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:

Response
{
  "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.

Response
{
  "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 between 0.0 and 1.0 that measure how well the result matches the input query.

Higher scores generally represent better matches.

  • If a region (ie. US State) or postalcode were provided in the query but differed from the corresponding result property, we return 0.5

Otherwise the confidence is computed through several metrics, we return the mathematical mean of these calculations which include:

  • Similarity of the returned name compared to the requested name.
  • Similarity of the address compared to the requested address.
  • Similarity of other fields.

Finally the scores are ‘smoothed’ to compute ‘z-scores’ and compare their relative distance to the mean.

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 record layer is different from the layer 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.