v1

latestOpenAPI 3.1.02026-08-0420183200.9 KB

Geocoding

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

get/geocoding/v2/search

Query parameters

textstring required

The text to search for (the start of an address, place name, etc.).

focus.point.latnumber double

Latitude in decimal degrees.

Example:12.345678

The latitude of a focus point.

If provided (along with longitude), the search results should be more locally relevant.

focus.point.lonnumber double

Longitude in decimal degrees.

Example:12.345678

The longitude of a focus point.

If provided (along with longitude), the search results should be more locally relevant.

layersLayerId[]

A list of layers to limit the search to.

sourcesSourceId[]

A list of sources to limit the search to.

boundary.gidstring

A globally unique identifier for a feature. Note: these are not stable for all datasets! For example, OSM features may be deleted and re-added with a new ID. Others like Who's on First guarantee stability long term.

Example:whosonfirst:locality:102026327

The GID of a region to limit the search to.

Note: these are not stable for all datasets! For example, OSM features may be deleted and re-added with a new ID.

boundary.countrystring[]

A list of comma-separated country codes in ISO 3116-1 alpha-2 or alpha-3 format. The search will be limited to these countries.

boundary.rect.min_latnumber double

The minimum latitude component of a search bounding box.

NOTE: Requires all other boundary.rect parameters to be specified.

boundary.rect.min_lonnumber double

Longitude in decimal degrees.

Example:12.345678

The minimum longitude component of a search bounding box.

NOTE: Requires all other boundary.rect parameters to be specified.

boundary.rect.max_latnumber double

Latitude in decimal degrees.

Example:12.345678

The maximum latitude component of a search bounding box.

NOTE: Requires all other boundary.rect parameters to be specified.

boundary.rect.max_lonnumber double

Longitude in decimal degrees.

Example:12.345678

The maximum longitude component of a search bounding box.

NOTE: Requires all other boundary.rect parameters to be specified.

boundary.circle.latnumber double

Latitude in decimal degrees.

Example:12.345678

The latitude of the center of a circle to limit the search to.

NOTE: Requires boundary.circle.lon.

boundary.circle.lonnumber double

Longitude in decimal degrees.

Example:12.345678

The longitude of the center of a circle to limit the search to.

NOTE: Requires boundary.circle.lat.

boundary.circle.radiusinteger

A radius, measured in kilometers.

Example:1

The radius of the circle (in kilometers) to limit the search to.

NOTE: Requires the other boundary.circle parameters to take effect. Defaults to 50km if unspecified.

sizeinteger

The maximum number of items to return.

Example:3

The maximum number of items to return from a query.

langstring

A BCP47 language tag which specifies a preference for localization of results. There is no default value, so place names will be returned as-is, which is usually in the local language. NOTE: The Accept-Language header is also respected, and many user agents will set it automatically.

Response

A GeoJSON FeatureCollection with the results

bboxnumber[] nullable

The geographic bounding box covering all features in the result set.

This is empty for autocomplete results.

typestring required

The GeoJSON object type as defined in RFC 7946.

NOTE: This is always FeatureCollection, as the response envelope is designed to hold multiple results.

Example response

{
  "features": [
    {
      "properties": {
        "coarse_location": "Seoul, South Korea",
        "context": {
          "whosonfirst": {
            "borough": {
              "gid": "whosonfirst:locality:102026327"
            },
            "continent": {
              "gid": "whosonfirst:locality:102026327"
            },
            "country": {
              "gid": "whosonfirst:locality:102026327"
            },
            "county": {
              "gid": "whosonfirst:locality:102026327"
            },
            "dependency": {
              "gid": "whosonfirst:locality:102026327"
            },
            "localadmin": {
              "gid": "whosonfirst:locality:102026327"
            },
            "locality": {
              "gid": "whosonfirst:locality:102026327"
            },
            "macrocounty": {
              "gid": "whosonfirst:locality:102026327"
            },
            "macroregion": {
              "gid": "whosonfirst:locality:102026327"
            },
            "marinearea": {
              "gid": "whosonfirst:locality:102026327"
            },
            "neighbourhood": {
              "gid": "whosonfirst:locality:102026327"
            },
            "ocean": {
              "gid": "whosonfirst:locality:102026327"
            },
            "region": {
              "gid": "whosonfirst:locality:102026327"
            }
          }
        },
        "gid": "whosonfirst:locality:102026327",
        "layer": "address",
        "name": "Hit Coffee Roasters",
        "sources": [
          {
            "source": "whosonfirst",
            "source_id": "85633135"
          }
        ]
      }
    }
  ]
}