Геокодирование адреса

Разработчики Европейской экономической зоны (ЕЭЗ)

Геокодирование преобразует адрес в местоположение на карте. При геокодировании адреса ответ содержит:

  • Идентификатор местоположения
  • Координаты широты и долготы местоположения
  • Плюс Код местоположения
  • Расширенные данные адреса

Запрос геокодирования

Запрос геокодирования — это HTTP-запрос GET. Вы можете указать адрес в виде неструктурированной строки :

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

Или как структурированный набор компонентов адреса, представленных параметрами запроса:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

Структурированный формат обычно используется при обработке компонентов адреса, содержащихся в HTML-форме.

Все остальные параметры передавайте как параметры URL или, для таких параметров, как ключ API и маска поля, в заголовках как часть запроса GET.

Передать неструктурированную строку адреса

Неструктурированный адрес — это адрес, отформатированный как строка или код Plus. Например, в следующем примере передаётся URL-адрес в кодировке «1600 Amphitheatre Parkway, Mountain View, CA»:

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Обратите внимание, что символ «+» в URL-адресе преобразуется в пробел.

Вы также можете сделать запрос с помощью команды curl:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Адреса могут содержать множество специальных символов. Например, символ «/», как в «7/1 King St, Concord West». В URL символ «/» кодируется как %2F :

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Другой распространённый пример — символ «#», как в «9500 W Bryn Mawr Ave #650, Rosemont». В URL символ «#» кодируется как %2FE :

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

В следующем примере вы указываете неструктурированную строку адреса как Plus Code 849VCWC8+R4 . Убедитесь, что вы закодировали символ «+» в URL как %2B :

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Передать структурированный адрес

Укажите структурированный адрес, используя параметр запроса address типа PostalAddress . Объект PostalAddress позволяет указать некоторые или все компоненты адреса в запросе как отдельные параметры запроса.

Например, чтобы указать только почтовый индекс адреса, используйте PostalAddress.postalCode :

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Чтобы указать несколько компонентов адреса, например, для компонентов адреса, зафиксированных в HTML-форме, используйте несколько параметров запроса:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

Используйте OAuth для создания запроса

Geocoding API версии 4 поддерживает OAuth 2.0 для аутентификации. Для использования OAuth с Geocoding API необходимо назначить токену OAuth правильную область действия. Geocoding API поддерживает следующие области действия для использования с прямым геокодированием:

  • https://www.googleapis.com/auth/maps-platform.geocode — Используйте со всеми конечными точками API геокодирования.
  • https://www.googleapis.com/auth/maps-platform.geocode.address — Используйте только с GeocodeAddress для прямого геокодирования.

Кроме того, вы можете использовать общую область действия https://www.googleapis.com/auth/cloud-platform для всех конечных точек Geocoding API. Эта область действия полезна на этапе разработки, но не в процессе эксплуатации, поскольку она предоставляет доступ ко всем конечным точкам.

Дополнительную информацию и примеры см. в разделе Использование OAuth .

Геокодирование ответа

Функция Geocoding возвращает объект GeocodeAddressResponse , содержащий массив results объектов GeocodeResult . Каждый объект GeocodeResult представляет одно место.

Полный объект JSON имеет следующий вид: 

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Обязательные параметры

  • address — почтовый адрес или код Plus Code , который вы хотите геокодировать. Указывайте адреса в соответствии с форматом, используемым национальной почтовой службой соответствующей страны. Следует избегать дополнительных элементов адреса, таких как названия компаний и номера подразделений, офисов или этажей. Элементы почтового адреса должны быть разделены пробелами и закодированы в URL-адресе как %20 . Например, передайте адрес «24 Sussex Drive Ottawa ON» следующим образом:
    24%20Sussex%20Drive%20Ottawa%20ON
     Форматируйте плюс-коды, как показано ниже. Знаки «плюс» кодируются в URL как %2B , а пробелы — как %20 .
    • Глобальный код — это четырёхзначный код города и шестизначный или более длинный местный код. Например, код «849VCWC8+R9» можно закодировать как 849VCWC8%2BR9 .
    • Составной код — это локальный код длиной не менее 6 символов с указанием местоположения. Например, код «CWC8+R9 Mountain View, CA, USA» можно закодировать как CWC8%2BR9%20Mountain%20View%20CA%20USA .

Необязательные параметры

  • locationBias

    Указывает область поиска в качестве области Viewport . Это местоположение служит смещением, что означает, что могут быть возвращены результаты, близкие к указанному местоположению, включая результаты, находящиеся рядом, но за пределами этой области.

    Укажите область как прямоугольную область просмотра . Прямоугольник — это область просмотра, состоящая из двух диагонально противоположных точек: самой низкой и самой высокой. Самая низкая точка соответствует юго-западному углу прямоугольника, а самая высокая — северо-восточному.

    Область просмотра считается замкнутой областью, то есть включает её границу. Диапазон широты должен быть от -90 до 90 градусов включительно, а диапазон долготы — от -180 до 180 градусов включительно.

    • Если low = high , то область просмотра состоит из этой единственной точки.
    • Если low.longitude > high.longitude , диапазон долготы инвертируется (область просмотра пересекает линию долготы 180 градусов).
    • Если low.longitude = -180 градусов и high.longitude = 180 градусов, область просмотра включает все долготы.
    • Если low.longitude = 180 градусов, а high.longitude = -180 градусов, диапазон долготы пуст.
    • Если low.latitude > high.latitude , диапазон широт пуст.

    Оба поля (низкий и высокий) должны быть заполнены, и отображаемое поле не может быть пустым. Пустая область просмотра приводит к ошибке.

    Например, эта строка запроса определяет область просмотра, которая полностью охватывает Нью-Йорк: 

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • код_языка

    Язык, на котором будут возвращаться результаты.

    • Ознакомьтесь со списком поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
    • Если languageCode не указан, API по умолчанию использует en . Если указан недопустимый код языка, API возвращает ошибку INVALID_ARGUMENT .
    • API делает всё возможное, чтобы предоставить адрес, понятный как пользователю, так и местным жителям. Для этого он возвращает адреса на местном языке, при необходимости транслитерируя их в удобный для пользователя язык с учётом выбранного языка. Все остальные адреса возвращаются на выбранном языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
    • Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
    • Предпочтительный язык оказывает небольшое влияние на набор результатов, возвращаемых API, и порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть корректны в одном языке, но некорректны в другом.

  • Код региона

    Код региона в виде двухсимвольного кода CLDR . Значение по умолчанию отсутствует. Большинство кодов CLDR идентичны кодам ISO 3166-1.

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

Смещение местоположения

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

Например, запрос геокодирования адреса «Вашингтон» может вернуть результаты для Вашингтона, округ Колумбия, и для американского штата Вашингтон: 

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

Ответ имеет вид: 

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Однако добавление параметра locationBias , определяющего ограничивающую рамку вокруг северо-восточной части США, приводит к тому, что этот геокод возвращает только город Вашингтон, округ Колумбия: 

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Региональное смещение

В запросе геокодирования вы можете указать службе геокодирования возвращать результаты, смещенные относительно определённого региона, используя параметр regionCode . Этот параметр принимает двухсимвольное значение кода CLDR, указывающее смещение относительно региона. Большинство кодов CLDR идентичны кодам ISO 3166-1.

Значение по умолчанию для regionCode отсутствует. Например, геокод «Толедо» вернёт результаты для США и Испании: 

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

Ответ: 

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Запрос геокодирования для «Толедо» с regionCode=es (Испания) возвращает результаты только из Испании: 

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY