Reverse Geocoding API Reference
Estimated reading time: 4 minutesReverse 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.