Geocoding Service

Overview

Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA") into geographic coordinates (like latitude 37.423021 and longitude -122.083739), which you can use to place markers or position the map.

Reverse geocoding is the process of converting geographic coordinates into a human-readable address. The reverse geocoder also lets you find the address for a given place ID.

The Google Maps API provides a geocoder class for geocoding and reverse geocoding dynamically from user input. If instead you wish to geocode static, known addresses, see the Geocoding web service documentation.

Getting started

Before using the Geocoding service in the Google Maps JavaScript API, first ensure that the Google Maps Geocoding API is enabled in the Google API Console, in the same project you set up for the Google Maps JavaScript API.

To view your list of enabled APIs:

  1. Go to the Google API Console Enabled APIs list.
  2. From the project drop-down, select your project.
  3. From the Enabled APIs list, look for Google Maps Geocoding API.
  4. If you see the API in the list, you’re all set. If the API is not listed, enable it:
    1. Select the Google APIs tab.
    2. Search for Google Maps Geocoding API, then select it from the results list.
    3. Select Enable. When the process finishes, Google Maps Geocoding API appears in the list of enabled APIs.

Usage limits and policies

Quotas

The following usage limits are in place for the Geocoding service:

Use of the Geocoding service with the Standard Plan

  • 2,500 free requests per day, calculated as the sum of client-side and server-side queries; enable billing to access higher daily quotas, billed at $0.50 USD / 1000 additional requests, up to 100,000 requests daily.
  • 50 requests per second, calculated as the sum of client-side and server-side queries.

Use of the Geocoding service with the Premium Plan

  • Shared daily free quota of 100,000 requests per 24 hours; additional requests applied against the annual purchase of Maps APIs Credits.
  • Unlimited client-side requests per second, per project. Note that the server-side API is limited to 50 requests per second.

Policies

Use of the Geocoding service must be in accordance with the policies described for the Google Maps Geocoding API.

Geocoding Requests

Accessing the Geocoding service is asynchronous, since the Google Maps API needs to make a call to an external server. For that reason, you need to pass a callback method to execute upon completion of the request. This callback method processes the result(s). Note that the geocoder may return more than one result.

You access the Google Maps API geocoding service within your code via the google.maps.Geocoder object. The Geocoder.geocode() method initiates a request to the geocoding service, passing it a GeocoderRequest object literal containing the input terms and a callback method to execute upon receipt of the response.

The GeocoderRequest object literal contains the following fields:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Required parameters: You must supply one, and only one, of the following fields:

  • address — The address which you want to geocode.
  • location — The LatLng (or LatLngLiteral) for which you wish to obtain the closest, human-readable address. The geocoder performs a reverse geocode. See Reverse Geocoding for more information.
  • placeId — The place ID of the place for which you wish to obtain the closest, human-readable address. The place ID is a unique identifier that can be used with other Google APIs. For example, you can use the placeId returned by the Google Maps Roads API to get the address for a snapped point. For more information about place IDs, see the place ID overview. If you pass a placeId, the geocoder performs a reverse geocode. See Reverse Geocoding for more information.

Optional parameters:

  • bounds — The LatLngBounds within which to bias geocode results more prominently. The bounds parameter will only influence, not fully restrict, results from the geocoder. (For more information see Viewport Biasing below.)
  • componentRestrictions — Used to restrict results to a specific area. (For more information see Component Filtering below.)
  • region — The region code, specified as a IANA language region subtag. In most cases, these tags map directly to familiar ccTLD ("top-level domain") two-character values. The region parameter will only influence, not fully restrict, results from the geocoder. (For more information see Region Code Biasing below.)

Geocoding Responses

The Geocoding service requires a callback method to execute upon retrieval of the geocoder's results. This callback should pass two parameters to hold the results and a status code, in that order.

Geocoding Results

The GeocoderResult object represents a single geocoding result. A geocode request may return multiple result objects:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

These fields are explained below:

  • types[] is an array indicating 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," which sometimes differs from country to country. (Note that some countries, such as Great Britain, 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 8th Avenue" (a street address), "New York" (the city) and "NY" (the US state). These address components are noted below. (For more information on types, see Types below.
  • address_components[] is an array containing the separate address components, as explained above.
  • 

    partial_match – указывает, что геокодировщик не вернул точное совпадение для начального запроса, хотя и обнаружил частичное совпадение с запрашиваемым адресом. Рекомендуется проверить исходный запрос на наличие в нем опечаток и/или неполного адреса.

    В большинстве случаев частичные совпадения возникают при использовании почтовых адресов, которые отсутствуют в местности, указанной в запросе. Частичные совпадения могут также возвращаться для запросов, в которых имеется соответствие нескольким местоположениям в пределах одной местности. Например, запрос "улица Генр, 21, Бристоль, Великобритания" вернет частично совпадающие результаты для "улица Генри" и "улица Генриетты". Обратите внимание, если запрос содержит ошибки в написании адреса, служба геокодирования может предложить альтернативный адрес. Такие предложения также будут помечены как частичные совпадения.

  • place_idis a unique identifier of a place, which can be used with other Google APIs. For example, you can use the place_id with the Google Places API library to get details of a local business, such as phone number, opening hours, user reviews, and more. See the place ID overview.
  • 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. Note that we return this location as a LatLng object, not as a formatted string.
    • location_type stores additional data about the specified location. The following values are currently supported:

      • google.maps.GeocoderLocationType.ROOFTOP indicates that the returned result reflects a precise geocode.
      • google.maps.GeocoderLocationType.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.
      • google.maps.GeocoderLocationType.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).
      • google.maps.GeocoderLocationType.APPROXIMATE indicates that the returned result is approximate.

    • viewport stores the recommended viewport for the returned result.
    • bounds (optionally returned) stores the LatLngBounds 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 should not be returned in the viewport.)

