Places API Responses
Estimated reading time: 6 minutesTo facilitate the use of our API in the mapping ecosystem, the return of our API is in the well-known GeoJSON format.
We are using a FeatureCollection
, all the results that best matched your input will be in the features
property, can be empty when no responses are found.
The bbox
is computed from all your responses, it will be omitted when no responses are found.
{
"geocoding": {},
"type": "FeatureCollection",
"features": [],
"bbox": []
}
geocoding
The geocoding
property is meant for debugging purpose only. It includes:
attribution
: the link to use to display the licenses of the data sources we use.query
: how we parse your query, useful if you want to check if everything went well.engine
: the engine of our Jawg Places APIwarnings
: list of warnings messages, there are automatic messages during some optimizations. These are not real issues.errors
: list of errors messages, this is usually a fatal error.timestamp
: time of your request.
{
"geocoding": {
"attribution": "https://...",
"query": {},
"engine": {},
"warnings": [],
"errors": [],
"timestamp": 0
}
}
features
Since we are using a FeatureCollection
as main response format, the features
property will contain Feature
objects that describe a single location.
Each item in this list will contain all the information needed to find it in human-readable format in the properties
block, as well as computer friendly coordinates in the geometry
property.
The bbox
describes the geographic extent of the location, in this example it will be the area of London, England, United Kingdom
.
The type
is always Feature
.
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [ -0.125422, 51.501581 ]
},
"properties": {
"id": "101750367",
"gid": "whosonfirst:locality:101750367",
"layer": "locality",
"source": "whosonfirst",
"souce_id": "101750367",
"name": "London",
"confidence": 0.949,
"country": "United Kingdom",
"country_gid": "whosonfirst:country:85633159",
"country_a": "GBR",
"macroregion": "England",
"macroregion_gid": "whosonfirst:macroregion:404227469",
"region": "City of Westminster",
"region_gid": "whosonfirst:region:85684061",
"locality": "London",
"locality_gid": "whosonfirst:locality:101750367",
"label": "London, England, United Kingdom",
"addendum": {}
},
"bbox": [ -0.4984345, 51.297207, 0.27894, 51.6843015 ]
}
geometry
features[].geometry
Results returned are usually Point
, but can be another type according to the API you are using. You can check the type
of the geometry and the coordinates
array. Following the GeoJSON specification, these coordinates are in longitude, latitude order.
Valid types are Point
, MultiPoint
, LineString
, MultiLineString
, Polygon
, MultiPolygon
, only Places Details API is able to return other type than Point
.
id and gid
features[].properties.id
and features[].properties.gid
All locations have a gid
(Geocoding Identifier) and an id
.
The id
refers to the location's identifier in its original dataset when available.
The gid
consists of an identifier for the original data source (such as openstreetmap
or openaddresses
), a layer
(such as address
or country
), and the original id
. This information is also available as properties on the individual results as layer
, source
, and source_id
.
⚠️ While useful for identifying a specific record at a particular time, gid
s can not always be relied upon to be valid over the course of days, months, or years, as many data sources do not have stable IDs.
Follow these guidelines regarding the
gid
:
- You should not create your own
gid
strings.gid
strings may not be consistent across releases.- You should not attempt to parse
gid
strings for information or store them for future use. You should only usegid
at the time when you receive the search results. One valid use for thegid
is to retrieve full details on a particular result from the /place endpoint.
name
features[].properties.name
The name
is a short description of the location, such as a business name, a locality name, or part of an address, depending on what is being searched for and what is returned.
For address searches, the housenumber
and street
properties are brought together under the name
property in the local standard format. This saves you from having to reassemble the address yourself, including to determine whether the numbers should be placed before or after the street name.
label
features[].properties.label
The label
is a human-friendly representation of the place, with the most complete details, that is ready to be displayed to an end user. Examples of a label
include a name with its locality, a complete mailing address, or a locality with region and country names. The label
field attempts to use a format that is right for the region of the result.
confidence
features[].properties.confidence
The confidence
score is an estimation of how accurately this result matches the query, it's also used to sort the results. Confidence scores are floating point numbers ranging from 0.0
to 1.0
and are only available on search
and reverse
APIs.
distance
features[].properties.distance
The distance
property is the distance, in meters, from the query point on reverse
API or with queries using focus.point
parameters.
match_type
features[].properties.match_type
The match_type
property is not always present on responses, the possible values are exact
, interpolated
, and fallback
.
exact
: we believe this record was what you were looking forinterpolated
: you are querying for a street address, and we could not find that exact address. We will estimate where that address might be (if it exists).fallback
: we weren't able to return exactly what you asked for, so we will try to return something that relates to your query in an intelligent way.
accuracy
features[].properties.accuracy
The accuracy
property gives information on the accuracy of the latitude/longitude point returned with the given result. The possible values are point
, centroid
and source
.
point
: results are generally addresses, venues, or interpolated addresses. A point result means the record represents a record that can reasonably be represented by a single latitude/longitude point.centroid
: results, on the other hand, are records that represent a larger area, such as a city or country.source
: results are generally the raw geometry from the datasource or a simplified one. The record may be aPolygon
orMultiPolygon
.
layer
features[].properties.layer
The layer
property contains the name of the location's layer (venue
, address
, country
...).
source
features[].properties.source
The source
is the name of the location's source (openaddresses
, openstreetmap
...).
source_id
features[].properties.source_id
The source_id
contains the location's original id, taken from its source (node/4616798278
...).
Hierarchy properties
features[].properties.{layer}
, features[].properties.{layer}_gid
and features[].properties.{layer}_a
We assign a hierarchy to all locations, thanks to this, you are able to easily locate every locations.
{layer}
: is the human-readable name of the layer, for example the propertyfeatres.properties.country
and its valueUnited Kingdom
.{layer}_gid
: is the gid of the layer, for example the propertyfeatres.properties.country_gid
and its valuewhosonfirst:country:85633159
.{layer}_a
: is the abbreviation of the layer, for example the propertyfeatres.properties.country_a
and its valueGBR
, the abbreviation is not always available.
addendum
features[].properties.addendum
The addendum
is an arbitrary data alongside any document. All entries are namespaced in order to avoid property collisions.
Who's On First data will provide concordances
namespace in order to link data with other sources, wiki links etc.
{
"properties": {
"id": "101751119",
"gid": "whosonfirst:locality:101751119",
"layer": "locality",
"source": "whosonfirst",
"source_id": "101751119",
"country_code": "FR",
"name": "Paris",
"label": "Paris, France",
"addendum": {
"concordances": {
"dbp:id": "Paris",
"fb:id": "en.paris",
"fct:id": "0a65c8b6-8f76-11e1-848f-cfd5bf3ef515",
"gn:id": 2988507,
"gp:id": 615702,
"loc:id": "n79058874",
"ne:id": 1159151613,
"nyt:id": "N38451885616396959731",
"qs:id": 783857,
"qs_pg:id": 783857,
"wd:id": "Q90",
"wk:page": "Paris"
}
}
}
}
Geoname will provide geonames
namespace in order to have the feature code for example.
{
"properties": {
"id": "5128638",
"gid": "geonames:region:5128638",
"layer": "region",
"source": "geonames",
"source_id": "5128638",
"country_code": "US",
"name": "New York",
"label": "New York, USA",
"addendum": {
"geonames": {
"feature_code": "ADM1"
}
}
}
}
OpenStreetMap data will provide osm
namespace in order to have data about the data such as website, opening hours, wikipedia etc.
{
"properties": {
"id": "node/4616798278",
"gid": "openstreetmap:venue:node/4616798278",
"layer": "venue",
"source": "openstreetmap",
"source_id": "node/4616798278",
"country_code": "FR",
"name": "Jawg Corp",
"label": "Jawg Corp, Bagneux, France",
"addendum": {
"osm": {
"wheelchair": "yes",
"website": "https://jawg.io",
"opening_hours": "Mo-Fr 09:00-18:00"
}
}
}
}
For all data, you can have a dedupe
namespace that gives you all documents that have been merged by our deduplication system. This can be useful for debugging or doing processes on other documents. We will merge only similar documents (same region in the world and same name in any language).
{
"properties": {
"id": "101751119",
"gid": "whosonfirst:locality:101751119",
"layer": "locality",
"source": "whosonfirst",
"source_id": "101751119",
"country_code": "FR",
"name": "Paris",
"label": "Paris, France",
"addendum": {
"dedupe": [
{
"gid": "geonames:macrocounty:2988506",
"source": "geonames",
"layer": "macrocounty",
"id": "2988506"
},
{
"gid": "whosonfirst:region:85683497",
"source": "whosonfirst",
"layer": "region",
"id": "85683497"
},
{
"gid": "geonames:locality:6455259",
"source": "geonames",
"layer": "locality",
"id": "6455259"
},
{
"gid": "geonames:region:2968815",
"source": "geonames",
"layer": "region",
"id": "2968815"
},
{
"gid": "geonames:locality:2988507",
"source": "geonames",
"layer": "locality",
"id": "2988507"
}
]
}
}
}