API

REST API for address normalization and optional OSM matching.

Endpoints

Endpoint	Methods	Description
`/oauth/token`	`POST`	OAuth2 token endpoint. Supports `grant_type=password` and `grant_type=client_credentials`.
`/api/normalize`	`POST`, `GET`	Normalize a free-text address. Optional match via `?match=true`. For GET use `?address=...`.
`/api/normalize/structured`	`POST`, `GET`	Normalize a structured address (fields). Optional match via `?match=true`.

1. OAuth token

POST /oauth/token (application/x-www-form-urlencoded)

Grant: password

grant_type=password&username=admin@example.com&password=YOUR_PASSWORD

Grant: client_credentials

grant_type=client_credentials&client_id=YOUR_API_KEY&client_secret=YOUR_PASSWORD

Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Normalize free-text address

POST or GET /api/normalize

Send a single address string. It is parsed into components. If match=true, an OpenStreetMap building lookup is performed and the first result is returned.

Request (POST, application/json)

{
  "address": "47 Glen Avenue, Newton, MA 02459"
}

Query: match (optional, boolean, default false). For GET pass address as a query param.

3. Normalize structured address

POST or GET /api/normalize/structured

{
  "housenumber": "47 2",
  "street": "Glen Avenue",
  "city": "Newton",
  "county": "Middlesex",
  "state": "MA",
  "postcode": "02459",
  "countrycode": "US"
}

Supported fields: countrycode, state, county, city, postcode, housenumber, street. Required: housenumber and street, plus at least one of city, state, or postcode.

General

Authentication: send Authorization: Bearer <access_token>. Legacy ?key=... still works for now.
Geographic limits: Results are filtered to the configured country (default US) and, when state-test mode is on, to a single state (e.g. MA).
OpenStreetMap: Matching uses a structured lookup against OpenStreetMap building features. When multiple results are returned, only the first is used.
Errors: 400 for missing/invalid input; 500 with {"error": "message"} on server errors.