**European Economic Area (EEA) developers**
> [!NOTE]
> If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt).
## Request
A Geocoding API request takes the following form:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
where `outputFormat` may be either of the following values:
- `json` (recommended) indicates output in JavaScript Object Notation (JSON); or
- `xml` indicates output in XML
HTTPS is required.
> [!NOTE]
> **Note** : URLs must be [properly encoded](https://developers.google.com/maps/documentation/geocoding/web-service-best-practices.md.txt#BuildingURLs) to be valid and are limited to 16384 characters for all web services. Be aware of this limit when constructing your URLs. Note that different browsers, proxies, and servers may have different URL character limits as well.
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](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-reverse-geocoding.md.txt) separately, because
different parameters are available for each type of request.
### Geocoding (latitude/longitude lookup) parameters
> [!CAUTION]
> All reserved characters (for example the plus sign "+") must be [URL-encoded](https://developers.google.com/maps/documentation/geocoding/web-service-best-practices.md.txt#BuildingURLs).
**Required parameters in a geocoding request:**
- `key` --- Your application's API key. This key identifies your application for purposes of quota management. Learn how to [get a key](https://developers.google.com/maps/documentation/geocoding/guides-v3/get-api-key.md.txt).
- You must specify either `address` or `components`
or both in a request:
- `address` --- The street address or [plus code](https://plus.codes) that you want to geocode. **Note:** Address geocoding does not resolve latitude and longitude coordinates, or other unstructured strings that don't represent an address or a Plus Code. Requests using such strings are not supported and may lead to error responses or unspecified behavior. Examples of unsupported queries include the following:
| Query type | Example |
|---|---|
| Latitude and longitude coordinates. Use [reverse geocoding](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-reverse-geocoding.md.txt) instead. | *"37.422131,-122.084801"* |
| Too many concepts or constraints, such as the names of multiple places, roads, or cities in a single query | *"Market Street San Francisco San Jose Airport"* |
| Postal address elements not represented on Google Maps | *"C/O John Smith 123 Main Street"* *"P.O. Box 13 San Francisco"* |
| Names of businesses, chains, or categories combined with locations where these entities are not available | *"Tesco near Dallas, Texas"* |
| Ambiguous queries with multiple interpretations | *"Charger drop-off"* |
| Historical names no longer in use | *"Middlesex United Kingdom"* |
| Non-geospatial elements or intent | *"How many boats are in Ventura Harbor?"* |
| Unofficial or vanity names | *"The Jenga"* *"The Helter Skelter"* |
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`):
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
Format plus codes as shown here (plus signs are url-escaped to `%2B` and spaces are url-escaped to `%20`):
- **global code** is a 4 character area code and 6 character or longer local code (849VCWC8+R9 is `849VCWC8%2BR9`).
- **compound code** is a 6 character or longer local code with an explicit location (CWC8+R9 Mountain View, CA, USA is `CWC8%2BR9%20Mountain%20View%20CA%20USA`).
- `components` --- A components filter with elements separated by a pipe (`|`). The components filter is also accepted as an optional parameter if an `address` is provided. Each element in the components filter consists of a `component:value` pair, and fully restricts the results from the geocoder. See more information about [component filtering](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#component-filtering) below.
See [the FAQ](https://developers.google.com/maps/faq.md.txt#geocoder_queryformat) for additional
guidance.
**Optional parameters in a Geocoding request:**
- `bounds` --- The bounding box of the viewport within which to bias geocode results more prominently. This parameter will only influence, not fully restrict, results from the geocoder. (For more information see [Viewport Biasing](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#Viewports) below.)
- `language` --- The language in which to return results.
- See the [list of supported
languages](https://developers.google.com/maps/faq#languagesupport). Google often updates the supported languages, so this list may not be exhaustive.
- 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.
- `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. (For more information see [Region Biasing](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#RegionCodes) below.) The parameter can also affect results based on applicable law.
- `components` --- A components filter with elements separated by a pipe (`|`). The components filter is *required* if the request doesn't include an `address`. Each element in the components filter consists of a `component:value` pair, and fully restricts the results from the geocoder. See more information about [component filtering](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#component-filtering) below.
- `extra_computations` --- Use this parameter to specify the following additional features in the response:
- `ADDRESS_DESCRIPTORS` --- See [address descriptors](https://developers.google.com/maps/documentation/geocoding/guides-v3/address-descriptors/requests-address-descriptors.md.txt) for more details.
- `BUILDING_AND_ENTRANCES` --- See [entrances and building outlines](https://developers.google.com/maps/documentation/geocoding/guides-v3/building-attributes.md.txt) for more details.
To enable multiple of these features for the same API request, include the `extra_computations` parameter in the request for each feature, for example:
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```
## Responses
Geocoding responses are returned in the format indicated by the `output` flag
within the URL request, or in JSON format by default.
In this example, the Geocoding API requests a `json`
response for a query on the address "1600 Amphitheatre Parkway, Mountain View,
CA".
This request demonstrates using the JSON `output` flag:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
This request demonstrates using the XML `output` flag:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Select the tabs below to see the sample JSON and XML responses.
### JSON
```json
{
"results": [
{
"address_components": [
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Pkwy",
"types": [
"route"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"locality",
"political"
]
},
{
"long_name": "Santa Clara County",
"short_name": "Santa Clara County",
"types": [
"administrative_area_level_2",
"political"
]
},
{
"long_name": "California",
"short_name": "CA",
"types": [
"administrative_area_level_1",
"political"
]
},
{
"long_name": "United States",
"short_name": "US",
"types": [
"country",
"political"
]
},
{
"long_name": "94043",
"short_name": "94043",
"types": [
"postal_code"
]
},
{
"long_name": "1351",
"short_name": "1351",
"types": [
"postal_code_suffix"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4222804,
"lng": -122.0843428
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4237349802915,
"lng": -122.083183169709
},
"southwest": {
"lat": 37.4210370197085,
"lng": -122.085881130292
}
}
},
"place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
"plus_code": {
"compound_code": "CWC8+W7 Mountain View, CA",
"global_code": "849VCWC8+W7"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
```
Note that the JSON response contains two root elements:
- `"status"` contains metadata on the request. See [Status codes](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#StatusCodes) 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.
### XML
```xml
OK
street_address
1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
1600
1600
street_number
Amphitheatre Parkway
Amphitheatre Pkwy
route
Mountain View
Mountain View
locality
political
Santa Clara County
Santa Clara County
administrative_area_level_2
political
California
CA
administrative_area_level_1
political
United States
US
country
political
94043
94043
postal_code
37.4224428
-122.0842467
ROOFTOP
37.4212648
-122.0856069
37.4239628
-122.0829089
ChIJeRpOeF67j4AR9ydy_PIzPuM
849VCWC8+X8
CWC8+X8 Mountain View, CA
```
Note that the XML response consists of a single
`` and two top-level elements:
- `` contains metadata on the request. See [Status codes](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#StatusCodes) below.
- Zero or more `` elements, each containing a single set of geocoded address information and geometry information.
The XML response is considerably longer than the JSON response. For
that reason, we recommend that you use `json` as the preferred
output flag unless your service requires `xml` for some reason.
Additionally, processing XML trees requires some care, so that you reference
proper nodes and elements. See
[Parsing XML with XPath](https://developers.google.com/maps/documentation/geocoding/web-service-best-practices.md.txt#ParsingXML) for some recommended design patterns for output processing.
> [!NOTE]
> The remainder of this documentation uses JSON syntax. In most cases, the output format does not matter for purposes of illustrating concepts or field names in the documentation. However, note the following subtle differences:
- XML results are wrapped in a root `` element.
- JSON denotes entries with multiple elements by plural arrays (`types`), while XML denotes these using multiple singular elements (``).
- Blank elements are indicated through empty arrays in JSON, but by the absence of any such element in XML. A response that generates no results will return an empty `results` array in JSON, but no `` elements in XML, for example.
### 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.
- The provided method of payment is no longer valid (for example, a credit card has expired).
See the [Maps FAQ](https://developers.google.com/maps/faq.md.txt#over-limit-key-error) to learn
how to fix this.
- `"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]
> **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. (XML responses consist of zero
or more `` elements.)
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. For more information, see [Address types and address component types](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding.md.txt#address-types).
- `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. The address component might have an empty types array when there are no known types for that address component. The API might add new type values as needed. For more information, see [Address types and address component types](https://developers.google.com/maps/documentation/geocoding/requests-geocoding#address-types).
- `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. See the guide to
[parsing a response](https://developers.google.com/maps/documentation/geocoding/web-service-best-practices.md.txt#Parsing).
- `postcode_localities[]` is an array denoting up to 100 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.
- `viewport` contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the `southwest` and `northeast` corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user.
- `bounds` (optionally returned) stores the bounding box which can fully contain the returned result. Note that these bounds may not match the recommended viewport. (For example, San Francisco includes the [Farallon islands](https://en.wikipedia.org/wiki/Farallon_Islands), which are technically part of the city, but probably should not be returned in the viewport.)
- `plus_code` (see [Open Location Code](https://en.wikipedia.org/wiki/Open_Location_Code) and [plus codes](https://plus.codes)) is an encoded location reference, derived from latitude and longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where addresses do not exist (where buildings are not numbered or streets are not named). The API does not always return plus codes.
When the service does return a plus code, it is formatted as a global code and a compound code:
- `global_code` is a 4 character area code and 6 character or longer local code (849VCWC8+R9).
- `compound_code` is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA). Do not programmatically parse this content.
Where available, the API returns both the global code and compound code. However, if the result is in a remote location (for example, an ocean or desert) only the global code may be returned.
- `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, "Hillpar 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.
- `place_id` is a unique identifier that can be used with other Google APIs. For example, you can use the `place_id` in a [Places API](https://developers.google.com/maps/documentation/places/web-service/details) request to get details of a local business, such as phone number, opening hours, user reviews, and more. See the [place ID
overview](https://developers.google.com/maps/documentation/places/web-service/place-id).
### Address types and address component types
The `types` array in the response indicates the
*address type*. Examples of address types include a street address, a
country, or a political entity. The `types` array in
the `address_component` field indicates the type of each part of the
address. Examples include street number or country.
Addresses may have multiple types. The types may be considered 'tags'.
For example, many cities are tagged with the `political` and
`locality` types.
The following types are supported and returned in both the
address type and address component type arrays:
| Address Type | Description |
|---|---|
| `street_address` | A precise street address. |
| `route` | A named route (such as "US 101"). |
| `intersection` | A major intersection, usually of two major roads. |
| `political` | A political entity. Usually, this type indicates a polygon of some civil administration. |
| `country` | The national political entity, and is typically the highest order type returned by the Geocoder. |
| `administrative_area_level_1` | 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` | 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` | 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` | 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` | A fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. |
| `administrative_area_level_6` | A sixth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. |
| `administrative_area_level_7` | A seventh-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels. |
| `colloquial_area` | A commonly-used alternative name for the entity. |
| `locality` | An incorporated city or town political entity. |
| `sublocality` | 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` | A named neighborhood. |
| `premise` | A named location, usually a building or collection of buildings with a common name. |
| `subpremise` | An addressable entity below the premise level, such as an apartment, unit, or suite. |
| `plus_code` | An encoded location reference, derived from latitude and longitude. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named). See for details. |
| `postal_code` | A postal code as used to address postal mail within the country. |
| `natural_feature` | A prominent natural feature. |
| `airport` | An airport. |
| `park` | A named park. |
| `point_of_interest` | 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 listed below.
> [!NOTE]
> **Note:** This list is not exhaustive, and is subject to change.
| Address Component Type | Description |
|---|---|
| `floor` | The floor of a building address. |
| `establishment` | Typically a place that has not yet been categorized. |
| `landmark` | A nearby place that is used as a reference, to aid navigation. |
| `point_of_interest` | A named point of interest. |
| `parking` | A parking lot or parking structure. |
| `post_box` | A specific postal box. |
| `postal_town` | A grouping of geographic areas, such as `locality` and `sublocality`, used for mailing addresses in some countries. |
| `room` | The room of a building address. |
| `street_number` | The precise street number. |
| `bus_station`, `train_station` and `transit_station` | The location of a bus, train or public transit stop. |
> [!NOTE]
> **Note:** The Geocoding API isn't guaranteed to return any particular component for an address within our data set. What may be thought of as the city, such as Brooklyn, may not show up as locality, but rather as another component - in this case, sublocality_level_1. What specific components are returned is subject to change without notice. Design your code to be flexible if you are attempting to extract address components from the response.
## Viewport biasing
In a Geocoding request, you can instruct the Geocoding service to prefer
results within a given viewport (expressed as a bounding box). You do so
within the request URL by setting the `bounds` parameter.
The `bounds` parameter defines the latitude/longitude coordinates
of the southwest and northeast corners of this bounding box using a pipe
(`|`) character to separate the coordinates.
> [!NOTE]
> **Note:** this only adds a *bias* towards results within the viewport, and doesn't guarantee that all or any result(s) will be contained by it. The [Places API's Autocomplete method](https://developers.google.com/maps/documentation/places/web-service/autocomplete) is generally better suited for ambiguous queries, and can restrict results to a specific area. The [Geocoding best practices article](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt) provides some guidance regarding which API method best fits which use-case.
For example, a geocode for "Washington" generally returns the US state of
Washington:
Request:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
However, adding a `bounds` argument defining a bounding box around
the north-east part of the U.S. results in this geocode returning the city of
Washington, D.C.:
Request:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
## Region biasing
In a Geocoding request, you can instruct the Geocoding service to return
results biased to a particular region by using the `region`
parameter. This parameter takes a [ccTLD](https://en.wikipedia.org/wiki/CcTLD) (country code top-level
domain) argument specifying the region bias. Most ccTLD codes are identical to
ISO 3166-1 codes, with some notable exceptions. For example, the United
Kingdom's ccTLD is "uk" (`.co.uk`) while its ISO 3166-1 code is "gb"
(technically for the entity of "The United Kingdom of Great Britain and
Northern Ireland").
Geocoding results can be biased for every domain in which the main
Google Maps application is officially launched. Note that biasing only
*prefers* results for a specific domain; if more relevant results exist
outside of this domain, they may be included.
For example, a geocode for "Toledo" returns this result, as the default
domain for the Geocoding API is set to the United States. Request:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
A Geocoding request for "Toledo" with `region=es` (Spain) will return the
Spanish city.
Request:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
## Component filtering
In a Geocoding response, the Geocoding API can return
address results restricted to a specific area. You can specify the restriction
using the `components` filter. A filter consists of a list of `component:value`
pairs separated by a pipe (`|`). Filter values support the same methods of
spelling correction and partial matching as other Geocoding requests. If the
geocoder finds a partial match for a component filter, the response will contain
a `partial_match` field.
The `components` that can be filtered include:
- `postal_code` matches `postal_code` and `postal_code_prefix`.
- `country` matches a country name or a two letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. The API follows the ISO standard for defining countries, and the filtering works best when using the corresponding ISO code of the country.
> [!NOTE]
> **Note:** If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at [Wikipedia: List of ISO
> 3166 country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) or the [ISO Online Browsing
> Platform](https://www.iso.org/obp/ui/#search).
The following `components` may be used to influence results, but will not be
enforced:
- `route` matches the long or short name of a route.
- `locality` matches against `locality` and `sublocality` types.
- `administrative_area` matches all the `administrative_area` levels.
Notes about component filtering:
- Do not repeat these component filters in requests, or the API will return `Invalid_request`: `country`, `postal_code`, `route`
- If the request contains repeated component filters, the API evaluates those filters as an AND, not an OR.
- Results are consistent with Google Maps, which occasionally yields unexpected `ZERO_RESULTS` responses. Using Place Autocomplete may provide better results in some use cases. To learn more, see [this
FAQ](https://developers.google.com/maps/documentation/geocoding/faq#trbl_component_filtering).
- For each address component, either specify it in the `address` parameter or in a `components` filter, but not both. Specifying the same values in both may result in `ZERO_RESULTS`.
A geocode for "High St, Hastings" with `components=country:GB` returns a result
in Hastings, England rather than in Hastings-On-Hudson, USA.
Request:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
A geocode request for the locality of "Santa Cruz" with `components=country:ES`
returns Santa Cruz de Tenerife in Canary Islands, Spain.
Request:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Component filtering returns a `ZERO_RESULTS` response only if you provide
filters that exclude each other.
Request:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Response:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
You can make valid queries without the address parameter, using the `components`
filter. (When geocoding a full address, the `address` parameter is required if
the request contains the names and numbers of buildings.)
Request:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}