apiary.apib

FORMAT: 1A
HOST: https://maps.googleapis.com/

# Google Geocoding API

Below you will find a current list of the available methods on google's geocoding and reverse geoding API. If you need help or support, please head over to google's [support page](https://developers.google.com/maps/documentation/geocoding/support).

## Useful Links
* [API Support](https://developers.google.com/maps/documentation/geocoding/support)
* [Stack Overflow](https://stackoverflow.com/questions/tagged/google-geocoding-api)
* [Issue Tracker](http://code.google.com/p/gmaps-api-issues/issues/list?can=2&q=apitype:Geocoder&colspec=ID+Type+Status+Introduced+Fixed+Summary+Internal+Stars&cells=tiles)
* [Usage Limit](https://developers.google.com/maps/documentation/geocoding/usage-limits)

## Before you begin

This document describes the Google Maps Geocoding API web service. It is intended for website and mobile developers who want to use geocoding data within maps provided by one of the Google Maps APIs.

<strong>Note</strong>: This service is generally designed for geocoding <b>static (known in advance) addresses</b> for placement of application content on a map; this service is <b>not</b> designed to respond in real time to user input. For dynamic geocoding (for example, within a user interface element), consult the documentation for the [Google Maps JavaScript API client geocoder](https://developers.google.com/maps/documentation/javascript/geocoding) and/or the [Google Play services Location APIs](https://developer.android.com/training/location/index.html).

Geocoding is a time and resource intensive task. Whenever possible, pre-geocode known addresses (using the Google Maps Geocoding API described here or another geocoding service), and store your results in a temporary cache of your own design.

To use the Google Maps Geocoding API, you need an API key. Before you start developing with the Geocoding API, review the [authentication requirements](https://developers.google.com/maps/documentation/geocoding/get-api-key) and the [API usage limits](https://developers.google.com/maps/documentation/geocoding/usage-limits).

## Google Maps Geocoding API Request Format

A Google Maps 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

To access the Google Maps Geocoding API over HTTP, use:

    http://maps.googleapis.com/maps/api/geocode/outputFormat?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.

<strong>Note</strong>: URLs must be [properly encoded](https://developers.google.com/maps/web-services/overview#BuildingURLs) to be valid and are limited to 2048 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](#geocoding) and [reverse geocoding](#reverse_geoding) separately, because different parameters are available for each type of request.

## Geocoding [/maps/api/geocode/{outputFormat}{?key,address,bounds,language,region,components}]

**Created on Aug. 4, 2015**

Geocoding is the process of converting addresses (like a street address) into geographic coordinates (like latitude and longitude), which you can use to place markers on a map, or position the map.

<table style="width: 100%; margin: 12px 0 0 0;">
<tr><td colspan="2"><strong>Required Parameters</strong></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">address</td><td>The street address that you want to geocode, in 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. Please refer to the FAQ for additional guidance.</td></tr>
<tr><td style="padding-right: 40px; width: 140px;"><strong>or</strong></td><td></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">components</td><td>A component filter for which you wish to obtain a geocode. See <a href="https://developers.google.com/maps/documentation/geocoding/intro#ComponentFiltering">Component Filtering</a> for more information. The components filter will also be accepted as an optional parameter if an address is provided.</td></tr>
<tr><td style="padding-right: 40px; width: 140px;">key</td><td>Your application's API key. This key identifies your application for purposes of quota management. Learn how to <a href="https://developers.google.com/maps/documentation/geocoding/get-api-key">get a key</a>.</td></tr>
<tr><td colspan="2"><strong>Optional Parameters</strong></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">bounds</td><td>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 <a href="https://developers.google.com/maps/documentation/geocoding/intro#Viewports">Viewport Biasing</a> below.)</td></tr>
<tr><td style="padding-right: 40px; width: 140px;">language</td><td>The language in which to return results.
<ul>
<li>See the <a href="https://developers.google.com/maps/faq#languagesupport">list of supported languages</a>. Google often updates the supported languages, so this list may not be exhaustive</li>
<li>If <code>language</code> is not supplied, the geocoder attempts to use the preferred language as specified in the <code>Accept-Language</code> header, or the native language of the domain from which the request is sent.</li>
<li>If a name is not available in the preferred language, the geocoder uses the closest match</li>
</ul></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">region</td><td>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 <a href="https://developers.google.com/maps/documentation/geocoding/intro#RegionCodes">Region Biasing</a> below.)</td></tr>
<tr><td style="padding-right: 40px; width: 140px;">components</td><td>The component filters, separated by a pipe (<code>|</code>). Each component filter consists of a <code>component:value</code> pair and will fully restrict the results from the geocoder. For more information see <a href="https://developers.google.com/maps/documentation/geocoding/intro#ComponentFiltering">Component Filtering</a>, below.</td></tr>
</table>

+ Parameters
    + `outputFormat`: `json` (required, enum[string]) - format of the response
        + Members
            + `json`
            + `xml`
    + `key`: `YOUR_API_KEY` (required, string) - your application's API key
    + `address`: `1600 Amphitheatre Parkway, Mountain View, CA` (required, string) - the street address that you want to geocode
    + `bounds` (optional, string) - bounding box of the viewport, seperate by a | within which to bias geocode results
    + `language`: `en` (optional, string) - language in which to return results
    + `region` (optional, string) - region code, specified as a top-level domain two-character value
    + `components` (optional, string) - component filters, seperated by a |

### Get Latitude & Longitude [GET]

+ Response 200 (application/json; charset=UTF-8)
    + Body

            {
               "results" : [
                  {
                     "address_components" : [
                        {
                           "long_name" : "Winnetka",
                           "short_name" : "Winnetka",
                           "types" : [ "locality", "political" ]
                        },
                        {
                           "long_name" : "New Trier",
                           "short_name" : "New Trier",
                           "types" : [ "administrative_area_level_3", "political" ]
                        },
                        {
                           "long_name" : "Cook County",
                           "short_name" : "Cook County",
                           "types" : [ "administrative_area_level_2", "political" ]
                        },
                        {
                           "long_name" : "Illinois",
                           "short_name" : "IL",
                           "types" : [ "administrative_area_level_1", "political" ]
                        },
                        {
                           "long_name" : "United States",
                           "short_name" : "US",
                           "types" : [ "country", "political" ]
                        }
                     ],
                     "formatted_address" : "Winnetka, IL, USA",
                     "geometry" : {
                        "bounds" : {
                           "northeast" : {
                              "lat" : 42.1282269,
                              "lng" : -87.7108162
                           },
                           "southwest" : {
                              "lat" : 42.0886089,
                              "lng" : -87.7708629
                           }
                        },
                        "location" : {
                           "lat" : 42.10808340000001,
                           "lng" : -87.735895
                        },
                        "location_type" : "APPROXIMATE",
                        "viewport" : {
                           "northeast" : {
                              "lat" : 42.1282269,
                              "lng" : -87.7108162
                           },
                           "southwest" : {
                              "lat" : 42.0886089,
                              "lng" : -87.7708629
                           }
                        }
                     },
                     "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
                     "types" : [ "locality", "political" ]
                  }
               ],
               "status" : "OK"
            }

    + Attributes (object)
        + `status` (Geocode Status Types) contains metadata on the request.
        + `results` (array[Result]) - contains an array of geocoded address information and geometry information.

## Reverse Geocoding [/maps/api/geocode/{outputFormat}{?key,latlng,place_id,language,result_type,location_type}]

The term geocoding generally refers to translating a human-readable address into a location on a map. The process of doing the opposite, translating a location on the map into a human-readable address, is known as reverse geocoding.

<table style="width: 100%; margin: 12px 0 0 0;">
<tr><td colspan="2"><strong>Required Parameters</strong></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">latlng</td><td>The latitude and longitude values specifying the location for which you wish to obtain the closest, human-readable address.<br><strong>Note</strong>: Ensure that no space exists between the latitude and longitude values when passed in the latlng parameter.</td></tr>
<tr><td style="padding-right: 40px; width: 140px;"><strong>or</strong></td><td></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">place_id</td><td>The place ID of the place for which you wish to obtain the human-readable address. The place ID is a unique identifier that can be used with other Google APIs. For example, you can use the <code>placeID</code> returned by the <a href="https://developers.google.com/maps/documentation/roads/snap">Google Maps Roads API</a> to get the address for a snapped point. For more information about place IDs, see the <a href="https://developers.google.com/places/place-id">place ID overview</a>. The place ID may only be specified if the request includes an API key or a Google Maps APIs Premium Plan client ID.</td></tr>
<tr><td style="padding-right: 40px; width: 140px;">key</td><td>Your application's API key. This key identifies your application for purposes of quota management. Learn how to <a href="https://developers.google.com/maps/documentation/geocoding/get-api-key">get a key</a>.</td></tr>
<tr><td colspan="2"><strong>Optional Parameters</strong></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">language</td><td>The language in which to return results.
<ul>
<li>See the <a href="https://developers.google.com/maps/faq#languagesupport">list of supported languages</a>. Google often updates the supported languages, so this list may not be exhaustive</li>
<li>If <code>language</code> is not supplied, the geocoder attempts to use the preferred language as specified in the <code>Accept-Language</code> header, or the native language of the domain from which the request is sent.</li>
<li>If a name is not available in the preferred language, the geocoder uses the closest match</li>
</ul></td></tr>
<tr><td style="padding-right: 40px; width: 140px;">result_type</td><td>TheOne or more address types, separated by a pipe (<code>|</code>). Examples of address types: <code>country</code>, <code>street_address</code>, <code>postal_code</code>. For a full list of allowable values, see the <a href="https://developers.google.com/maps/documentation/geocoding/intro#Types">address types</a> on this page. Specifying a type will restrict the results to this type. If multiple types are specified, the API will return all addresses that match any of the types. <strong>Note</strong>: This parameter is available only for requests that include an API key or a client ID.</td></tr>
<tr><td style="padding-right: 40px; width: 140px;">location_type</td><td>One or more location types, separated by a pipe (<code>|</code>). Specifying a type will restrict the results to this type. If multiple types are specified, the API will return all addresses that match any of the types. <strong>Note</strong>: This parameter is available only for requests that include an API key or a client ID. The following values are supported:
<ul>
<li> <code>ROOFTOP</code> restricts the results to addresses for which we have location information accurate down to street address precision. </li>
<li> <code>RANGE_INTERPOLATED</code> restricts the results to those 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. </li>
<li> <code>GEOMETRIC_CENTER</code> restricts the results to geometric centers of a location such as a polyline (for example, a street) or polygon (region). </li>
<li> <code>APPROXIMATE</code> restricts the results to those that are characterized as approximate. </li>
</ul></td></tr>
</table>

If both <code>result_type</code> and <code>location_type</code> restrictions are present then the API will return only those results that matches both the <code>result_type</code> and the <code>location_type</code> restrictions.

+ Parameters
    + `outputFormat`: `json` (required, enum[string]) - format of the response
        + Members
            + `json`
            + `xml`
    + `key`: `YOUR_API_KEY` (required, string) - your application's API key
    + `latlng`: `40.714224,-73.961452` (required, string) - the street address that you want to geocode
    + `language`: `en` (optional, string) - language in which to return results
    + `place_id` (optional, string) - place ID of the place
    + `result_type`: `street_address` (optional, string) - language in which to return results
    + `location_type`: `ROOFTOP` (optional, string) - region code, specified as a top-level domain two-character value

### Get Reverse Geocode [GET]

+ Response 200 (application/json; charset=UTF-8)
    + Body

            {
               "results" : [
                  {
                     "address_components" : [
                        {
                           "long_name" : "277",
                           "short_name" : "277",
                           "types" : [ "street_number" ]
                        },
                        {
                           "long_name" : "Bedford Ave",
                           "short_name" : "Bedford Ave",
                           "types" : [ "route" ]
                        },
                        {
                           "long_name" : "Williamsburg",
                           "short_name" : "Williamsburg",
                           "types" : [ "neighborhood", "political" ]
                        },
                        {
                           "long_name" : "Brooklyn",
                           "short_name" : "Brooklyn",
                           "types" : [ "sublocality_level_1", "sublocality", "political" ]
                        },
                        {
                           "long_name" : "Kings County",
                           "short_name" : "Kings County",
                           "types" : [ "administrative_area_level_2", "political" ]
                        },
                        {
                           "long_name" : "New York",
                           "short_name" : "NY",
                           "types" : [ "administrative_area_level_1", "political" ]
                        },
                        {
                           "long_name" : "United States",
                           "short_name" : "US",
                           "types" : [ "country", "political" ]
                        },
                        {
                           "long_name" : "11211",
                           "short_name" : "11211",
                           "types" : [ "postal_code" ]
                        }
                     ],
                     "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
                     "geometry" : {
                        "location" : {
                           "lat" : 40.714232,
                           "lng" : -73.9612889
                        },
                        "location_type" : "ROOFTOP",
                        "viewport" : {
                           "northeast" : {
                              "lat" : 40.7155809802915,
                              "lng" : -73.9599399197085
                           },
                           "southwest" : {
                              "lat" : 40.7128830197085,
                              "lng" : -73.96263788029151
                           }
                        }
                     },
                     "partial_match" : true,
                     "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
                     "types" : [ "street_address" ]
                  }
               ],
               "status" : "OK"
            }

    + Attributes (object)
        + `status` (Reverse Geocode Status Types) contains metadata on the request.
        + `results` (array[Result]) - contains an array of geocoded address information and geometry information.

# Data Structures

## Address Types (enum[string])

+ 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.
+ ward - indicates a specific type of Japanese locality, to facilitate distinction between multiple locality components within a Japanese address.
+ 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 "Statue of Liberty."
+ 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 <strong>locality</strong> and <strong>sublocality</strong>, 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, transit_station - indicate the location of a bus, train or public transit stop.

## Location Types (enum[string])

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

## Geocode Status Types (enum[string])

+ 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_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.

## Reverse Geocode Status Types (enum[string])

+ 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_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.

## Address Components (object)

+ types (array[Address Types]) - is an array indicating the type of the address component.
+ long_name (string) - is the full text description or name of the address component as returned by the Geocoder.
+ short_name (string) - 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.

## Location (object)

+ lat (number) - latitude
+ lng (number) - longitude

## Geometry (object)

+ location (Location) - contains the geocoded latitude,longitude value. For normal address lookups, this field is typically the most important.
+ location_type (Location Types) - stores additional data about the specified location. The following values are currently supported
+ viewport (Bounds) - contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the <strong>southwest</strong> and <strong>northeast</strong> corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user.
+ bounds (Bounds) - 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, which are technically part of the city, but probably should not be returned in the viewport.)

## Bounds (object)

+ northeast (Location)
+ southwest (Location)

## Result (object)

+ types (array[string]) - 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 (string) - is a string containing the human-readable address of this location. Often this address is equivalent to the "postal address," which sometimes differs from country to country. (Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.) This address is generally composed of one or more address components. For example, the address "111 8th Avenue, New York, NY" contains separate address components for "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state). These address components contain additional information as noted below.
+ address_components (array[Address Components]) - is an array containing the separate address components.<br><strong>Note</strong>: it may contain more address components than noted within the formatted address.
+ postcode_localities (array[string]) - 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 (Geometry) - contains the following information
+ partial_match (boolean) - 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.<p>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.</p>
+ place_id (string) - is a unique identifier that can be used with other Google APIs.