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.