Before you begin
Geocoding is the process of converting an address into latitude and longitude coordinates using an API, while reverse geocoding – converting geographic coordinates (latitude and longitude) into a human-readable address via an API.
So, for example, when converting geographical coordinates like latitude 40.758678 and longitude 73.978798, using reverse geocoding API, you will receive the exact address “35 Rockefeller Plaza, New York, NY 10111, USA”.
DistanceMatrix.ai offers both solutions, Reverse Geocoding API for turning latitude and longitude into address and Direct Geocoding API for converting addresses on the map into geographical coordinates.
How to use Reverse Geocoding API
This service is accessible via an HTTP interface. For reverse geocoding requests, you would need to submit a query as coordinates (latitude and longitude). The list below details both required and optional parameters for these requests.
Upon querying, you'll receive a response in the form of a JSON document containing the most pertinent results. Examples of such requests and their corresponding responses are provided in the documentation below.
Security comes first. That's why HTTPS is strongly advised, particularly for applications dealing with sensitive data such as user location. HTTPS encryption strengthens your app's security, making it more resistant to surveillance and modification.
Our reverse geocoding API gives you the flexibility to make requests in the way that best suits your needs. The detailed instructions above guide you on how to make these requests using Postman, a versatile and easy-to-use API interaction tool.
How to use Geocoding API through Postman
Our API is a versatile HTTP service suitable for various use cases and integration scenarios. It can be used in any way that suits your needs, including direct browser requests, coding in different programming languages, or integration with applications and systems.
One of the easiest and most efficient ways to start interacting and integrating our API into your projects is using
Postman, known for its user-friendly interface and powerful features.
Here's how to do it:
To get started with Postman, install it on your computer or access a browser web version.
Import our pre-configured API collection:
Upon importing, Postman will automatically add the collection into your workspace.
For users of the online version of Postman, you can directly open the collection link and create a fork. Do this by clicking on the three dots next to the collection name.
Set up your environment in Postman, go to the Variables section and add your authentication token in the “API Authorization Token” field.
Don't forget to save these changes.
Make your first request: Select an endpoint from our collection, configure your request parameters, and hit send to see the response.
-min.webp)
Please note that you can obtain your individual token in the admin panel. Read how to do it in
the article.
-min.webp)
Don't forget to save these changes.
-min.webp)
In our Postman collection, you will find all endpoints, types of requests and available parameters. In general, we recommend using synchronous requests. However, for situations where you need to process bulk requests with a very large number of locations in one go, asynchronous requests are also available as well and can be effective. To work with them, click on Distancematrix Accurate → Bulk requests → Send a job → Body, begin work!
-min.webp)
In the Postman collection, you can find all the parameters you need to set up your requests. If you have any questions, don’t hesitate to
contact us.
Once you're comfortable with the basics, you can explore more advanced features of our API. Our detailed documentation below will guide you through the specific functionalities of our API.
Required parameters in a Reverse Geocoding request:
latlng: This required parameter includes the latitude and longitude values to specify the location you want to obtain the address for. Example:
latlng=37.422387799999996,-122.08418770000002
key: A unique API key that authenticates the requestor and enables quota calculation. This key needs to be included in each request. Append your API key to the request using the format &key=<your_access_token>.
Follow the
link to learn more about the key, its purpose, how to get it, and the Reverse Geocoding API limits.
Optional parameters in a Reverse Geocoding request:
language: Sets the language for results.
Show the list of languages
Show languages
Hide languages
Language Code
Language
Language Code
Language
af
Afrikaans
ja
Japanese
sq
Albanian
kn
Kannada
am
Amharic
kk
Kazakh
am
Arabic
km
Khmer
hy
Armenian
ko
Korean
az
Azerbaijani
ky
Kyrgyz
eu
Basque
lo
Lao
be
Belarusian
lv
Latvian
bn
Bengali
lt
Lithuanian
bs
Bosnian
mk
Macedonian
bg
Bulgarian
ms
Malay
my
Burmese
ml
Malayalam
ca
Catalan
mr
Marathi
zh
Chinese
mn
Mongolian
zh-CN
Chinese (Simplified)
ne
Nepali
zh-HK
Chinese (Hong Kong)
no
Norwegian
zh-TW
Chinese (Traditional)
pl
Polish
hr
Croatian
pt
Portuguese
cs
Czech
pt-BR
Portuguese (Brazil)
da
Danish
pt-PT
Portuguese (Portugal)
nl
Dutch
pa
Punjabi
en
English
ro
Romanian
en-AU
English (Australian)
ru
Russian
en-GB
English (Great Britain)
sr
Serbian
et
Estonian
si
Sinhalese
fa
Farsi
sk
Slovak
fi
Finnish
sl
Slovenian
fil
Filipino
es
Spanish
fr
French
es-419
Spanish (Latin America)
fr-CA
French (Canada)
sw
Swahili
gl
Galician
sv
Swedish
ka
Georgian
ta
Tamil
de
German
te
Telugu
el
Greek
th
Thai
gu
Gujarati
tr
Turkish
iw
Hebrew
uk
Ukrainian
hi
Hindi
ur
Urdu
hu
Hungarian
uz
Uzbek
is
Icelandic
vi
Vietnamese
id
Indonesian
zu
Zulu
it
Italian
result_type: Filters results by address types, using a pipe (|) for multiple types. It acts as a post-search filter, discarding results not matching the specified types. Supported types include:
location_type: Filters by location types, again using a pipe (|) for multiples. It post-filters search results, keeping only those matching specified types. Supported types are:
If both result_type and location_type filters are used, only results matching both are returned. If no matches are found, the API returns "ZERO_RESULTS".
Reverse Geocoding Responses
The given request uses the Reverse Geocoding API to convert the latitude and longitude coordinates '40.714224,-73.961452', located in Brooklyn, into a human-readable address and specifies that the response should be in JSON format.
Here's how the request is structured:
GET:
https://api.distancematrix.ai/maps/api/geocode/json?latlng=40.714224,-73.961452&key=<your_access_token>
*Important Note: When inputting the latlng parameter, ensure that there is no space between the latitude and longitude values.
JSON-response example:
BODY
{
"result": [
{
"address_components": [
{
"long_name": "290-306",
"short_name": "290-306",
"types": [
"street_number"
]
},
{
"long_name": "bedford ave",
"short_name": "bedford ave",
"types": [
"route"
]
},
{
"long_name": "brooklyn",
"short_name": "brooklyn",
"types": [
"city_district"
]
},
{
"long_name": "ny",
"short_name": "ny",
"types": [
"state"
]
},
{
"long_name": "11249",
"short_name": "11249",
"types": [
"postcode"
]
},
{
"long_name": "usa",
"short_name": "usa",
"types": [
"country"
]
}
],
"formatted_address": "290-306 Bedford Ave, Brooklyn, NY 11249, USA",
"geometry": {
"location": {
"lat": 40.714224,
"lng": -73.961452
},
"location_type": "APPROXIMATE",
"viewport": {
"northeast": {
"lat": 40.714224,
"lng": -73.961452
},
"southwest": {
"lat": 40.714224,
"lng": -73.961452
}
}
},
"place_id": "",
"plus_code": {},
"types": [
"locality",
"political"
]
}
],
"status": "OK"
}
The "formatted_address" results include various ways to geographically name a location, such as street addresses, city names, states, or countries, returning any of these types as valid results. For example, geocoding a point in Chicago can be represented as a street address, city (Chicago), state (Illinois), or country (US). The reverse geocoder matches political entities, street addresses, and postal codes.
* Important Note: Reverse geocoding estimates the nearest addressable location within a specific tolerance range, returning zero results if no close match is found.
Please, note that the JSON response has two primary elements:
"status": This element provides metadata about the request. Refer to the
Status Codes below for more details.
“result”: This includes an array with geocoded address details and geometry information.
Keep in mind that to extract specific values from these results, you generally need to parse the JSON, which in its turn is a straightforward process.
Status Codes
In the Geocoding response, the "status" field shows the request's status and may include debugging details. Possible values are:
"OK": No errors; the address was processed, and geocode(s) returned.
"ZERO_RESULTS": Geocode successful but no results found, possibly due to a non-existent address.
"OVER_DAILY_LIMIT": Could mean a missing/invalid API key, no billing enabled, or a usage cap exceeded.
"OVER_QUERY_LIMIT": Indicates quota overuse.
"REQUEST_DENIED": Your request was denied.
"INVALID_REQUEST": Typically means missing query details (address, components, or latlng).
"UNKNOWN_ERROR": A server error prevented processing. A retry might be successful.
Error Messages
If the geocoder's status code is something other than “OK,” an “error_message” field may appear in the response. This field provides detailed reasons for the specific status code.
*Important Note: The “error_message” field isn't always included, and its contents can vary.
Results
When the geocoder produces results, they are placed in a results array in JSON format. If no results are found, such as with a non-existent address, the array is returned empty.
Key fields in a typical result include:
types[] array: Specifies the type of result, with tags like “locality” for cities or “political” for political entities. For example, “Chicago” could be tagged as both.
formatted_address: A human-readable address string, often similar to a postal address. However, in some places, such as the United Kingdom, true postal addresses may not be distributable. This address is made up of components such as the street number, route, city, and state. Instead of parsing this address, use the separate address components that are also provided in the response.
address_components[]: An array of the address components.
Each address component typically contains the following fields:
types[]: Specifies the type of each address component.
long_name: Provides the full text description or name of the address component as given by the Geocoder.
short_name: Applies to the address component's name with an available abbreviated version of the address component's name. Let's take the state of Alaska as an example: a short_name of "AK," which is its 2-letter postal abbreviation and a long_name of "Alaska".
Keep in mind these points about the address_components[] array in geocoding results:
The array might include more elements than the formatted_address.
It doesn't always encompass all political entities of an address, only those in the formatted_address. Use reverse geocoding with latitude/longitude for a comprehensive list.
The response format, including the number and types of address components, can vary with each request and over time for the same address. Components may shift in position, change in type, or be absent in subsequent responses.
To effectively use the geocoding response, you need to parse the array of components and select values as needed.
postcode_localities[]: This array lists all localities within a postal code. It appears only for postal codes encompassing multiple localities.
geometry: Provides key location details:
partial_match: Indicates a non-exact match, where only part of the requested address could be matched. This is common for non-existent street addresses within the requested locality, or when an address matches multiple locations. For example, a request with a slightly misspelled address might return a nearby, correctly spelled address as a partial match.
Address Types and Address Component Types
The types[] array in geocoding results indicates the address type, which can include:
street_address: A specific street address.
route: A named route like “US 101”.
intersection: A major crossroads of two roads.
political: A political entity, often a civil administration area.
country: The national political entity, usually the top-level type.
administrative_area_level_2: A secondary civil entity, such as counties in the USA.
administrative_area_level_3 to administrative_area_level_5: Lower-order civil divisions.
Other supported types include:
colloquial_area: An alternative name for a place.
locality: An incorporated city or town.
sublocality (and levels 1-5): A civil entity within a locality.
neighborhood: A specific neighborhood.
premise: A named building or complex.
subpremise: A unit within a larger premise.
postal_code: The postal code.
natural_feature: Notable natural landmarks.
point_of_interest: Significant local entities like landmarks.
An empty types list means no known types for that address component. Additional types include:
establishment: Unclassified places.
post_box: Specific postal boxes.
postal_town: Geographic areas used for mailing addresses.
room: Specific rooms in a building.
street_number: Exact street number.
bus_station, train_station, transit_station: Transit stops.
FAQ
What can you do with the Reverse Geocoding API?
Businesses that deal with geocoding widely use both direct geocoding and reverse geocoding APIs in software and apps to locate stores, vehicles, and customers, aiding in transportation management and movement tracking.
More than just address identification/placement, reverse geocoding is a versatile tool for location mapping, route planning, and data analysis. This technology can be beneficial for logistic companies who require precise location details. There are more real-world examples of reverse geocoding API in action on our website.
Why use the Reverse Geocoding API?
Reverse Geocoding API from DistanceMatrix.ai provides accurate location data from 99% of the world in a variety of formats. So that you can get the correct address in seconds from anywhere. That's what puts our tool in high demand across multiple industries. Besides, due to its high accuracy, it competes with top providers in the field. Another thing to mind is that the switching process from any side services to our API is seamless without any hassle.
