Guides

Quickstart

Make your first authenticated geocoding and autocomplete requests.

You need the base URL for your deployment and an active API key. Obtain the key through your deployment's account portal. The examples use http://localhost:8000 as the base URL; use your assigned HTTPS URL in production.

Configure credentials

Set these variables in your backend environment:

export GEOCODING_BASE_URL='http://localhost:8000'
export GEOCODING_API_KEY='YOUR_API_KEY'

The base URL is the API origin or deployment prefix, without an endpoint path. Use a Server API key from the portal for these backend examples. Keep it in backend configuration. Frontend autocomplete uses a separate Browser token; see browser setup.

Geocode an address

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"

street (house number and street) and at least one of city, state, or zip are required. Adding more correct location fields helps distinguish matches. --data-urlencode with --get builds the query string for you.

The response is a GeoJSON FeatureCollection; each result's fields are in properties. An illustrative result, shortened:

{
  "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",
        "house_number": "11",
        "street": "Wall Street",
        "city": "New York",
        "state": "NY",
        "zip": "10005",
        "country": "US",
        "lat": 40.7074,
        "lon": -74.0113,
        "confidence": 0.99,
        "source": "openaddresses"
      }
    }
  ]
}

Coordinates, scores, and sources depend on your dataset. A valid request with no matches returns HTTP 200 and "features": []. Check for an empty array before accessing a result. See response fields for every property.

Search with free text

curl --get "$GEOCODING_BASE_URL/v1/search" \
  --header "apikey: $GEOCODING_API_KEY" \
  --data-urlencode "q=Starbucks, Los Angeles" \
  --data-urlencode "limit=3"

Search accepts one line of text: an address, business, city, or ZIP code. Add near=lat,lon to prefer nearby results.

Reverse geocode coordinates

curl "$GEOCODING_BASE_URL/v1/reverse?lat=40.7074&lon=-74.0113&limit=1" \
  --header "apikey: $GEOCODING_API_KEY"

Requests use lat and lon. GeoJSON geometry.coordinates lists longitude first, so prefer properties.lat and properties.lon when reading results.

Choose a client

The SDKs provide normalized result objects, country routing, optional fallbacks, and request controls. Choose TypeScript, Python, PHP, or C# / .NET.

For a frontend, use the browser autocomplete client with a public pub_ token and allowed origins configured in the portal.

Unknown parameters return 400 with a message naming the allowed ones. See the HTTP reference for limits and error handling for failures.

Autocomplete an address

curl --get "$GEOCODING_BASE_URL/v1/autocomplete" \
  --header "apikey: $GEOCODING_API_KEY" \
  --data-urlencode "q=11 Wall" \
  --data-urlencode "country=US" \
  --data-urlencode "limit=5"

Autocomplete returns full results, so you can display properties.label and use the selected result's fields and coordinates directly. To fetch a result again later from a stored id, call GET /v1/place?id=.... An empty list is a successful no-match response. Each successful request is metered. See the autocomplete reference.