# Administrative Boundaries API Quickstart

Use this guide to find boundaries at a point, read their identifiers, and retrieve a boundary with Administrative Boundaries v1.

## Before you begin

You need:

- A [Geoscape Hub](https://hub.geoscape.com.au) application with Administrative Boundaries API access
- The application's Consumer Key
- A terminal with `curl` and `jq` installed

Follow [Authentication](/guides/authentication) to create an application and find its credentials.

## 1. Set your Consumer Key

```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 for these requests. The base URL is `https://api.psma.com.au/v1/administrativeBoundaries`.

## 2. Find boundaries at a point

Choose one or more layers and send their names in a single comma-separated query value. This request retrieves locality and Commonwealth electoral attributes without polygon coordinates:

```shell
BOUNDARY_RESULT=$(curl --fail-with-body --get \
  "https://api.psma.com.au/v1/administrativeBoundaries/findByPoint" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "latitude=-35.32556759" \
  --data-urlencode "longitude=149.149937769" \
  --data-urlencode "layers=localities,electoralBoundariesCommonwealth" \
  --data-urlencode "excludeGeometry=true")

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

- `latitude`, `longitude`, and `layers` are required
- Input coordinates use GDA94 (EPSG:4283) unless you supply a supported `Content-Crs` header. See [CRS & GDA2020](/guides/gda-2020)
- `excludeGeometry=true` keeps feature attributes and returns a geometry with `coordinates: [null, null]`

## 3. Read the result

A successful request returns `200` with a `FeatureCollection`. This abbreviated example illustrates the locality result. Live data can differ:

```json
{
  "type": "FeatureCollection",
  "query": [149.149937769, -35.32556759],
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "MultiPolygon", "coordinates": [null, null]},
      "properties": {
        "layer": "locality",
        "localityPid": "LOC4D979CF6E3C5",
        "localityName": "GRIFFITH",
        "state": "ACT"
      }
    }
  ],
  "messages": []
}
```

Check these fields before using the result:

| Field | What it tells you |
| --- | --- |
| `features` | The returned boundaries. An empty array means no features were found |
| `features[].properties.layer` | Which boundary type the feature represents. The `localities` request value returns `layer: "locality"` |
| The layer's primary PID | The identifier to use for a follow-up lookup |
| `messages` | Layers with no result are reported as `Layer '{layer}' not found.` |
| `attribution` | The attribution text to retain with the data |

Missing layers do not make the request fail. For example, an ACT point has no Local Government Area result. See [Boundary Layers](/guides/admin-boundaries/layers) for values, primary identifiers, and coverage notes.

## 4. Retrieve a boundary by identifier

Use the primary feature PID from the response. A polygon PID is a different identifier and is not the lookup key. The following request retrieves the matched locality with geometry:

```shell
LOCALITY_PID=$(printf '%s\n' "$BOUNDARY_RESULT" | jq -r \
  '.features[] | select(.properties.layer == "locality") | .properties.localityPid' | head -n 1)

if [ -n "$LOCALITY_PID" ]; then
  curl --fail-with-body --get \
    "https://api.psma.com.au/v1/administrativeBoundaries/findByIdentifier" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/json" \
    --data-urlencode "identifier=$LOCALITY_PID" \
    --data-urlencode "layers=localities" \
    --data-urlencode "excludeGeometry=false"
fi
```

- Copy the identifier's casing exactly
- A feature can have several polygons, so inspect all returned features
- Geometry coordinate pairs are in `[longitude, latitude]` order for the default response CRS
- Use `Accept-Crs` to request another response CRS. It does not change the input CRS
- SEIFA features contain attributes without polygon coordinates, even when geometry is requested

<span id="transaction-usage-and-errors"></span>

## Credit usage and errors

The API uses 1 credit per returned feature without geometry and 4 per returned feature with geometry. Request only the layers and geometry you need. Keep the response's attribution. See [Attribution](/guides/attribution) and [Rate Limiting](/guides/rate-limiting).

- For `400`, check required parameters, coordinate values, layer names, and CRS headers
- For `401` or `403`, check the Consumer Key and application access
- A no-match lookup returns `200` with an empty `features` array and layer messages
- For `429` or transient `500` errors, follow [Error Handling](/guides/errors)

## Next steps

- [Choose boundary layers and identifiers](/guides/admin-boundaries/layers)
- [Find boundaries at a point](/reference/administrative-boundaries-v1-admin-bounds#find-by-point-2)
- [Find boundaries by identifier](/reference/administrative-boundaries-v1-admin-bounds#find-by-identifier-2)