The addresses will be returned by the Geocoder using the browser's preferred language setting, or the language specified when loading the API JavaScript using the language parameter. (For more information, see Localization.)

Address Component Types

The types[] array within the returned result indicates the address type. These types may also be returned within address_components[] arrays to indicate the type of the particular address component. Addresses within the geocoder may have multiple types; the types may be considered "tags". For example, many cities are tagged with the political and locality type.

The following types are supported and returned by the HTTP Geocoder:

  • 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.
  • 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 through 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.

An empty list of types indicates there are no known types for the particular address component, for instance Lieu-dit in France.

In addition to the above, address components may exhibit the following types:

  • post_box indicates a specific postal box.
  • street_number indicates the precise street number.
  • floor indicates the floor of a building address.
  • room indicates the room of a building address.

Status Codes

The status code may return one of the following values:


    
  • "OK" – ошибок нет, адрес обработан и получен хотя бы один геокод.
  • "ZERO_RESULTS" – геокодирование успешно выполнено, однако результаты не найдены. Это может произойти, если геокодировщику был передан несуществующий адрес (address).
  • "OVER_QUERY_LIMIT" – указывает на превышение квоты.
  • "REQUEST_DENIED" – указывает на отклонение запроса.
  • "INVALID_REQUEST" – как правило, указывает на отсутствие в запросе полей address, components или latlng.
  • "UNKNOWN_ERROR" – указывает, что запрос не удалось обработать из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.

In this example, we geocode an address and place a marker at the returned latitude and longitude values. Note that the handler is passed as an anonymous function literal.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById("map"), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById("address").value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == google.maps.GeocoderStatus.OK) {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert("Geocode was not successful for the following reason: " + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

View example (geocoding-simple.html)

Reverse Geocoding (Address Lookup)

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

The Geocoder supports reverse geocoding directly. Instead of supplying a textual address, supply a comma-separated latitude/longitude pair in the location parameter. Alternatively, supply a placeId to find the address for a given place ID.

Reverse Geocoding by Location

The following example geocodes a latitude/longitude value and centers the map at that location, bringing up an info window with the formatted address. We return the second result, which is less specific than the first (in this case, a neighborhood name):

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.731, lng: -73.997}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  var input = document.getElementById('latlng').value;
  var latlngStr = input.split(',', 2);
  var latlng = {lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1])};
  geocoder.geocode({'location': latlng}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[1]) {
        map.setZoom(11);
        var marker = new google.maps.Marker({
          position: latlng,
          map: map
        });
        infowindow.setContent(results[1].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

View example (geocoding-reverse.html).

Note that in the previous example we showed the second result (by selecting results[1]. The reverse geocoder often returns more than one result. Geocoding "addresses" 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 labeled 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 all of these results.

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

The full list of addresses returned by the previous query is shown below.

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results[1].formatted_address: "Williamsburg, NY, USA",
results[2].formatted_address: "New York 11211, USA",
results[3].formatted_address: "Kings, New York, USA",
results[4].formatted_address: "Brooklyn, New York, USA",
results[5].formatted_address: "New York, New York, USA",
results[6].formatted_address: "New York, USA",
results[7].formatted_address: "United States"

Addresses are returned in the order of best to least matches. Generally, 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. If you wish to match a more general address, you may wish to inspect the results[].types field.

Note: Reverse geocoding is not an exact science. The geocoder will attempt to find the closest addressable location within a certain tolerance.

Reverse Geocoding by Place ID

The following example accepts a place ID, finds the corresponding address, and centers the map at that location. It also brings up an info window showing the formatted address of the relevant place:

// Initialize the map.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.72, lng: -73.96}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a reverse geocode.
function geocodePlaceId(geocoder, map, infowindow) {
  var placeId = document.getElementById('place-id').value;
  geocoder.geocode({'placeId': placeId}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
          map: map,
          position: results[0].geometry.location
        });
        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

View example (geocoding-place-id.html).

Viewport Biasing

You can also instruct the Geocoding Service to prefer results within a given viewport (expressed as a bounding box). You do so by setting the bounds parameter within the GeocoderRequest object literal to define the bounds of this viewport. Note that biasing only prefers results within the bounds; if more relevant results exist outside of these bounds, they may be included.

For example, a geocode for "Winnetka" generally returns this suburb of Chicago:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

However, specifying a bounds parameter defining a bounding box for the San Fernando Valley of Los Angeles results in this geocode returning the neighborhood named "Winnetka" in that location:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Region Code Biasing

You can also set the Geocoding Service to return results biased to a particular region explicitly using the region parameter. This parameter takes a region code, specified as a IANA language region subtag. In most cases, these tags map directly to familiar ccTLD ("top-level domain") two-character values such as "uk" in "co.uk" for example. In some cases, the region tag also supports ISO-3166-1 codes, which sometimes differ from ccTLD values ("GB" for "Great Britain" for example).

Geocoding requests can be sent for every domain in which the main Google Maps application offers geocoding. 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 Service is set to the United States:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

A geocode for "Toledo" with the region field set to 'es' (Spain) will return the Spanish city:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Component Filtering

You can also set the Geocoding Service to return address results restricted to a specific area. Specify the restriction by using the componentRestrictions parameter. A filter consists of one or more of: route, locality, administrativeArea, postalCode or country. Only results matching all the filters will be returned. Filter values support the same methods of spelling correction and partial matching as other geocoding requests.

The following example function demonstrates using the componentRestrictions parameter to filter by country and postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Оставить отзыв о...

Текущей странице
Документации
Google Maps Javascript API
Google Maps Javascript API
Продуктах
Нужна помощь? Обратитесь в службу поддержки.