Getting started with the Airfree Cadastre API in 30 minutes

This tutorial takes you from nothing to a working cadastral integration in about half an hour. We will authenticate, fetch a parcel, filter a set of parcels, and kick off a bulk export — the four things almost every integration needs. Everything is in Python, but the calls are plain HTTP, so any language works.

Step 1 — Authenticate with client credentials

The Cadastre API uses OAuth 2.0 client credentials for server-to-server access. Create a client in your workspace settings, note the client ID and secret, and exchange them for a short-lived access token. Treat the secret like a password — keep it out of source control and out of the browser.

import requests

token = requests.post(
    'https://airfree.au/auth/realms/airfree/protocol/openid-connect/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
    },
).json()['access_token']

headers = {'Authorization': f'Bearer {token}'}

Step 2 — Fetch a parcel as GeoJSON

With a token in hand, retrieving a parcel is a single GET. The API returns standard GeoJSON, so the geometry drops straight into any spatial library or map client without translation.

r = requests.get(
    'https://airfree.au/api/v1/cadastre/parcels/ABC123',
    headers=headers,
)
parcel = r.json()
print(parcel['properties']['tenure'], parcel['geometry']['type'])

Step 3 — Filter by tenure and area

Most real queries are not for one known parcel but for a set that matches a rule. The items endpoint accepts CQL2 filters, so you can ask for, say, every freehold parcel over a thousand square metres in one request and page through the results.

params = {
    'filter': "tenure = 'freehold' AND area_sqm > 1000",
    'limit': 100,
}
r = requests.get(
    'https://airfree.au/api/v1/cadastre/parcels/items',
    headers=headers, params=params,
)
features = r.json()['features']

Step 4 — Stream a bulk export

When you need the whole set rather than a page, use the async job endpoint. You POST the query, receive a job ID, poll until it is ready, and download the result. This keeps large exports off the synchronous request path and lets the server stream gigabytes without timing out.

job = requests.post(
    'https://airfree.au/api/v1/cadastre/exports',
    headers=headers,
    json={'filter': "tenure = 'freehold'", 'format': 'geojson'},
).json()

# poll job['id'] until status == 'complete', then GET job result URL

Where to go next

You now have the four primitives — authenticate, fetch, filter, export — that almost every cadastral integration is built from. From here the natural next steps are writing back validated geometries through the Cadastre Engine, subscribing to change webhooks so your copy stays current, and adding the layer-level permission scopes your organisation needs. Each is documented in the developer reference.