Before you begin
Geocoding converts an address into geographic coordinates that are useful for placing markers on maps or locating addresses. For example, converting “Rockefeller Center, NY, USA” results in latitude 40.7587402 and longitude 73.9786736.
Likewise, reverse geocoding converts geographic coordinates into a readable address.
How to use Geocoding API
The Distancematrix.ai geocoding service is available via an HTTP interface for a variety of applications, including web browsers, Postman, and direct application integration. Users can submit standard geocoding requests with an address, or reverse geocoding requests with coordinates (latitude and longitude). The service allows you to further configure requests by specifying additional parameters with options for customization.
After submitting your request, the service responds with a JSON-formatted document containing the most relevant results, ideally structured for straightforward use and integration with various platforms – from web browsers to different types of applications.
Security is important and HTTPS is recommended whenever possible, especially for applications that include sensitive user data, such as a user's location, in requests. Using HTTPS encryption makes your application more secure, and more resistant to snooping or tampering.
Below you'll find examples showing how to make requests and interpret responses, illustrating the process for different platforms and methods, including browsers, Postman, and application-based coding.
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 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 geocoding request:
address: Here you need to mention the street address for geocoding. It should be formatted as per the national postal service standards of the relevant country, excluding elements like business names or unit/suit/floor numbers. Use spaces (URL-escaped as %20) to separate street address elements, e.g.:
address=100%20Queens%20Park%20Toronto%20ON where "100 Queens Park, Toronto, ON" is the address of the Royal Ontario Museum
key: This parameter requires your unique API authorization token, which is necessary to verify the identity and permissions of the client making the request, ensuring secure access and accurate monitoring of its usage quota.
More details about the key, its purpose, obtaining process, and Geocoding API limits applied to the key, can be found at the
link.
Geocoding Responses
Our Geo API converts addresses to coordinates (latitude and longitude). It returns responses in the format specified in the URL request, such as JSON. In the example below, a request for “1600 Amphitheatre Parkway, Mountain View, CA” uses JSON format for its response, as indicated by the JSON output flag in the request:
GET:
https://api-v2.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>
The sample JSON response:
BODY
{
"result": [
{
"address_components": [
{
"long_name": "United States",
"short_name": "US",
"types": [
"country",
"political"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"administrative_area_level_3",
"political"
]
},
{
"long_name": "94043",
"short_name": "94043",
"types": [
"postal_code"
]
},
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Parkway",
"types": [
"route"
]
},
{
"long_name": "Google Headquarters",
"short_name": "Google Headquarters",
"types": [
"name"
]
},
{
"long_name": "CA",
"short_name": "CA",
"types": [
"state",
"administrative_area_level_1",
"political"
]
}
],
"formatted_address": "1600 Amphitheatre Parkway, Mountain View 94043, United States",
"geometry": {
"location": {
"lat": 37.4217636,
"lng": -122.084614
},
"location_type": "APPROXIMATE",
"viewport": {
"northeast": {
"lat": 37.4217636,
"lng": -122.084614
},
"southwest": {
"lat": 37.4217636,
"lng": -122.084614
}
}
},
"place_id": "2192620021",
"plus_code": {},
"types": [
"street_address"
]
}
],
"status": "OK"
}
Note that the JSON response contains two root elements:
"status" contains metadata on the request. See
Status Codes below.
"results" contains an array of geocoded address information and geometry information.
Generally, only one entry in the "results" array is returned for address lookups,though the geocoder may return several results when address queries are ambiguous.
Note that these results generally need to be parsed if you wish to extract values from the results.
Status Codes
The "status" field in the Geocoding response gives the request status and debugging information to help diagnose issues. Possible status values include:
"OK": The request was successful, and geocoding data is returned.
"ZERO_RESULTS": Geocoding was successful but yielded no results, possibly due to a non-existent address.
"OVER_DAILY_LIMIT": This can mean an invalid or missing API key, no billing on the account, or a usage cap exceeded.
"OVER_QUERY_LIMIT": Your usage has exceeded the quota.
"REQUEST_DENIED": The request was rejected.
"INVALID_REQUEST": Often means a missing query (address, components, or latlng).
"UNKNOWN_ERROR": A server error occurred; a retry may succeed.
Error Messages
If the status code returned by the Geocoder is not “OK”, an optional “error_message” field may appear in the response. This field provides more details about why that particular status code was returned.
*Note: The “error_message” field may not always be available, and its contents may change.
Results
When the geocoder returns results, they are placed in a results array in JSON format. If no results are found (such as for a non-existent address), the array will be empty.
Typical fields in a 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".
Here are some more facts about the address_components[] array to keep in mind:
The address_components[] array in a geocoding response may have more elements than the formatted_address.
It doesn't always include all political entities containing the address, except those in the formatted_address. For a complete list, use reverse geocoding with the address's latitude/longitude.
The response format, including the number and types of address components, can vary between requests and over time for the same address. Components may change in position, type, or may be omitted in subsequent responses.
To effectively use the response from the geocoder, you need to parse the array of components:
postcode_localities[]: This array lists all localities within a postal code. It appears only for postal codes encompassing multiple localities.
geometry: Includes key information like:
partial_match: Indicates a non-exact match for the request, useful for identifying potential issues like misspellings or incomplete addresses. Partial matches often occur for non-existent street addresses or when an address matches multiple locations in the same area. For example, a misspelled address (let it be "21 Henr St, Bristol, UK") might return a similar sounding street as a partial match ("Henry Street" and "Henrietta Street").
Address Types and Address Component Types
The types[] array in the geocoding result specifies the address type, such as a street address, country, or political entity. There's also a types[] array within address_components[] that specifies the type of each address part, such as street number or country. Addresses can have multiple types, functioning as 'tags'. For example, cities often have tags like 'political' and 'locality'.
The geocoder supports and returns various types in both address type and component type arrays:
street_address: A precise street address.
route: A named route like "US 101".
intersection: A major intersection of two major roads.
political: A political entity, usually indicating a civil administration polygon.
country: The national political entity, often the highest order type.
administrative_area_level_1: A primary civil entity below the country level, like states in the USA. These often align with ISO 3166-2 subdivisions.
administrative_area_level_2: A secondary civil entity, like counties in the USA.
administrative_area_level_3/administrative_area_level_4/administrative_area_level_5: Lower order civil entities, representing minor divisions.
colloquial_area: A commonly used alternative name for the entity.
locality: An incorporated city or town.
sublocality (and levels 1-5: sublocality_level_1 to sublocality_level_5): Lower order entities within a locality.The smaller geographic area the larger numbers.
neighborhood: A named neighborhood.
premise: A named location, typically a building or complex.
subpremise: A part of a larger premise, like a building within a complex.
postal_code: A postal code used within the country.
natural_feature: A significant natural feature.
point_of_interest: A prominent entity like "Empire State Building" or "Eiffel Tower".
If an address component's type list is empty, it means that no specific types are known for that component, such as a 'Lieu-dit' in France. Additionally, address components may include:
floor: The floor number in a building.
establishment: A place not yet categorized.
point_of_interest: A named point of interest.
parking: A parking lot or structure.
post_box: A specific postal box.
postal_town: A geographic area grouping used for mailing addresses in some countries.
room: A room in a building.
street_number: The precise street number.
bus_station, train_station, transit_station: Locations of bus, train, or public transit stops.
FAQ
What differentiates this API from other Geocoding APIs?
The Distancematrix.ai Geocoding API has several factors that differentiate it from other geocoding APIs:
High Accuracy: The Distancematrix.ai Geocoding API uses advanced algorithms and data sources to provide accurate and reliable geocoding results. The API also has a high success rate for matching addresses, which means that it can handle a wide range of address formats and variations.
Global Coverage: The API covers a wide range of countries and regions, including hard-to-reach places like rural areas, islands, and developing countries. This means that users can rely on the API to provide accurate results no matter where their data is coming from.
Speed and Scalability: The API is designed to handle large volumes of geocoding requests quickly and efficiently.
Cost-Effective: The API offers a simple and transparent pricing model, with no hidden fees or upfront costs. The API offers a Free plan and a Growth plan with pay-as-you-go pricing model.
Can I use this API as a converting address to lat long API?
Yes, you can use the Distancematrix.ai Geocoding API to convert addresses to latitude-longitude coordinates. In fact, that is one of the primary functions of an address to lat long API like this one.
To use the API for geocoding, you would send a request to the API with an address parameter, and the API would respond with the corresponding lat-long coordinates for that address.
The Distancematrix.ai Geocoding API is designed as a get latitude longitude from address API that is easy to use. It can be integrated into a wide range of applications and platforms. The API supports a variety of programming languages and frameworks, including Python, JavaScript, and PHP, among others.
Can I use this API as a latitude longitude API converter to human-readable addresses?
Yes, you can use the Distancematrix.ai Geocoding API to convert latitude-longitude (lat-long) coordinates to human-readable addresses. This process is also known as reverse geocoding and developers usually search for a latitude and longitude API or for aget coordinates from address API.
To use the API for reverse geocoding, you would send a request to the API with the latitude and longitude parameters, and the API would respond with the corresponding human-readable address for those coordinates.
If you have any questions or need further assistance in using the API for your reverse geocoding needs, the Distancematrix.ai team provides detailed documentation and customer support to help you get started.
What can you do with the Geocoding API?
Many companies and enterprises use software and applications to locate stores, warehouses, vehicles, and customers, to control transportation and movements that deal with geocoding. But currently, its definition is not limited to address searches. It is quite a universal tool that allows you to apply it to the overall market, from precise location and route mapping to customer data analysis and geographic pattern recognition.
This solution is in handy among, for example, taxi drivers in case they lack accurate data about the clients' destination addresses. Also, this service is convenient for food delivery couriers in their daily routines. You can read other successful geocoding API examples using our website.
Why use the Geocoding API?
The Distancematrix.ai APIs offer best-in-class accuracy that rivals industry giants but at a much more affordable price, greater scalability, and a friendly, real human support team that is always available to help you with your questions. An added benefit is the ease of transition from other vendors, ensuring a smooth switching process.
In addition, Distancematrix.ai allows users to test the service without the need to attach a credit/debit card before making a final decision. This is done so that users can verify the quality and value of the results obtained. Feel free to try to make sure that Distancematrix.ai is a high-quality and fast, yet cost-effective solution. What’s more, even during the trial period, users can reach out to the live support available for any queries.
