# 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](https://hub.geoscape.com.au) 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](/guides/authentication) if you need to create an application or find its key. Returned buildings consume credits. Check [Additional Properties](/guides/buildings/additional-properties#credit-usage) 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:

```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.

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

```shell
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](/reference/buildings-v2-1-search#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:

```shell
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](/guides/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:

```shell
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](/guides/buildings/additional-properties) for accepted values, availability, and costs.

## 5. Retrieve related addresses

Use the same building ID to retrieve relationship records:

```shell
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](/apis/addresses)
- 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](/reference/buildings-v2-1-search#find-by-identifier) when you already have an address, property, or cadastral parcel ID. Supply exactly one of `addressId`, `propertyPid`, or `cadastrePid`:

```shell
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](/reference/buildings-v2-1-search#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

```shell
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](https://geojson.org/geojson-spec.html#bounding-boxes). For response CRS selection, see [CRS & GDA2020](/guides/gda-2020).

## 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](/guides/errors) and [Rate Limiting](/guides/rate-limiting).

## Next steps

- [Choose additional properties](/guides/buildings/additional-properties)
- [Migrate legacy building fields](/guides/buildings/national-buildings-4-0)
- [Browse the Buildings reference](/reference/buildings-v2-1-building)