---
title: "Search cadastral parcels for a property"
method: GET
path: "/properties/{property_id}/parcel-search"
tags: ["Properties"]
---

# Search cadastral parcels for a property

`GET /properties/{property_id}/parcel-search`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/properties/{property_id}/parcel-search`
- Auth: HTTP bearer

Queries the state's externally operated public cadastre for parcels at or near a point.
The state is read from the property's address.
Send latitude and longitude, or an address. When both are sent, the coordinates are
used and the address is ignored. The address is not stored, logged or used as a cache key.
The property's PIC is the farmer's own declaration. It is not looked up and it is not sent
to the cadastre.

NSW, VIC, QLD and TAS return candidates. Each has external_id, lot, plan, lot_plan, area_ha
and GeoJSON geometry. SA, WA, NT and ACT answer 422 parcel_search_unsupported. Draw the
boundary with updatePropertyBoundary. PICs are farmer-declared identifiers, not parcel-search inputs.

A blank state is 422 parcel_search_state_required. Put the state in place_label or location. An address
that does not resolve is 422 parcel_geocode_failed. With no geocoder configured, an address
is 422 parcel_geocode_unavailable. Send coordinates instead. A state service that does not
answer is 422 parcel_search_unavailable.

Plain JSON, not JSON:API. Needs read access to the property's records. A property shared
publicly or by link does not share its parcels. Not cached on the response. The server
keeps the candidates for twelve hours so attachParcelsToProperty can store the geometry
it fetched.

## Path parameters

- `property_id` string, required

## Query parameters

- `latitude` string
- `longitude` string
- `address` string

## Response `200`

Candidate parcels. An empty parcels array means the point hit none.

- ParcelSearchResponse
  - `property_id` string, uuid, required
  - `state` string, nullable
  - `latitude` number: The point that was searched. An address is resolved to this and is not echoed.
  - `longitude` number
  - `parcels` Parcel[], required
    - `id` string, uuid, nullable: Present once the parcel is stored on the property. Omitted on a search candidate.
    - `external_id` string, required: The cadastral id from that state's parcel service. NSW lot/DP, a Vicmap SPI, a Queensland lotplan, or a Tasmanian PID.
    - `state` 'NSW' | 'VIC' | 'QLD' | 'SA' | 'WA' | 'TAS' | 'NT' | 'ACT', nullable
    - `source` string, nullable: Which public service the geometry came from. nsw_spatial, vicmap_parcel, qld_dcdb or tas_list.
    - `lot` string, nullable
    - `plan` string, nullable
    - `lot_plan` string, nullable: Lot and plan as one label, when the service provides them.
    - `area_ha` number, nullable: Area in hectares, from the parcel service when it publishes one.
    - `geometry` ParcelGeometry, required: GeoJSON in WGS84, longitude first. A Polygon, or a MultiPolygon when the parcel has more than one part. Holes are not stored.
      - `type` 'Polygon' | 'MultiPolygon', required
      - `coordinates` unknown[], required
        - unknown
  - `_meta` OnboardingMeta
    - `onboarding` Onboarding: Where the account in scope is in setting up a farm. A suggestion: reads are never refused because a step is missing. `next_step` is null once every step is done.
      - `status` 'not_started' | 'in_progress' | 'complete'
      - `completed_steps` string[]
      - `next_step` 'create_team' | 'create_property' | 'map_boundaries' | 'map_paddocks' | 'create_blocks' | 'add_mobs' | 'first_record', nullable
      - `skill` string
      - `skill_url` string
      - `agent_hint` string: Plain-language instruction, including a short fallback the agent can follow without the skill.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: The state is blank or unsupported, the point or address cannot be used, or the cadastre did not answer.

## Changes

- **2026-10-30** `92c4663a1266`: 6 warning, 6 info
  - removed the optional property `_meta` from the response with the `422` status (media type: application/json)
  - removed the optional property `_meta` from the response with the `422` status (media type: application/vnd.api+json)
  - removed the optional property `errors/items/onboarding` from the response with the `422` status (media type: application/json)
  - removed the optional property `errors/items/onboarding` from the response with the `422` status (media type: application/vnd.api+json)
  - …8 more
- **2026-10-24** `e285768a8f1d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/purplegrain/apis/purple-grain-api/changes/properties/:property_id/parcel-search/get.md)

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) - [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/e32f34ba218b?raw)