Skip to main content
API reference

OpenAPI specification

Download the customer HTTP contract for API tools and clients.

The downloadable OpenAPI 3.1 contract describes the API paths, the API-key header, query parameters, GeoJSON responses, and errors.

Download the OpenAPI JSON specification

Import the JSON into an API client or documentation tool and set its server URL to your deployment's base URL. The default server is the local development URL http://localhost:8000.

Scope​

The specification includes GET /v1/geocode, GET /v1/search, GET /v1/reverse, GET /v1/autocomplete, and GET /v1/place. It excludes internal health and administration endpoints, account-management endpoints, and Google/HERE APIs.

The apikey security scheme describes authentication for server keys and public browser tokens. Browser tokens require an allowed Origin and authorize autocomplete and place lookup only; an origin or scope denial returns 403. Authentication and rate-limit error bodies may use message instead of error. No production host is assumed.

Validation beyond the schema​

Some service rules need validation beyond what the schema expresses:

  • Parameter values are trimmed and limited to 256 bytes, not characters.
  • Unknown and repeated parameters are rejected with 400.
  • geocode requires street and at least one of city, state, or zip.
  • bbox minimums must not exceed maximums, and near/bbox coordinates must be in range.
  • exclude_sources accepts up to 32 names of 1–64 bytes; place accepts up to 20 ids.

The x-maxBytes extension is informational and may not be enforced by imported tooling. SDK-only options such as session tokens and fallback providers are absent from the HTTP contract.

Consult the geocode, search, reverse, autocomplete, and place lookup references for the exact contract.