Sign in

v1

latestOpenAPI 3.1.02026-08-0420183200.9 KB
Geocoding

Search for location and other info using a place name or address (forward geocoding).

The search endpoint lets you search for addresses, points of interest, and administrative areas. This is most commonly used for forward geocoding applications where you need to find the geographic coordinates of an address.

get/geocoding/v1/search

Query parameters

textstring required
Example:1600 Pennsylvania Ave NW

The place name (address, venue name, etc.) to search for.

focus.point.latnumber double

The latitude of the point to focus the search on. This will bias results toward the focus point. Requires focus.point.lon.

focus.point.lonnumber double

The longitude of the point to focus the search on. This will bias results toward the focus point. Requires focus.point.lat.

boundary.rect.min_latnumber double

Defines the min latitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.

boundary.rect.max_latnumber double

Defines the max latitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.

boundary.rect.min_lonnumber double

Defines the min longitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.

boundary.rect.max_lonnumber double

Defines the max longitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.

boundary.circle.latnumber double

The latitude of the center of a circle to limit the search to. Requires boundary.circle.lon.

boundary.circle.lonnumber double

The longitude of the center of a circle to limit the search to. Requires boundary.circle.lat.

boundary.circle.radiusnumber double

The radius of the circle (in kilometers) to limit the search to. Defaults to 50km (search) or 1km (reverse) if unspecified.

boundary.countrystring[]

A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format.

boundary.gidstring

The GID of an area to limit the search to.

layersGeocodingLayer[]

A list of layers to limit the search to.

sourcesGeocodingSource[]

A list of sources to limit the search to.

sizeinteger

The maximum number of results to return.

langstring

A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a langtag (in RFC 5646 terms) can contain script, region, etc., only the language portion, an ISO 639 code, will be considered. So en-US and en-GB will both be treated as English.

Response

A GeoJSON collection of search results.

bboxnumber[]

An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.

Example response

{
  "bbox": [
    -77.036547,
    38.897675,
    -77.036547,
    38.897675
  ],
  "features": [
    {
      "geometry": {
        "coordinates": [
          -77.036547,
          38.897675
        ],
        "type": "Point"
      },
      "properties": {
        "accuracy": "point",
        "confidence": 1,
        "continent": "North America",
        "continent_gid": "whosonfirst:continent:102191575",
        "country": "United States",
        "country_a": "USA",
        "country_code": "US",
        "country_gid": "whosonfirst:country:85633793",
        "county": "District of Columbia",
        "county_a": "DI",
        "county_gid": "whosonfirst:county:1377370667",
        "gid": "openaddresses:address:us/dc/statewide:aa53d4bd0fe295be",
        "housenumber": "1600",
        "id": "us/dc/statewide:aa53d4bd0fe295be",
        "label": "1600 Pennsylvania Avenue NW, Washington, DC, USA",
        "layer": "address",
        "locality": "Washington",
        "locality_gid": "whosonfirst:locality:85931779",
        "match_type": "exact",
        "name": "1600 Pennsylvania Avenue NW",
        "neighbourhood": "White House Grounds",
        "neighbourhood_gid": "whosonfirst:neighbourhood:1108724059",
        "postalcode": "20500",
        "region": "District of Columbia",
        "region_a": "DC",
        "region_gid": "whosonfirst:region:85688741",
        "source": "openaddresses",
        "source_id": "us/dc/statewide:aa53d4bd0fe295be",
        "street": "Pennsylvania Avenue NW"
      },
      "type": "Feature"
    }
  ],
  "geocoding": {
    "attribution": "https://stadiamaps.com/attribution",
    "engine": {
      "name": "Theseus",
      "version": "1.0"
    },
    "query": {
      "lang": {
        "defaulted": true,
        "iso6391": "en",
        "iso6393": "eng",
        "name": "English",
        "via": "default"
      },
      "parsed_text": {
        "housenumber": "1600",
        "street": "pennsylvania ave nw"
      },
      "parser": "libpostal",
      "private": false,
      "querySize": 20,
      "size": 10,
      "text": "1600 Pennsylvania Ave NW"
    },
    "timestamp": 1679043782383,
    "version": "0.2"
  },
  "type": "FeatureCollection"
}