Search Parcels

Submit a cadastral parcel search. Accepts a GeoJSON FeatureCollection of point geometries (as a JSON body) or a file upload containing point geometries.

The API routes each point to the appropriate national cadastral service based on its location, retrieves the parcel polygons that contain or surround each point, and returns them in a unified format.

Use Cases

  • Look up official land boundaries for a set of sourcing coordinates.
  • Find the cadastral parcel polygons that cover your farm or facility locations.
  • Upload a file of coordinates and retrieve parcel data in bulk.

How it works

  1. You submit point geometries (inline JSON or file upload).
  2. The API identifies the country for each point and routes it to the appropriate national cadastral service.
  3. Each service returns the parcel polygon(s) containing or nearest to the point.
  4. Results are unified into a standard format with parcel boundaries, area, and raw properties.
  5. For small requests (โ‰ค 500 uncached points, JSON body), results are returned synchronously. Otherwise a background task is created โ€” poll GET /cadastral/tasks/:id until complete, then fetch results via GET /cadastral/parcels/results/:id.
  6. If location_type is provided, successful results are automatically ingested as supply chain locations after the search completes.

Input modes

JSON body (Content-Type: application/json)

Send an inline GeoJSON FeatureCollection. Points are processed immediately if there are 500 or fewer uncached points, otherwise processing is offloaded to a background task.

File upload (Content-Type: multipart/form-data)

Upload a file containing point geometries as a single multipart field named file. Supported formats: CSV, JSON, NDJSON, GeoJSON, Parquet, GeoPackage, Shapefile (ZIP), XLSX, XLS.

File uploads are always processed asynchronously: the API returns a 202 Accepted immediately with a task envelope and a Location header pointing at the result endpoint. Poll the task's status link until it reaches a terminal state, then fetch results from GET /cadastral/parcels/results/:id.

curl

curl -X POST "$BASE_URL/cadastral/parcels/search" \
  -H "x-api-key: $API_KEY" \
  -F "file=@points.csv"

Successful response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: /cadastral/parcels/results/a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "meta": {},
  "links": {
    "self": "/cadastral/parcels/search",
    "status": "/cadastral/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "data": {
    "type": "parcel_search_task",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "attributes": {
      "overall_status": "processing",
      "source_file": "points.csv",
      "created_at": "2026-03-15T10:30:00.000Z"
    },
    "links": {
      "self": "/cadastral/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}

Note: The 202 response intentionally omits the inline rate_limits meta. The worker hasn't parsed the file or counted points against your quota by the time the 202 returns, so any remaining value here would be pre-request. Call GET /rate-limits after the task reaches a terminal status to see the post-charge state, or read per-point failures from the task results.

Example file payloads

CSV โ€” header row + one row per point (longitude, latitude):

longitude,latitude,name,ref
-86.158068,39.768403,Site A,S-001
-123.1207,49.2827,Site B,S-002

Any extra columns are preserved in input_properties on the corresponding result row, so you can ship reference IDs, tags, or business attributes alongside the coordinates.

GeoJSON โ€” standard FeatureCollection:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-86.158068, 39.768403] },
      "properties": { "name": "Site A", "ref": "S-001" }
    }
  ]
}

NDJSON โ€” one Feature per line:

{"type":"Feature","geometry":{"type":"Point","coordinates":[-86.158068,39.768403]},"properties":{"ref":"S-001"}}
{"type":"Feature","geometry":{"type":"Point","coordinates":[-123.1207,49.2827]},"properties":{"ref":"S-002"}}

Shapefile โ€” ZIP the .shp, .shx, .dbf (and optional .prj) into a single archive and upload that.

Polling for completion

curl -H "x-api-key: $API_KEY" "$BASE_URL/cadastral/tasks/$TASK_ID"
# โ€ฆpoll until overall_status is "completed", "completed_with_errors", or "failed"

curl -H "x-api-key: $API_KEY" "$BASE_URL/cadastral/parcels/results/$TASK_ID?page[number]=1&page[size]=100"

See Get Task Status and Get Results for the full response shapes.

Field semantics

Only the file field is read on this endpoint โ€” additional form fields are ignored. Auto-ingest, output_crs, and tags are JSON-body-only; submit those via the JSON-body path if you need them.

Geometry handling

Any GeoJSON geometry type is accepted. Non-Point geometries (Polygon, LineString, etc.) have their centroid computed and used as the lookup point. The original geometry is preserved in input_properties.original_geometry.

Auto-ingest

If location_type is provided in the request, the system automatically ingests successful parcel results as plots or sheds after the search completes. No separate ingest step needed.

Nearest parcel (match_radius_m)

