Geocoding API | Documentation & Examples

Developer Guide
Before you begin
Geocoding is an innovative solution to get geographic coordinates from an address. This process can be used to insert markers on maps or determine the position of a map at an address. For example, we have an exact address – "1600 Amphitheater Parkway, Mountain View, CA". We need to get the coordinates on the map. The consequence – is latitude 37.423021 and longitude 122.083739.

There is also an opportunity for reverse Geocoding where you can get an actual readable address by geographic coordinates.
* Note: This service is generally designed for geocoding static (known in advance) addresses for placement of application content on a map.
Check our Geocoding API documentation to get more information about current options to create requests and received responses.

What сan 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 Geocoding API?

The Geocoding API, as the API reverse geocoding, can be in high demand in many areas. This tool will help you correctly determine the location anywhere in the world. You can get data in various formats. The undoubted advantage of this service is its high level of accuracy.

If we talk about world leaders like Google, TomTom, and Bing, we should admit that our API provides a similar accuracy level to the best analogs. And we have good news for you. You will not have any troubles or discomfort if you decide to change Google API to our product.

How to use Geocoding API

You can access this service through an HTTP interface.
All geocoding requests need to submit a query or what you're trying to find. In the form of initial data, you can use the actual address and coordinates – latitude and longitude – for reverse geocoding. Below you can find the list of required and optional parameters in requests.

When you make a query, you get a response, a JSON-formatted document of the most relevant results from your request. You can see below examples of actual requests and responses.

Geocoding API Request Format

Request Parameters

The Geocoding API request was created specifically to be similar to the Google Geocoding API request format.
A Geocoding API request takes the following form:
GET:
Copied!
https://api.distancematrix.ai/maps/api/geocode/json?parameters
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.

Some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.

The rest of this page describes geocoding and reverse geocoding separately, because different parameters are available for each type of request.

Required parameters in a geocoding request:

  • address — The street address that you want to geocode. Specify addresses in accordance with the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to %20):
Copied!
address=24%20Sussex%20Drive%20Ottawa%20ON
  • key — Your application's API key. This key identifies your application for purposes of quota management.
More details about the key, its purpose, obtaining process, and Geocoding API limits applied to the key, can be found at the link.

Optional parameters in a Geocoding request:

  • language — The language in which to return results.
    • See the list of supported languages.
    • If language is not supplied, the geocoder attempts to use the preferred language as specified in the Accept-Language header, or the native language of the domain from which the request is sent.
    • The geocoder does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the geocoder uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street and square respectively in Hungarian.
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


  • region — The region code, specified as a ccTLD ("top-level domain") two-character value. This parameter will only influence, not fully restrict, results from the geocoder.

Geocoding Responses

Our Geo API converts the address to latitude and longitude. Geocoding responses are returned in the format indicated by the output flag within the URL request's path.

In this example, the Geocoding API requests a json response for a query on "1600 Amphitheatre Parkway, Mountain View, CA".
This request demonstrates using the JSON output flag:
GET:
Copied!
https://api.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>
The sample JSON response:
BODY
Copied!
{
   "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"
}
Show more
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. Parsing JSON is relatively easy.

Status Codes

The "status" field within the Geocoding response object contains the status of the request, and may contain debugging information to help you track down why geocoding is not working. The "status" field may contain the following values:
  • "OK" indicates that no errors occurred; the address was successfully parsed and at least one geocode was returned.
  • "ZERO_RESULTS" indicates that the geocode was successful but returned no results. This may occur if the geocoder was passed a non-existent address.
  • "OVER_DAILY_LIMIT" indicates any of the following:
    • The API key is missing or invalid.
    • Billing has not been enabled on your account.
    • A self-imposed usage cap has been exceeded.
  • "OVER_QUERY_LIMIT" indicates that you are over your quota.
  • "REQUEST_DENIED" indicates that your request was denied.
  • "INVALID_REQUEST" generally indicates that the query (address, components or latlng) is missing.
  • "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.

Error Messages

When the geocoder returns a status code other than OK, there may be an additional error_message field within the Geocoding response object. This field contains more detailed information about the reasons behind the given status code.
* Note: This field is not guaranteed to be always present, and its content is subject to change.

Results

When the geocoder returns results, it places them within a (JSON) results array. Even if the geocoder returns no results (such as if the address doesn't exist) it still returns an empty results array.
A typical result contains the following fields:
  • The types[] array indicates the type of the returned result. This array contains a set of zero or more tags identifying the type of feature returned in the result. For example, a geocode of "Chicago" returns "locality" which indicates that "Chicago" is a city, and also returns "political" which indicates it is a political entity.
  • formatted_address is a string containing the human-readable address of this location. Often this address is equivalent to the postal address. Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions. The formatted address is logically composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" consists of the following components: "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state). Do not parse the formatted address programmatically. Instead you should use the individual address components, which the API response includes in addition to the formatted address field.
  • address_components[] is an array containing the separate components applicable to this address.
