On this page

Copy page

Documentation

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 application with Administrative Boundaries API access
• The application's Consumer Key
• A terminal with curl and jq installed

Follow Authentication to create an application and find its credentials.

1. Set your Consumer Key

Code
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:

Code
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
• 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:

Code
{
  "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 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:

Code
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

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 and 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

Next steps

• Choose boundary layers and identifiers
• Find boundaries at a point
• Find boundaries by identifier