Cadastral lookup is point-in-polygon โ€” it returns the parcel whose boundary contains the point. But a GPS coordinate collected in the field often lands on a road, a right-of-way, or a sliver between parcels, where no parcel contains it even though a real parcel sits a few metres away. To avoid an unnecessary miss (and an unnecessary trip to the forest fallback), the API also considers parcels within a radius of the point and returns the closest one.

  • match_radius_m โ€” how far (metres) to look for the nearest parcel when none contains the point. Default 100. Range 0โ€“1000. Set 0 to restore strict point-in-polygon (containing parcel only).
  • The nearest parcel is chosen by true geometry distance: a parcel that contains the point always wins (distance 0); otherwise the closest parcel within the radius is returned.
  • This is free โ€” the provider returns the containing and nearby parcels in the same billable request (cadastral services bill per lookup, not per parcel). Every parcel returned within the radius is cached, so a later point landing in any of them is a cache hit.

Each result row carries matched_distance_m so you can tell an exact hit from a nearby match:

matched_distance_mMeaning
0The point is inside the returned polygon โ€” a containing parcel (or a forest segment, see below).
> 0No parcel contained the point; the nearest parcel within match_radius_m was returned, this many metres away.
nullNo polygon was matched (a failed / unmatched point).

Backward-compatible: a point that already had a containing parcel behaves exactly as before (that parcel is returned, matched_distance_m: 0). Only points that previously returned nothing change โ€” they now resolve to the nearest parcel within the radius instead of falling through to the forest fallback.

Request example (explicit radius; omit for the 100 m default):

{
  "type": "FeatureCollection",
  "match_radius_m": 100,
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-86.078833, 34.118966] },
      "properties": { "ref": "S-001" }
    }
  ]
}

Notes:

  • JSON-body only (like output_crs, forest_fallback, auto-ingest, and tags); the file-upload path uses the 100 m default.
  • Runs before the forest fallback: a point only falls back to a canopy polygon when no parcel contains it or sits within match_radius_m.

Forest fallback (automatic)

Cadastral parcel data is only available for the US and supported Canadian provinces (today British Columbia), and even inside that footprint some points have no parcel. By default the API automatically resolves any such point to a canopy polygon derived from imagery instead of failing โ€” the same canopy method as geometry_source="segmentation" (see below). This supplements legal parcels; it does not replace them: cadastral is tried first, and only points with no parcel fall back. Pass "forest_fallback": false to opt out (no-parcel points then fail).

A point is diverted to the fallback in exactly two cases:

  1. Outside cadastral coverage โ€” the point is outside every national cadastral service's footprint (today: US, and Canada โ€” British Columbia). With fallback off these fail with Unsupported country โ€ฆ.
  2. Genuine no-parcel miss โ€” the point is inside the cadastral footprint but the provider found no parcel containing it nor any within match_radius_m (see Nearest parcel above).

Transient, upstream, and rate-limit errors are not diverted โ€” those stay hard failures so they remain retry-worthy and aren't silently downgraded to a forest polygon.

For each diverted point the API derives the canopy plot from imagery (AEF watershed for the boundary, ESRI Living Atlas land cover to restrict to canopy, Overture roads/waterways to split the segment), smoothed to a natural outline. A returned polygon becomes a normal completed result; a point with no eligible canopy nearby becomes a failed result.

Fallback results are distinguishable from real cadastral parcels on the Get Results response:

FieldCadastral parcelForest fallback (canopy)
parcel_idprovider parcel idforest:{lon},{lat}:{year}
country_codeISO code (e.g. US)"" (empty)
area_sqmparcel areanull
matched_distance_m0 (containing) or the offset to the nearest parcel0 (the point is inside the segment)
raw_properties.sourceโ€”"aef-watershed-canopy"
raw_properties.source_yearโ€”the segmented year (see year below)

Request example (fallback is on by default; shown explicitly here):

{
  "type": "FeatureCollection",
  "forest_fallback": true,
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-60.0, -3.0] },
      "properties": { "ref": "BR-1" }
    }
  ]
}

Notes:

  • On by default; pass "forest_fallback": false to disable (no-parcel points then fail).
  • JSON-body only (like output_crs, auto-ingest, and tags).
  • The fallback returns the same canopy geometry as geometry_source="segmentation" โ€” the only difference is when it runs (per-miss vs every point).
  • A whole-batch fallback outage fails only the diverted points; already-matched cadastral points are unaffected.

Vintage (year)

The imagery paths (fallback and segmentation) segment from annual AlphaEarth embeddings + ESRI land cover, and the latest complete year is the prior year (currently 2025), not real-time. So a polygon reflects canopy as of that vintage. For ground that changed recently โ€” e.g. a stand harvested this year โ€” segmenting the latest year may miss the canopy. Pass "year": <YYYY> (a year before the harvest) to segment the pre-harvest canopy instead. Omit it for the latest available year. year is ignored by the pure cadastral lookup.

Segmentation (geometry_source)

geometry_source selects where each point's geometry comes from:

ValueBehaviour
"cadastral" (default)Regrid / BC-WFS parcel lookup โ€” today's behaviour, unchanged. forest_fallback still applies per-miss.
"segmentation"Skip the cadastral lookup entirely and derive every point's geometry from imagery segmentation.

