Оптимизация использования квоты при геокодировании

Геокодирование – это процесс преобразования адресов (например, "1600 Amphitheatre Parkway, Mountain View, CA") в географические координаты (например, 37.423021, -122.083739), которые можно использовать для размещения маркеров или позиционирования карты. API платформы Google Карт поддерживают два подхода к геокодированию:

  • Клиентское геокодирование, которое выполняется в браузере, как правило, в ответ на действия пользователя. В Maps JavaScript API есть классы, которые выполняют запросы за вас. Этот подход описан в документации по Maps JavaScript API.
  • HTTP-геокодирование на стороне сервера, которое позволяет вашему серверу напрямую запрашивать геокоды у серверов Google. Эту функцию предоставляет веб-сервис Geocoding API. Обычно этот сервис интегрируется с другим кодом, который выполняется на стороне сервера. Геокодирование на стороне сервера описано в документации по Geocoding API.

Примеры геокодирования на стороне клиента и на стороне сервера

Ниже приведен пример клиентского геокодирования, при котором адрес геокодируется, центр карты перемещается в это местоположение и там добавляется маркер.

geocoder = new google.maps.Geocoder();
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
    });
  }
});

Другие примеры вы найдете в документации по Maps JavaScript API.

Ниже приведен пример использования Python для выполнения запроса геокодирования на стороне сервера в Geocoding API версии 4.

import json
import urllib.request

address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key = "my-key-here"
url = f"https://geocode.googleapis.com/v4/geocode/address/{address}"
headers = {"X-Goog-Api-Key": key}

req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))

Это создает объект JSON следующего содержания:

{
  "results": [
    {
      "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "location": {
        "latitude": 37.4224864,
        "longitude": -122.0855962
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4211700197085,
          "longitude": -122.08691558029149
        },
        "high": {
          "latitude": 37.4238679802915,
          "longitude": -122.08421761970851
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4221145,
          "longitude": -122.0860002
        },
        "high": {
          "latitude": 37.4228775,
          "longitude": -122.085133
        }
      },
      "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 41",
          "shortText": "Google Building 41",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

Другие примеры вы найдете в обзоре Geocoding API версии 4 и руководстве по геокодированию адресов.

Квоты и расходы

При выборе стратегии геокодирования необходимо учитывать стоимость, квоты и ограничения частоты запросов.

Стоимость

Для запросов геокодирования не используются суточные квоты. Вместо этого каждый запрос геокодирования, будь то клиентский через браузер или серверный через веб-сервис Geocoding API, оплачивается по цене за запрос. Чтобы контролировать расходы, управляйте лимитами на использование и квотами.

Ограничение частоты запросов

Для сервиса геокодирования задано ограничение частоты запросов в 3000 запросов в минуту. Это сумма клиентских и серверных запросов.

Если клиентские запросы на геокодирование выполняются периодически, например в мобильном приложении, они могут возвращать ошибки, если все пользователи отправляют запросы одновременно (например, в одну и ту же секунду каждой минуты). Чтобы избежать такой ситуации, рекомендуем:

Кеширование

Ознакомьтесь с правилами Geocoding API в отношении кеширования.

Серверная и клиентская архитектура в версии 4

Geocoding API версии 4 (включая SearchDestinations, GeocodeAddress, GeocodeLocation и GeocodePlace) – это API для межсерверного взаимодействия. Вызов конечных точек версии 4 с вашего бэкенд-сервера дает важные преимущества:

  • Гиперлокальные данные о прибытии. Метод SearchDestinations (POST /v4/geocode/destinations) доступен только при использовании REST- или gRPC-запросов на стороне сервера. Он возвращает информацию о входах в здания, точках навигации, контурах зданий и ближайших ориентирах, которая недоступна в клиентских геокодерах браузеров.
  • Повышенная безопасность API. Вызовы на стороне сервера защищают ключи API и токены OAuth от раскрытия в браузерах клиентов. Подробнее о безопасности API…
  • Маски полей ответа. Конечные точки версии 4 на стороне сервера поддерживают маски полей, что позволяет запрашивать только те поля, которые требуются вашему приложению, чтобы минимизировать размер полезной нагрузки и задержку.

Когда использовать клиентский поиск в браузере

Для интерактивных браузерных приложений, реагирующих на нажатия клавиш, рекомендуем использовать клиентский сервис автозаполнение мест (чтобы уточнять ввод данных пользователем и получать идентификатор места) в сочетании с вызовом SearchDestinations или GeocodePlace на стороне бэкенда, чтобы безопасно получать гиперлокальные данные или координаты.