Each address component typically contains the following fields:
  • types[] is an array indicating the type of the address component.
  • long_name is the full text description or name of the address component as returned by the Geocoder.
  • short_name is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation.
Note the following facts about the address_components[] array:
  • The array of address components may contain more components than the formatted_address.
  • The array does not necessarily include all the political entities that contain an address, apart from those included in the formatted_address. To retrieve all the political entities that contain a specific address, you should use reverse geocoding, passing the latitude/longitude of the address as a parameter to the request.
  • The format of the response is not guaranteed to remain the same between requests. In particular, the number of address_components varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the component can change. A particular component may be missing in a later response.
To handle the array of components, you should parse the response and select appropriate values via expressions.
  • postcode_localities[] is an array denoting all the localities contained in a postal code. This is only present when the result is a postal code that contains multiple localities.
  • geometry contains the following information:
    • location contains the geocoded latitude, longitude value. For normal address lookups, this field is typically the most important.
    • location_type stores additional data about the specified location. The following values are currently supported:
      • "ROOFTOP" indicates that the returned result is a precise geocode for which we have location information accurate down to street address precision.
      • "RANGE_INTERPOLATED" indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
      • "GEOMETRIC_CENTER" indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region).
      • "APPROXIMATE" indicates that the returned result is approximate.
  • partial_match indicates that the geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address.
Partial matches most often occur for street addresses that do not exist within the locality you pass in the request. Partial matches may also be returned when a request matches two or more locations in the same locality. For example, "21 Henr St, Bristol, UK" will return a partial match for both Henry Street and Henrietta Street. Note that if a request includes a misspelled address component, the geocoding service may suggest an alternative address. Suggestions triggered in this way will also be marked as a partial match.

Address Types and Address Component Types

The types[] array in the result indicates the address type. Examples of address types include a street address, a country, or a political entity. There is also a types[] array in the address_components[], indicating the type of each part of the address. Examples include street number or country. (Below is a full list of types.) Addresses may have multiple types. The types may be considered 'tags'. For example, many cities are tagged with the political and the locality type.
The following types are supported and returned by the geocoder in both the address type and address component type arrays:
  • street_address indicates a precise street address.
  • route indicates a named route (such as "US 101").
  • intersection indicates a major intersection, usually of two major roads.
  • political indicates a political entity. Usually, this type indicates a polygon of some civil administration.
  • country indicates the national political entity, and is typically the highest order type returned by the Geocoder.
  • administrative_area_level_1 indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 short names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.
  • administrative_area_level_2 indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.
  • administrative_area_level_3 indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  • administrative_area_level_4 indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  • administrative_area_level_5 indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
  • colloquial_area indicates a commonly-used alternative name for the entity.
  • locality indicates an incorporated city or town political entity.
  • sublocality indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: sublocality_level_1 to sublocality_level_5. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area.
  • neighborhood indicates a named neighborhood.
  • premise indicates a named location, usually a building or collection of buildings with a common name.
  • subpremise indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name.
  • postal_code indicates a postal code as used to address postal mail within the country.
  • natural_feature indicates a prominent natural feature.
  • airport indicates an airport.
  • park indicates a named park.
  • point_of_interest indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Empire State Building" or "Eiffel Tower".
An empty list of types indicates there are no known types for the particular address component, for example, Lieu-dit in France.
In addition to the above, address components may include the types below:
  • floor indicates the floor of a building address.
  • establishment typically indicates a place that has not yet been categorized.
  • point_of_interest indicates a named point of interest.
  • parking indicates a parking lot or parking structure.
  • post_box indicates a specific postal box.
  • postal_town indicates a grouping of geographic areas, such as locality and sublocality, used for mailing addresses in some countries.
  • room indicates the room of a building address.
  • street_number indicates the precise street number.
  • bus_station, train_station and transit_station indicate the location of a bus, train or public transit stop.

Reverse Geocoding Requests

Required parameters in a Reverse Geocoding request:

  • latlng — The latitude and longitude values specifying the location for which you wish to obtain the closest, human-readable address.
  • key — Your application's API key. This key identifies your application for purposes of quota management.

Optional parameters in a Reverse Geocoding request:

