Skip to main content
API reference

Search

Free-text search for addresses, places, cities, and ZIP codes.

GET/v1/search

Send one line of text, such as an address, business name, city, or ZIP code. Search returns the best matches of any type. Use geocode when you already have the address split into street, city, state, and ZIP.

Headers​

HeaderRequiredValue
apikeyYesYour primary API key

Query parameters​

qstringrequired

What to find, e.g. 1600 Pennsylvania Ave, Washington DC or Starbucks, Los Angeles.

nearstring

lat,lon to prefer results near a point, e.g. 34.05,-118.24. Results elsewhere can still be returned.

bboxstring

minLon,minLat,maxLon,maxLat to return only results inside a box.

countrystring

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

typesstring

Comma-separated result types to include, e.g. address,venue.

limitinteger

Maximum results, 1–40. Default 10.

exclude_sourcesstring

Comma-separated source names to omit. See data sources.

Request example​

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

Success response​

Search returns the same GeoJSON format as every endpoint. Each result's type tells you what was matched, for example address, venue, city, or zip. When near is given, distance_m is the distance from that point in meters.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-118.2355, 34.0562]},
      "properties": {
        "id": "openstreetmap:venue:way/443287381",
        "label": "Starbucks, Los Angeles, CA, USA",
        "type": "venue",
        "name": "Starbucks",
        "house_number": "800",
        "street": "North Alameda Street",
        "unit": null,
        "neighborhood": "Historic Core",
        "city": "Los Angeles",
        "county": "Los Angeles",
        "state": "CA",
        "state_name": "California",
        "zip": "90012",
        "country": "US",
        "lat": 34.0562,
        "lon": -118.2355,
        "confidence": 0.86,
        "match_type": "exact",
        "distance_m": 798,
        "categories": ["amenity:cafe", "cuisine:coffee_shop"],
        "source": "openstreetmap"
      }
    }
  ]
}

No matches returns 200 with "features": [] and X-Geocoding-Outcome: no_match. Search confidence comes from the search ranking and is not the same score as geocode confidence.

See common failures and OpenAPI.