On this page

Copy page

Documentation

Buildings API Quickstart

Use this guide to find building footprints, retrieve a building by ID, and follow its address relationships. The current reference is labelled v2.1, but requests use /v2/buildings.

Before you begin

You need:

• A Geoscape Hub application with Buildings API access and a plan that permits premium data, such as Starter or a higher current paid plan
• The application's Consumer Key
• A terminal with curl and jq installed

Follow Authentication if you need to create an application or find its key. Returned buildings consume credits. Check Additional Properties before requesting extra attributes.

1. Set your Consumer Key

Store the key outside source code. Replace the sample value with your application's 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.

2. Find buildings near a point

Send latitude and longitude in GDA94 (EPSG:4283). This example searches a 90-metre radius and requests up to 10 buildings:

Code
BUILDINGS_RESULT=$(curl --fail-with-body --get \
  "https://api.psma.com.au/v2/buildings/findByPoint" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "latitude=-33.917156" \
  --data-urlencode "longitude=151.063934" \
  --data-urlencode "radius=90" \
  --data-urlencode "limit=10")

printf '%s\n' "$BUILDINGS_RESULT" | jq .

• Omit radius to find footprints intersecting the point itself
• Supply an integer radius from 1 to 500 metres to find footprints intersecting a circle
• Results are not ranked by distance, so the first feature is not necessarily the nearest building
• If no buildings match, the response is 404 with an error body rather than an empty successful collection

See Find by point for parameters and errors.

3. Read the result

A successful search returns 200 with a GeoJSON FeatureCollection served as application/json. Inspect the fields you need:

Code
printf '%s\n' "$BUILDINGS_RESULT" | jq '{
  totalArea,
  links,
  messages,
  buildings: [.features[] | {
    buildingPid: .properties.buildingPid,
    buildingArea: .properties.buildingArea,
    localityName: .properties.localityName,
    centroidLongitude: .properties.centroidLongitude,
    centroidLatitude: .properties.centroidLatitude
  }]
}'

Field	How to use it
features[].properties.buildingPid	Identifier for building lookups and relationship requests
features[].geometry	Roof outline as a MultiPolygon. Geographic coordinates use [longitude, latitude, z] order
features[].properties.buildingArea	Footprint area in square metres
features[].properties.totalFloorArea	Estimated total floor area in square metres, where available
totalArea	Sum of building areas on this page, not across every matched page
links.numberMatched and links.numberReturned	Total matches and the number returned on this page
messages	Request information, including pagination warnings

When using the data:

• Check for optional properties before reading them. Fields without values are omitted
• Read the Content-Crs response header to identify the coordinates' CRS
• Use Accept-Crs to request another response CRS. The default is GDA94. This does not change point-search input coordinates
• Preserve the top-level attribution text. See Attribution

4. Retrieve a building with height and roof data

Use a buildingPid from the search result. Request multiple additional properties in one comma-separated value:

Code
BUILDING_PID=$(printf '%s\n' "$BUILDINGS_RESULT" | jq -r '.features[0].properties.buildingPid // empty')

if [ -n "$BUILDING_PID" ]; then
  curl --fail-with-body --get \
    "https://api.psma.com.au/v2/buildings/$BUILDING_PID" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/json" \
    --data-urlencode "additionalProperties=height,roof"
else
  printf '%s\n' "No building ID returned. Review the search before making a lookup."
fi

The lookup also returns a FeatureCollection. Available height and roof objects appear inside each feature's properties. Missing additional data does not mean the building is missing.

You can add additionalProperties to the original search to avoid a separate building lookup. See Additional Properties for accepted values, availability, and costs.

5. Retrieve related addresses

Use the same building ID to retrieve relationship records:

Code
if [ -n "$BUILDING_PID" ]; then
  curl --fail-with-body --get \
    "https://api.psma.com.au/v2/buildings/$BUILDING_PID/building_address" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/json" \
    --data-urlencode "limit=10" \
    --data-urlencode "offset=0"
fi

• The response contains records, rather than features
• Use addressPid or addressDetailPid to identify the related address. Records can also include the address string and relationshipConfidence as a percentage
• Retrieve full address details through the Addresses API
• No relationships returns 200 with records: []. This does not establish whether the building exists
• Use /building_cadastre and /building_property for cadastral parcel and property relationships

Page through searches and relationship records

Searches and relationship endpoints support limit and offset:

• limit defaults to 100 and accepts 1 to 1,000
• offset defaults to 0
• Follow links.next while it is present. Resolve its relative URL against https://api.psma.com.au and include your authentication header on every request
• An offset beyond existing matches can return an empty page. Building collections can also include an offset warning in messages

The single-building lookup does not return pagination links.

Choose another search

Search by a related identifier

Use Find by identifier when you already have an address, property, or cadastral parcel ID. Supply exactly one of addressId, propertyPid, or cadastrePid:

Code
curl --fail-with-body --get \
  "https://api.psma.com.au/v2/buildings/findByIdentifier" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "addressId=GAQLD155997576" \
  --data-urlencode "limit=10"

Search a bounding box

Use Find by bounding box for a rectangular extent. Send four comma-separated coordinates in this order:

1. Bottom-left longitude
2. Bottom-left latitude
3. Top-right longitude
4. Top-right latitude

Code
curl --fail-with-body --get \
  "https://api.psma.com.au/v2/buildings/findByBoundingBox" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "bbox=149.12047,-35.28707,149.13689,-35.27529" \
  --data-urlencode "limit=10"

Use distinct corners within the supported Australian bounds: longitude 96 to 168 and latitude -45 to -8. A footprint can intersect the box without being entirely contained in it.

For background on coordinate ordering, see the GeoJSON bounding-box definition. For response CRS selection, see CRS & GDA2020.

If a request fails

Status	What to do
400	Correct missing parameters, invalid values, conflicting identifiers, or invalid CRS headers before retrying
401	Check the Consumer Key, application status, and Buildings API access
403	Check that the subscription permits premium-data access
404	Check the building ID or change the search extent. No-match service responses can have an empty messages array
429	Slow down and apply bounded backoff
500	Retry transient failures with bounded backoff. Check service status or contact support if failures persist

Service errors contain messages, requestTimeStamp, and requestDateTime. Gateway authentication and rate-limit errors can use different bodies. Inspect the HTTP status before parsing a success response. See Error Handling and Rate Limiting.

Next steps

• Choose additional properties
• Migrate legacy building fields
• Browse the Buildings reference