These are the optional parameters that you can include in a reverse Geocoding request:
  • language — The language in which to return results.
    • If language is not supplied, the geocoder attempts to use the preferred language as specified in the Accept-Language header, or the native language of the domain from which the request is sent.
    • The geocoder does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the geocoder uses the closest match.
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 — A filter of one or more address types, separated by a pipe (|). If the parameter contains multiple address types, the API returns all addresses that match any of the types. A note about processing: The result_type parameter does not restrict the search to the specified address type(s). Rather, the result_type acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified address type(s). The following values are supported:
    • street_address indicates a precise street address.
    • route indicates a named route (such as "US 101").
    • intersection indicates a major intersection, usually of two major roads.
    • political indicates a political entity. Usually, this type indicates a polygon of some civil administration.
    • country indicates the national political entity, and is typically the highest order type returned by the Geocoder.
    • administrative_area_level_1 indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels. In most cases, administrative_area_level_1 short names will closely match ISO 3166-2 subdivisions and other widely circulated lists; however this is not guaranteed as our geocoding results are based on a variety of signals and location data.
    • administrative_area_level_2 indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.
    • administrative_area_level_3 indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
    • administrative_area_level_4 indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
    • administrative_area_level_5 indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
    • colloquial_area indicates a commonly-used alternative name for the entity.
    • locality indicates an incorporated city or town political entity.
    • sublocality indicates a first-order civil entity below a locality. For some locations may receive one of the additional types: sublocality_level_1 to sublocality_level_5. Each sublocality level is a civil entity. Larger numbers indicate a smaller geographic area.
    • neighborhood indicates a named neighborhood.
    • premise indicates a named location, usually a building or collection of buildings with a common name.
    • subpremise indicates a first-order entity below a named location, usually a singular building within a collection of buildings with a common name.
    • postal_code indicates a postal code as used to address postal mail within the country.
    • natural_feature indicates a prominent natural feature.
    • airport indicates an airport.
    • park indicates a named park.
    • point_of_interest indicates a named point of interest. Typically, these "POI"s are prominent local entities that don't easily fit in another category, such as "Empire State Building" or "Eiffel Tower".
  • location_type — A filter of one or more location types, separated by a pipe (|). If the parameter contains multiple location types, the API returns all addresses that match any of the types. A note about processing: The location_type parameter does not restrict the search to the specified location type(s). Rather, the location_type acts as a post-search filter: the API fetches all results for the specified latlng, then discards those results that do not match the specified location type(s). The following values are supported:
    • "ROOFTOP" returns only the addresses for which DistanceMatrix has location information accurate down to street address precision.
    • "RANGE_INTERPOLATED" returns only the addresses that reflect an approximation (usually on a road) interpolated between two precise points (such as intersections). An interpolated range generally indicates that rooftop geocodes are unavailable for a street address.
    • "GEOMETRIC_CENTER" returns only geometric centers of a location such as a polyline (for example, a street) or polygon (region).
    • "APPROXIMATE" returns only the addresses that are characterized as approximate.
If both result_type and location_type filters are present then the API returns only those results that match both the result_type and the location_type values. If none of the filter values are acceptable, the API returns ZERO_RESULTS.

Example of Reverse Geocoding

The following query contains the latitude/longitude value for a location in Brooklyn and needs Geocoding API web service to transform it into a human-readable address.
Request example:
GET:
Copied!
https://api.distancematrix.ai/maps/api/geocode/json?latlng=40.714224,-73.961452&key=<your_access_token>
* Note: Ensure that no space exists between the latitude and longitude values when passed in the latlng parameter.
The above query returns the following result.
Response example:
BODY
Copied!
{
   "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"
}
Show more
Note that the reverse geocoder returned more than one result. The "formatted_address" results are not just postal addresses, but any way to geographically name a location. For example, when geocoding a point in the city of Chicago, the geocoded point may be denoted as a street address, as the city (Chicago), as its state (Illinois) or as a country (The United States). All are "addresses" to the geocoder. The reverse geocoder returns any of these types as valid results.

The reverse geocoder matches political entities (countries, provinces, cities and neighborhoods), street addresses, and postal codes.

The full list of formatted_address values returned by the previous query is shown below.
The full list of formatted_address:
BODY
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",
Copied!
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",
Generally, addresses are returned from most specific to least specific; the more exact address is the most prominent result, as it is in this case. Note that we return different types of addresses, from the most specific street address to less specific political entities such as neighborhoods, cities, counties, states, etc.
* Note: Reverse geocoding is an estimate. The geocoder will attempt to find the closest addressable location within a certain tolerance. If no match is found, the geocoder will return zero results.

Reverse Geocoding Status Codes

The "status" field within the Geocoding response object contains the status of the request, and may contain debugging information to help you track down why reverse geocoding is not working. The "status" field may contain the following values:
  • "OK" indicates that no errors occurred and at least one address was returned.
  • "ZERO_RESULTS" indicates that the reverse geocoding was successful but returned no results. This may occur if the geocoder was passed a latlng in a remote location.
  • "OVER_QUERY_LIMIT" indicates that you are over your quota.
  • "REQUEST_DENIED" indicates that the request was denied. Possibly because the request includes a result_type or location_type parameter but does not include an API key or client ID.
  • "INVALID_REQUEST" generally indicates one of the following:
    • The query ( address, components or latlng) is missing.
    • An invalid result_type or location_type was given.
  • "UNKNOWN_ERROR" indicates that the request could not be processed due to a server error. The request may succeed if you try again.

Learn more about the Geocoding API

No credit card required. Cancel anytime!
Start a free 7-day trial of the Geocoding API