# Land Parcels API Quickstart

Use this guide to find cadastre polygons at a point, read the result, and request planning data or related property polygons.

## Before you begin

You need a [Geoscape Hub](https://hub.geoscape.com.au/) application with Land Parcels API product access and its Consumer Key. Follow [Authentication](/guides/authentication) to set up your application.

```shell
export GEOSCAPE_API_KEY="YOUR_CONSUMER_KEY"
```

The header name is `Authorization`. Its value is the Consumer Key directly, without a `Bearer` prefix. The Consumer Secret is not used in these requests.

## 1. Find cadastre polygons at a point

Send latitude and longitude in GDA94 decimal degrees. Save the result for a related lookup. These examples use `curl` and `jq`:

```shell
PARCEL_RESULT=$(curl --fail-with-body --get \
  "https://api.psma.com.au/v1/landParcels/cadastres/findByPoint" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "latitude=-33.917156" \
  --data-urlencode "longitude=151.063934")

printf '%s\n' "$PARCEL_RESULT" | jq .
```

The request returns polygons that intersect the point. Add `radius` to search a surrounding area, from 1 to 500 metres. Use `/properties/findByPoint` for property polygons instead.

## 2. Read the result

A successful lookup returns a GeoJSON `FeatureCollection`:

| Field | Use |
| --- | --- |
| `features[].properties.cadastrePid` | Identify the cadastre for a later lookup or related-property search |
| `features[].properties.cadastrePolygonPid` | Identify this polygon. A cadastre PID can have multiple polygons |
| `features[].properties.parcelId` | Read the jurisdiction's parcel reference, such as a lot and plan |
| `features[].properties.area` | Read this polygon's area in square metres |
| `totalArea` | Read the sum of polygon areas on this response page, in square metres |
| `links.next` | Retrieve another page, when present |
| `messages` | Read information about the result |

Geometry coordinates use longitude,latitude order. Retain the returned `attribution`. See [Finding Parcels](/guides/land-parcels/parcels-and-planning) for identifier and base-parcel definitions.

A search with no matching parcels returns `404`. A page beyond the available features can return `200` with an empty `features` array when the search itself has matches.

## 3. Request planning data

On a paid plan with planning access, add `additionalProperties=planningBundle` to a cadastre request:

```shell
curl --fail-with-body --get \
  "https://api.psma.com.au/v1/landParcels/cadastres/findByPoint" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "latitude=-33.917156" \
  --data-urlencode "longitude=151.063934" \
  --data-urlencode "additionalProperties=planningBundle"
```

Planning attributes appear in `features[].properties.planningBundle`. The property is omitted when no planning data is available. Planning data is requested through cadastre endpoints.

## 4. Find related properties

Use a returned cadastre PID to find related property polygons:

```shell
CADASTRE_PID=$(printf '%s\n' "$PARCEL_RESULT" | jq -r '.features[0].properties.cadastrePid // empty')

if [ -n "$CADASTRE_PID" ]; then
  curl --fail-with-body --get \
    "https://api.psma.com.au/v1/landParcels/properties/findByIdentifier" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/json" \
    --data-urlencode "cadastrePid=$CADASTRE_PID"
else
  printf '%s\n' "No cadastre PID returned. Review the search before making a lookup."
fi
```

Supply exactly one related identifier per request. Property searches accept `addressId`, `cadastrePid`, or `contributorId`. Cadastre searches accept `addressId` or `propertyPid`.

## Usage and errors

- Each returned unique polygon PID uses 2 credits
- Each feature with returned planning data adds 1 credit
- Correct invalid parameters after `400`
- Resolve credentials or product access after `401` or `403`
- Check the identifier or broaden a search after `404`

See [Error Handling](/guides/errors) and [Rate Limiting](/guides/rate-limiting) for retries and request rates.

## Next steps

- [Choose parcel searches and planning data](/guides/land-parcels/parcels-and-planning)