With "segmentation", AEF watershed provides the plot-boundary texture, ESRI Living Atlas land cover restricts it to canopy, and Overture roads/waterways split the segment so a plot never spans a road. The point's own forest segment is returned when the point is on forest; otherwise the nearest canopy-covered segment is returned. A point that lands on no segmentable canopy (โ‰ฅ 0.1 ha) returns a per-point miss (null geometry) rather than a forced polygon.

Use this when the cadastral parcel is unhelpful โ€” no county data, or an over-large ownership tract โ€” and a forest-stand boundary is wanted instead.

Segmentation results carry raw_properties.source of "aef-watershed-canopy".

Request example:

{
  "type": "FeatureCollection",
  "geometry_source": "segmentation",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-86.15486, 34.33883] },
      "properties": { "ref": "FP-1" }
    }
  ]
}

Notes:

  • Additive & backward-compatible: omitting geometry_source (or sending "cadastral") preserves the existing parcel behaviour exactly.
  • Mutually exclusive with the cadastral path; forest_fallback is moot when geometry_source is "segmentation".
  • JSON-body only (like output_crs, forest_fallback, auto-ingest, and tags).

Caching

Results are cached globally. Repeated searches for the same area reuse cached data, reducing latency and external API usage.

Depending on your plan, points served from cache may or may not count toward your rate limit โ€” see Rate limiting below.

Rate limiting

Every cadastral search counts against a per-service quota on your organisation. Each cadastral service (US, Canada โ€” BC, etc.) has its own independent window. When a request is dispatched, each point is routed to one service and counts against that service's quota only.

What happens when you hit the limit

Rate-limit enforcement is per-point, not per-request. A batch that partially exceeds your quota does not fail outright โ€” points that fit within the remaining budget are processed normally, and points that would exceed it come back as Failed results inside the same task.

Look for these messages in the reason field of a failed result (see Get Results):

Reason textMeaning
Rate limit exceeded โ€” retry after NsYour organisation's quota for this service is exhausted. Retry after N seconds.
Cadastral capacity ceiling reached โ€” retry after NsThe platform-wide capacity for this service is temporarily saturated. Retry after N seconds.
Service misconfigured โ€” no rate-limit quota set for this backend. Contact support.Your access is provisioned but no quota has been configured. Contact support โ€” this is not something you can resolve from the API.
Cadastral access is no longer enabled for this organisationAccess was disabled between submission and processing. Contact support.

Successful and failed points share the same task โ€” you don't need to resubmit successful ones, just the failed ones once the retry window passes.

What counts toward the limit

  • Uncached points always count. Each point sent to an external cadastral service consumes one unit of quota for that service.
  • Cached points may also count, depending on your plan. Some plans charge based on total points processed (cached + uncached); others charge only for upstream calls. Check your plan or contact support if you're unsure.

Monitoring your usage

You can read your current quota state in two ways.

Inline on every synchronous (200) response

Every successful synchronous response (JSON-body path, 200) includes a rate_limits array under meta. The array is always present (empty when no service has an active quota), so client code never needs to defensively check for the key.

File upload (202 async) responses deliberately omit this meta โ€” by the time the API returns the 202, the background worker has not yet parsed the file and counted points against your quota. Reporting a remaining value at that moment would be strictly pre-request and could mislead you into oversending. Use GET /rate-limits after the task reaches a terminal status to see the post-charge state.

{
  "meta": {
    "rate_limits": [
      {
        "service_label": "US Cadastral",
        "max_requests": 10000,
        "remaining": 8766,
        "resets_at": "2026-06-14T00:00:00Z"
      }
    ]
  },
  "data": { /* the task resource */ }
}
FieldDescription
service_labelThe display name of the cadastral service this entry belongs to.
max_requestsThe maximum number of requests allowed per window.
remainingHow many requests you can still make before the window resets.
resets_atISO 8601 timestamp when the window rolls over. null if no requests have been counted yet.

Only services that are enabled and configured for your organisation appear in the array. An empty array means no cadastral service has been provisioned with a quota โ€” contact support.

Use this to:

  • Read remaining on every synchronous response and decide whether to send another batch immediately.
  • Time follow-up requests around resets_at when remaining is low.

Dedicated endpoint

For a full snapshot โ€” including services you haven't called yet, the window length (window_seconds), and current usage (current_usage) โ€” call GET /rate-limits directly. See Get Rate Limits for the full response shape.

Use the inline meta.rate_limits for the hot path (decide-and-retry around every response), and GET /rate-limits when you need to plan ahead.

Planning batches

  • First request of a session โ€” call GET /rate-limits to know your starting headroom across every service.
  • Subsequent JSON-body requests โ€” read meta.rate_limits[].remaining from the previous synchronous response and use it to decide the next batch size, with no extra round-trip.
  • After a file upload โ€” the 202 response doesn't carry quota state. Either call GET /rate-limits after the task completes, or wait for the task result and inspect any Failed rows for retry after Ns hints.
  • Partial-failure retries โ€” when a task returns with some Failed rate-limit results, schedule the retry to fire after the latest retry after Ns value seen in those results.

Required scope: parcels:write