API

REST API for address normalization and optional OSM matching.

Landing · Sign up · Sign in

Endpoints

EndpointMethodsDescription
/api/normalizePOST, GETNormalize a free-text address. Optional match via ?match=true. For GET use ?address=....
/api/normalize/structuredPOST, GETNormalize a structured address (fields). Optional match via ?match=true. For GET pass structured fields as query params.

1. 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)

Content-Type: application/json

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

Query: match (optional, boolean, default false) — if true, attempt OSM match and include best_result and photon_query.

Request (GET)

Query: address (required), match (optional).

Response (match=false)

{
  "input": "47 Glen Avenue, Newton, MA 02459",
  "components": {
    "house_number": "47",
    "road": "Glen Avenue",
    "city": "Newton",
    "state": "MA",
    "postcode": "02459"
  },
  "matched": false
}

Response (match=true)

Same fields plus best_result (first OpenStreetMap building: street, housenumber, postcode, city, state, country_code, lat, lon, osm_id, osm_type). matched is true if a result was found.

2. Normalize structured address

POST or GET /api/normalize/structured

Send address components. House number suffixes (e.g. 47a, 47 2, 47-2, 47 bis) are stripped for the OpenStreetMap lookup only.

Request

Content-Type: application/json. At least one field required.

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

Supported fields (POST body or GET query): house_number, housenumber, streetnumber, road, street, city, state, postcode, postalcode, countrycode. Use street or road; house_number/housenumber/streetnumber; postcode or postalcode.

Query: Same match parameter as above, plus any structured fields when using GET.

Response

Same shape as free-text: input, components, and when match=true, photon_query, best_result, matched.

General