Structured (component) geocode API

Geocode an address by its discrete components (street, city, county, state, postalcode, country) instead of one free-text string, returning normalized address components, ISO 3166-2 state code, and a bounding box. Distinct from free-text geocoding: structured queries are more precise and disambiguate ambiguous names. Answers 'geocode this structured address', 'lat/lon for street+city+country', 'bounding box of an address'.

Price$0.01per request

MethodPOST

Route/v1/data/places-structured-geocode

StatusLive

MIME typeapplication/json

Rate limit60/minute

Cache86400s public

dataplacesgeocodestructuredaddressnominatimosmiso-3166-2

API URLhttps://x402.hexl.dev/v1/data/places-structured-geocode

Integration docs

Example request

{
  "street": "Pennsylvania Avenue",
  "city": "Bremerton",
  "country": "USA",
  "limit": 1
}

Example response

{
  "query": {
    "street": "Pennsylvania Avenue",
    "city": "Bremerton",
    "county": null,
    "state": null,
    "postalcode": null,
    "country": "USA"
  },
  "count": 1,
  "results": [
    {
      "displayName": "Pennsylvania Avenue, Bremerton, Kitsap County, Washington, 98314, United States",
      "latitude": 47.5701099,
      "longitude": -122.6420442,
      "placeType": "residential",
      "addressType": "road",
      "importance": 0.053393,
      "boundingBox": {
        "minLat": 47.5673508,
        "maxLat": 47.572869,
        "minLon": -122.6420691,
        "maxLon": -122.642043
      },
      "components": {
        "houseNumber": null,
        "road": "Pennsylvania Avenue",
        "city": "Bremerton",
        "county": "Kitsap County",
        "state": "Washington",
        "stateCode": "US-WA",
        "postcode": "98314",
        "country": "United States",
        "countryCode": "US"
      }
    }
  ]
}

Input schema

{
  "type": "object",
  "properties": {
    "street": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "county": {
      "type": "string"
    },
    "state": {
      "type": "string"
    },
    "postalcode": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 5
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}