API reference

Geocode an address

Find coordinates for a structured street address.

GET/v1/geocode

Send a house number and street with at least one of city, state, or ZIP. The response lists matching addresses with coordinates and a confidence score that compares each match with what you sent. For a single free-text line such as "11 Wall St, New York", use search instead.

Headers

Header	Required	Value
apikey	Yes	Your primary API key

Query parameters

streetstringrequired

House number and street, e.g. 11 Wall Street.

citystring

City. At least one of city, state, or zip is required.

statestring

State or province code or name, such as NY or New York.

zipstring

ZIP or postal code. ZIP+4 (10005-1234) is accepted.

countrystring

2- or 3-letter country code to restrict matches, e.g. US.

limitinteger

Maximum results, 1–40. Default 10.

exclude_sourcesstring

Comma-separated source names to omit, e.g. openstreetmap. See data sources.

min_confidencenumber

Drop results whose confidence is below this value, 0–1. Default 0 (keep all). If none remain, the response is empty and the request is metered as no_match, so you are not charged a match for results you would reject. The SDKs send their confidence threshold here when backups are configured.

Values are trimmed and limited to 256 bytes. Unknown or repeated parameters return 400.

Request example

cURL

curl --get "$GEOCODING_BASE_URL/v1/geocode" \
  --header "apikey: $GEOCODING_API_KEY" \
  --data-urlencode "street=11 Wall Street" \
  --data-urlencode "city=New York" \
  --data-urlencode "state=NY" \
  --data-urlencode "zip=10005"

Success response

HTTP/1.1 200 OK
Content-Type: application/json
X-Geocoding-Outcome: matched

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-74.0113, 40.7074]},
      "properties": {
        "id": "openaddresses:address:us/ny:1",
        "label": "11 Wall Street, New York, NY, USA",
        "type": "address",
        "name": "11 Wall Street",
        "house_number": "11",
        "street": "Wall Street",
        "unit": null,
        "neighborhood": "Financial District",
        "city": "New York",
        "county": "New York County",
        "state": "NY",
        "state_name": "New York",
        "zip": "10005",
        "country": "US",
        "lat": 40.7074,
        "lon": -74.0113,
        "confidence": 0.99,
        "match_type": "exact",
        "distance_m": null,
        "categories": [],
        "source": "openaddresses"
      }
    }
  ],
  "bbox": [-74.0113, 40.7074, -74.0113, 40.7074]
}

The example is illustrative. See response fields for every property.

Geocode confidence compares your street, city, state, and ZIP with each match, and is lowered when two different addresses match nearly equally well. Results are sorted by confidence, highest first. See confidence scores.

No matches returns 200 with "features": [] and X-Geocoding-Outcome: no_match. Source filtering can remove all matches and does not fetch replacements.

Search behavior

Geocode matches street addresses only. To find cities, ZIP codes, or businesses, use search. Dataset coverage determines which addresses can match.

See common failures and OpenAPI.