Loading...
Sign in to see the examples with your own API key.

Discovery

Three endpoints describe the API to tools and coding agents (Claude Code and others), so they can build correct requests without reading these pages. None of them needs a key, and none counts towards your usage.

API catalog

The entry point for automated tooling, following the IETF API Catalog draft. It returns a linkset pointing at the OpenAPI description, the interactive API reference, the manifest and the examples below.

Request

GET https://api.getaddress.io/.well-known/api-catalog

Response (application/linkset+json)

{
    "linkset": [
        {
            "anchor": "https://api.getaddress.io",
            "rel": "service-desc",
            "href": "https://api.getaddress.io/openapi/v3.json",
            "type": "application/vnd.oai.openapi+json;version=3.0",
            "title": "getaddress.io API - OpenAPI 3.0 description"
        },
        {
            "anchor": "https://api.getaddress.io",
            "rel": "service-doc",
            "href": "https://api.getaddress.io/scalar",
            "type": "text/html",
            "title": "Interactive API reference (Scalar)"
        },
        {
            "anchor": "https://api.getaddress.io",
            "rel": "service-meta",
            "href": "https://api.getaddress.io/api/info",
            "type": "application/json",
            "title": "Agent-friendly API manifest"
        },
        {
            "anchor": "https://api.getaddress.io",
            "rel": "related",
            "href": "https://api.getaddress.io/api/examples",
            "type": "application/json",
            "title": "Worked request/response examples"
        }
    ]
}

Manifest

What the API does, where its OpenAPI description and reference live, how to authenticate and the dictionary of error codes. An agent needs to read it once per session. Branch on an error's code, never on its wording.

Request

GET https://api.getaddress.io/api/info

Response (descriptions shortened)

{
    "name": "getaddress.io API",
    "description": "Australian address look-up on G-NAF: ...",
    "version": "v1",
    "openapi_url": "https://api.getaddress.io/openapi/v3.json",
    "documentation_url": "https://api.getaddress.io/scalar",
    "examples_url": "https://api.getaddress.io/api/examples",
    "authentication": {
        "type": "api-key",
        "description": "Every request must carry an API key, passed as the 'api-key' query string parameter ..."
    },
    "error_codes": [
        { "code": "unauthorized", "status": 401, "description": "Missing or invalid api-key query string parameter." },
        { "code": "forbidden", "status": 403, "description": "The credential is valid but does not grant this operation ..." },
        { "code": "domain-token-scope", "status": 403, "description": "A domain token was used outside the address look-up routes ..." },
        { "code": "domain-token-rate-limit", "status": 429, "description": "The domain token's per-visitor or token-wide limit was reached ..." },
        { "code": "service-unavailable", "status": 503, "description": "The address data or the key store was briefly unreachable ..." }
    ]
}

Examples

Copy-pasteable requests and responses for Autocomplete (GET and POST), Get, Usage and the two most common errors. Each example has an id, the method and path, an optional request_body, and the response_status and response_example to expect. Paths carry YOUR-API-KEY where your key goes.

Request

GET https://api.getaddress.io/api/examples

Response (first example shown)

{
    "examples": [
        {
            "id": "autocomplete",
            "title": "Suggest addresses for a partial address",
            "description": "Returns up to 'top' suggestions (max 6) for what the user has typed so far. ...",
            "method": "GET",
            "path": "/autocomplete/12%20chapel%20st%20melb?api-key=YOUR-API-KEY&top=6",
            "request_body": null,
            "response_status": 200,
            "response_example": {
                "suggestions": [
                    { "address": "3/12 Chapel Street, Melbourne VIC 3000", "url": "/get/GAVIC421677561", "id": "GAVIC421677561" }
                ]
            }
        }
    ]
}
Top