To 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 API
• warnings: 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, gids 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 use gid at the time when you receive the search results. One valid use for the gid 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 for
• interpolated: 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 a Polygon or MultiPolygon.

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 property featres.properties.country and its value United Kingdom.
• {layer}_gid: is the gid of the layer, for example the property featres.properties.country_gid and its value whosonfirst:country:85633159.
• {layer}_a: is the abbreviation of the layer, for example the property featres.properties.country_a and its value GBR, 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"
        }
      ]
    }
  }
}