API Response Format

All Geocode Earth API endpoints return GeoJSON in a common format. They include a combination of useful geospatial and text information for each result.

Top level sections #

Geocode Earth will always return a FeatureCollection, even if only a single result is returned.

This means you can count on the following general structure to all responses:

{
  "type": "FeatureCollection",
  "features": [ ],
  "bbox": [ ]
}

All returned results will be elements within the features array. The top level bbox record will contain a bounding box encompassing all returned results.

Result properties #

Each result will be a GeoJSON feature with geometry, properties, and bbox elements.

The following complete response with a single address shows the general layout and properties available:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.43634,
          37.793899
        ]
      },
      "properties": {
        "id": "us/ca/san_francisco:e8cd038c05c513c8",
        "gid": "openaddresses:address:us/ca/san_francisco:e8cd038c05c513c8",
        "layer": "address",
        "source": "openaddresses",
        "source_id": "us/ca/san_francisco:e8cd038c05c513c8",
        "country_code": "US",
        "name": "2640 Steiner St",
        "housenumber": "2640",
        "street": "Steiner St",
        "postalcode": "94115",
        "confidence": 1,
        "match_type": "exact",
        "accuracy": "point",
        "country": "United States",
        "country_gid": "whosonfirst:country:85633793",
        "country_a": "USA",
        "region": "California",
        "region_gid": "whosonfirst:region:85688637",
        "region_a": "CA",
        "county": "San Francisco County",
        "county_gid": "whosonfirst:county:102087579",
        "county_a": "SF",
        "locality": "San Francisco",
        "locality_gid": "whosonfirst:locality:85922583",
        "locality_a": "SF",
        "neighbourhood": "Pacific Heights",
        "neighbourhood_gid": "whosonfirst:neighbourhood:85865909",
        "continent": "North America",
        "continent_gid": "whosonfirst:continent:102191575",
        "label": "2640 Steiner St, San Francisco, CA, USA"
      }
    }
  ]
}

General properties #

The following properties are included with every record and are generally the most useful:

• name: The name of the record itself. This might be the name of a POI, the country name, or a housenumber and street for an address.
• label: The name of the record, plus relevant administrative information. This data will be formatted according to local rules, for example, as it might be written when addressing a letter.
• source: The name of the data source this record is from
• layer: The type of result, as determined by our data layers

The following properties are common, but not always present:

• country_code: The ISO_3166-1 (alpha-2) two letter country code
• postalcode: The postal code for the result, such as a ZIP code in the USA

Address properties #

Results for addresses will additionally contain the following two properties:

• housenumber: The result’s housenumber, separate from the rest of the address
• street: The result’s street, separate from the rest of the address

Parent Properties #

Parent properties contain information on which administrative areas, such as city or country, contain each result.

Each parent of a result record will have properties with the name, Global ID, and abbreviation (if one exists).

For example, any result in the Philippines will include the following properties:

"country": "Philippines",
"country_gid": "whosonfirst:country:85632509",
"country_a": "PHL",

Coordinates and Bounding Boxes #

All results from Geocode Earth include latitude and longitude coordinates.

Results for administrative areas also contain a bbox property.

Here are the coordinate and bounding box properties for Tokyo, Japan.

{
  "type": "FeatureCollection",
  "features": [{
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          139.75391,
          35.695126
        ]
      },
      "properties": { },
      "bbox": [
        139.279417452,
        35.5330801096,
        140.147167867,
        35.813461192
      ]
    }
  }]
}

As required by the GeoJSON spec, coordinates are specified as [ longitude, latitude ] pairs, and bounding boxes are specified as four element arrays following the pattern [ minimum_longitude, minimum_latitude, maximum_longitude, maximum_latitude].

Match quality and accuracy properties #

Several properties on Geocode Earth records are designed to help you determine how well the results match your query.

accuracy #

This property is always present and will be one of two values: point or centroid.

Point records include addresses and POIs that generally can be well represented by a single coordinate.

Centroid records are generally administrative areas that represent larger areas, and a single coordinate (the centroid) has been chosen to best estimate its location.

confidence #

Confidence scores are always present and contain a decimal value from 0.0 to 1.0 that measure how well the result matches the input query.

Higher scores generally represent better matches.

match_type #

The match_type field describes how well the result type correlates with the type of record Geocode Earth determined you were looking for, based on the input query.

For example, a query for an address that returned an address will have a match_type of exact. If instead an interpolated address was returned, the match_type will be interpolated.

Finally, if the type of returned record is different from specified in the query, the match_type will be fallback. This will be the case when a query for an address returns a street or city.

The match_type property is present only on results from the search and structured search.