Geocoding API Accurate | Documentation & Examples

Geocoding Developer Guide

Before you begin

Geocoding APIs convert 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 APIs are 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 can find examples and instructions on our geocoding APIs HTTPS requests, suitable for a broad array of approaches – whether through a web browser, any platform or application of your choice or systems like Postman. This guidance includes comprehensive descriptions on forming requests and interpreting responses across different environments.

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:
- Open Postman
- Click on the “Import” button in the top left corner.
- Select “Import from link” and paste this Postman collection link: https://www.postman.com/distancematrix/workspace/distance-matrix/overview
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.

Please note that you can obtain your individual token in the admin panel. Read how to do it in the article.

Don't forget to save these changes.

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.

Direct Geocoding Developer Guide

Below, you can read how to get latitude and longitude from the address API. You will find out what required and optional parameters you should use and which geocoding response you obtain. Also, we will show you a sample JSON response based on the output flag.

API Request Format

The Geocoding API request has been specifically designed to resemble the commonly used request format to ease the transition from alternative services. These principles are similar across most geocoding apis, ensuring that developers can switch providers with minimal changes.

A Geocoding API request looks like this:

GET:

Base URL: In the DistanceMatrix.ai geocoding service, requests are structured as URLs with required and optional parameters, separated by the ampersand (&) character. Use HTTPS encryption for security: https://.
Domain: The domain for the DistanceMatrix.ai API accurate is api.distancematrix.ai
Request URL: For geocoding, it’s /maps/api/geocode/json.
Parameters: Parameters are additional pieces of information that are added to the request URL to provide specific details to the API. These parameters can be categorized into two types: required and optional.
- Required parameters are mandatory for the API to successfully process the request because they provide essential information without which the API cannot perform the intended operation. Thus, in a geocoding API request, the address for which you need the geographic coordinates is a required parameter. Without this address, the API wouldn't know what location to geocode. For example, for such a place of interest as Anne Frank House ?address=Westermarkt+20,+1016+GV+Amsterdam,+Netherlands specifies the address for standard geocoding.
- Optional parameters are not required, but can be included to refine or customize the API response. Optional parameters can provide additional control over the format of the API response, the language in which data is returned, or other specifics relevant to the request. For example, in a geocoding request, an optional parameter might be the language in which you want the results to be returned, like &language=uk for specifying a language preference. Including this parameter is not necessary for the geocoding function itself, but it can improve the usability of the data.
Authorization Token: Include your unique access token as &key=<your_access_token> to authenticate the request.

The sample JSON response:

https://api.distancematrix.ai/maps/api/geocode/json?address=Westermarkt%2020,%201016%20GV%20Amsterdam,%20Netherlands&key=<your_access_token>

Copied!

The next section of the page details the request for the geocoding.

Optional parameters in a Geocoding request:

language — The language in which to return results.

See the list of supported languages.
The geocoder defaults to the language specified in the Accept-Language header or the native language of the request's domain if no language is provided.
To ensure readability, the geocoder returns street addresses in the local language, using transliteration when necessary, based on the user's preferred language. All address components are delivered in the same language, determined by the first component's language.
If an address name isn't available in the preferred language, the geocoder selects the closest available match.
The preferred language subtly influences the selection and order of results, as the geocoder interprets abbreviations and synonyms differently across languages. For instance, 'utca' and 'tér' in Hungarian correspond to 'street' and 'square.’

Show languages

Hide languages

Language Code

Language

Language Code

Language

Afrikaans

Japanese

Albanian

Kannada

Amharic

Kazakh

Arabic

Khmer

Armenian

Korean

Azerbaijani

Kyrgyz

Basque

Lao

Belarusian

Latvian

Bengali

Lithuanian

Bosnian

Macedonian

Bulgarian

Malay

Burmese

Malayalam

Catalan

Marathi

Chinese

Mongolian

zh-CN

Chinese (Simplified)

Nepali

zh-HK

Chinese (Hong Kong)

Norwegian

zh-TW

Chinese (Traditional)

Polish

Croatian

Portuguese

Czech

pt-BR

Portuguese (Brazil)

Danish

pt-PT

Portuguese (Portugal)

Dutch

Punjabi

English

Romanian

en-AU

English (Australian)

Russian

en-GB

English (Great Britain)

Serbian

Estonian

Sinhalese

Farsi

Slovak

Finnish

Slovenian

fil

Filipino

Spanish

French

es-419

Spanish (Latin America)

fr-CA

French (Canada)

Swahili

Galician

Swedish

Georgian

Tamil

German

Telugu

Greek

Thai

Gujarati

Turkish

Hebrew

Ukrainian

Hindi

Urdu

Hungarian

Uzbek

Icelandic

Vietnamese

Indonesian

Zulu

Italian

region — specified as a two-character ccTLD ("top-level domain") value, this parameter influences but does not strictly limit the geocoder's results.

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.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>

Copied!

The sample JSON response:

BODY

{
    "result": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "amphitheatre parkway",
                    "short_name": "amphitheatre parkway",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "mountain view",
                    "short_name": "mountain view",
                    "types": [
                        "locality"
                    ]
                },
                {
                    "long_name": "ca",
                    "short_name": "ca",
                    "types": [
                        "state"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Parkway, Mountain View, CA",
            "geometry": {
                "location": {
                    "lat": 37.422387799999996,
                    "lng": -122.08418770000002
                },
                "location_type": "APPROXIMATE",
                "viewport": {
                    "northeast": {
                        "lat": 37.422387799999996,
                        "lng": -122.08418770000002
                    },
                    "southwest": {
                        "lat": 37.422387799999996,
                        "lng": -122.08418770000002
                    }
                }
            },
            "place_id": "",
            "plus_code": {
                "compound_code": "CWC8+R9 Mountain View, California, United States",
                "global_code": "849VCWC8+R9"
            },
            "types": [
                "locality",
                "political"
            ]
        }
    ],
    "status": "OK"
}

Copied!

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 denied.

"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:

location: Contains latitude and longitude. It's typically crucial for standard address lookups.
location_type: Provides additional details about the location, with values like:
- "ROOFTOP": A precise geocode with street address precision.
- "RANGE_INTERPOLATED": An approximate result between two precise points, usually used when rooftop data isn’t available.
- "GEOMETRIC_CENTER": The geometric center of a line or area.
- "APPROXIMATE": An approximate location.

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.

airport: An airport.

park: A named park.

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.

What is a geocoding API?

A geocoding API is a service that converts street addresses into geographic coordinates (latitude/longitude) and vice versa. It enables applications to accurately place locations on maps, calculate distances between points, and perform location-based operations.