Reverse Geocoding API Reference

Estimated reading time: 4 minutes

Reverse Geocoding is the process of converting a geographic coordinates (latitude and longitude) into a human-readable address or a location (street, city, landmark...). It's the inverse of forward geocoding, which converts addresses into geographic coordinates

We generally have two main use cases for reverse geocoding.

The first is to retrieve the address closest to a point to precisely locate something. This is the default behaviour, but you still can filter your results with the parameter layers=address,street for example.

The second is to retrieve the city / state / country of a point, this gives less precision but allows a macro categorization. For this use case you may use the parameter layers=coarse. You can also restrict the layer to specific administrative areas.

When should I use Reverse Geocoding?

  • Your users click on a Dynamic Map and you want the corresponding address/location
  • You have latitude and longitude data and want the corresponding address/location
  • You want to learn the address or information about the nearest point of interest (such as the name of a business, restaurant, or park)

Parameters

In our API, all the configuration is done through query parameters.

https://api.jawg.io/places/v1/reverse?point.lon=2.32474&point.lat=48.80507&access-token=your-jawg-access-token
\___/   \_________/\_____/\__/\_____/\___________________________________/              \____________________/
  |          |        |     \     \                   |                                            |
scheme     domain service version path              query                                authentication token
Parameter Type Default
access-token (required) string
boundary.country string
boundary.gid gid
lang string en
layers string all layers
point.lat (required) number
point.lon (required) number
point.radius number 1
size integer 10
sources string all sources

💡 Explore our interactive examples. The left input shows the result using the current configuration, while the right input displays the result with default settings.

access-token

The access token you receive after having an account on our services.

Not registered yet? Create your account now https://www.jawg.io/lab/.

boundary.country

The boundary.country parameter is used to constraint search results to specific countries (one or many). This is useful when you want to limit the search to some particular countries.

The value must be a comma separated list of alpha-2 or alpha-3 ISO-3166 country code, e.g. FR,USA for France and United States.

In this example, we are restricting results in Belgium and the parameter used is:

  • boundary.country: BE

➡️ Returns only locations within Belgium.

boundary.gid

The boundary.gid parameter is used to constraint search results to a specific area (one or many) identified by the Geocoding Identifier of an administrative area. You can get the GID from any response of our API. This is useful when you want to limit the search to some particular regions.

  • boundary.gid: whosonfirst:region:85672093

➡️ Returns locations only within Yogyakarta, Indonesia.

lang

The lang parameter is used to specify the targeted language for your results using the IETF BCP 47 language tag. By default, the API will use the user's browser language (thanks to Accept-Language HTTP header) and defaults to English.

When the translation is not available in your language, it will return the name in the local dialect or English.

➡️ Returns locations in German.

layers

The layers parameter is used to constraint the search to particular layers (one or many). Depending on your use-case, this can be very useful, for example if you need only addresses you can use layers=address, or only administrative area (country, cities, neighbourhood...) layers=coarse or everything except administrative area layers=address,street,venue.

Here is the full list of our layers:

Layer Description
venue points of interest, businesses, things with walls
address places with a street address
street streets, roads, highways
neighbourhood social communities neighbourhoods
borough a local administrative boundary (usually bigger than neighbourhood)
locality towns, hamlets, cities (usually bigger than borough)
localadmin local administrative (usually bigger than locality)
county official governmental area (usually bigger than localadmin)
macrocounty a related group of counties (usually bigger than county)
region states and provinces (usually bigger than macrocounty)
macroregion a related group of regions (usually bigger than region)
country places that issue passports, nations, nation-states
coarse alias for all administrative layers (everything except venue, street and address)
postalcode postal code used by mail services
island islands that are not equivalent to an administrative layer

➡️ Returns administrative locations, that means it removes all POIs, addresses and streets.

point

The point.* parameters are used to set the anchor point for your reverse geocoding query and will return nearby locations. You have to set one point (longitude and latitude). Default value for radius is 1, the minimum is 0.00001 and the maximum is 5

  • point.lat: 48.80507
  • point.lon: 2.32474
  • point.radius: 1

➡️ Returns locations and give preference to those located in 1km radius from the point.

size

The size parameter restrict the number of returned locations. The default number of returned locations is 10 and the maximum is 40.

➡️ Returns only 2 locations.

sources

The sources parameter is used to constraint the search to particular sources (one or many). This can be useful if you want to control the returned data that will be displayed on your map.

Source Encompasses Layers Description
geonames, gn coarse, venue Geonames is an aggregation of many authoritative and non-authoritative datasets.
jawg coarse Since 2023 we have introduced our own datasource that comes from years of research and development. This data is used in addition to other sources, we only focus on the parts of the world that can be improved.
openaddresses, oa address OpenAddresses is a collection of thousands of address datasets around the world collected from national, state, and local governments.
openstreetmap, osm address, coarse, street, venue OpenStreetMap is a community-driven, editable map of the world.
whosonfirst, wof coarse Who's on First is an open-data directory of worldwide administrative places.

⚠️ Using this parameter is not recommended, we are updating our sources and you may never enjoy our new features.

➡️ Returns locations from OpenAddresses.