# Buildings API

Use this page to choose a building search or lookup, prepare your first request, and find guidance on footprints and attributes.

## When to use this API

Retrieve Australian building footprints, characteristics, and relationships to addresses, cadastral parcels, and properties.

Start with the [Buildings Quickstart](/guides/buildings/quickstart) to find buildings near a point, retrieve optional attributes, and follow address relationships. The current reference is labelled v2.1. Requests use `/v2/buildings`.

| You have… | Use |
| --- | --- |
| A building PID | [Building Feature](/reference/buildings-v2-1-building#building-feature) |
| Latitude and longitude | [Find by point](/reference/buildings-v2-1-search#find-by-point) |
| A rectangular search extent | [Find by bounding box](/reference/buildings-v2-1-search#find-by-bounding-box) |
| An address, property, or cadastre identifier | [Find by identifier](/reference/buildings-v2-1-search#find-by-identifier) |
| A building PID and a need for related records | [Building Addresses](/reference/buildings-v2-1-building#building-addresses), [Building Cadastre](/reference/buildings-v2-1-building#building-cadastre), or [Building Properties](/reference/buildings-v2-1-building#building-properties) |

For bulk data delivery, use the [Datasets API](/apis/datasets). For map tiles, use the [Maps API](/apis/maps).

**Access:** Use a Geoscape Hub application with Buildings API access and a plan that permits premium data. Optional attributes can add credit costs.

Send its Consumer Key directly in the `Authorization` header. See [Authentication](/guides/authentication) for application and tester setup.

## Responses

- Building geometry represents the roof outline as a `MultiPolygon`. Geographic coordinates use `[longitude, latitude, z]` order
- Building area is measured in square metres. `totalArea` sums the building areas on the current response page
- Follow `links.next` for paginated searches and relationships. A single-building lookup has no pagination links
- Read `messages` and retain the returned `attribution`

## Further guidance

- [Additional Properties](/guides/buildings/additional-properties): choose height, roof, and solar data and check credit costs
- [Field Migration](/guides/buildings/national-buildings-4-0): migrate legacy fields and additional-property requests
- [Buildings Technical Description](https://docs.geoscape.com.au/projects/buildings_guide/en/stable/#document-2_technical_description) and [Buildings Product Guide](https://docs.geoscape.com.au/projects/buildings_guide/en/stable/#document-1_overview): review coverage, capture methods, and dataset definitions
- [CRS & GDA2020](/guides/gda-2020): select input and response coordinate systems
- [Error Handling](/guides/errors), [Rate Limiting](/guides/rate-limiting), and [Attribution](/guides/attribution): apply shared integration requirements

## Versions

| Version | Reference |
| --- | --- |
| v2.1 (current) | [Endpoint reference](/reference/buildings-v2-1-building) |
| v1 (legacy) | [Endpoint reference](/reference/buildings-v1-attributes) |

Use the current version for new integrations. Legacy identifies an older version. Individual deprecated endpoints are marked in the reference.