Как указать местоположения для маршрута

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

Чтобы рассчитать маршрут, необходимо указать как минимум начальную и конечную точки. Эти местоположения определяются как промежуточные точки маршрута.

Помимо пунктов отправления и назначения, вы можете указать разные типы промежуточных точек и то, как они будут обрабатываться при построении маршрута. Дополнительную информацию и примеры можно найти в следующих статьях:

Как указать местоположения для маршрута

Чтобы представить местоположение, создайте объект Waypoint (REST) или Waypoint (gRPC). В определении путевой точки можно указать местоположение одним из следующих способов:

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

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

  • При использовании координат широты и долготы местоположение может быть привязано к ближайшей дороге, которая может не быть подъездным путем к объекту или даже дорогой, по которой можно быстро и безопасно добраться до пункта назначения.
  • Чтобы рассчитать маршрут, сначала необходимо преобразовать строки адресов в координаты широты и долготы с помощью Routes API. Это может повлиять на эффективность.

Как указать местоположение с помощью идентификатора места

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

Получайте идентификаторы мест из Geocoding API и новой версии Places API (включая новую версию сервиса автозаполнения). Подробнее об идентификаторах мест…

В примере ниже свойство placeId используется для передачи идентификатора места в origin и destination.

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Как указать местоположение с помощью координат широты и долготы

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

Например, чтобы указать промежуточную точку для маршрута origin и destination, используйте координаты latitude и longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Как указать местоположение в виде строки адреса

Строки адресов – это адреса, представленные в виде строки (например, "1600 Amphitheatre Parkway, Mountain View, CA"). Геокодирование – это процесс преобразования строки адреса в координаты широты и долготы (например, широта 37,423021 и долгота -122,083739).

Когда вы передаете строку адреса в качестве местоположения путевой точки, Routes API внутренне геокодирует строку, чтобы преобразовать ее в координаты широты и долготы.

Например, чтобы рассчитать маршрут, укажите путевую точку для маршрута origin и destination, используя строки адреса:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

В этом примере Routes API геокодирует оба адреса, чтобы преобразовать их в координаты широты и долготы.

Если значение адреса неоднозначно, API маршрутов может выполнить поиск, чтобы отличить его от похожих адресов. Например, "1-я улица" может быть полным значением или частью значения "1-я улица, СВ" или "1-я улица, ЮВ". Этот результат может отличаться от того, который возвращает Geocoding API. Использование идентификаторов мест позволяет избежать возможных неточностей.

Как задать регион для адреса

Если передать неполную строку адреса в качестве местоположения путевой точки, API может использовать неправильные географические координаты. Например, вы отправляете запрос, в котором в качестве пункта отправления указан город Толедо, а в качестве пункта назначения – Мадрид.

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

В этом примере "Толедо" интерпретируется как город в штате Огайо в США, а не в Испании. Поэтому запрос возвращает пустой массив, что означает отсутствие маршрутов:

{
  []
}

Вы можете настроить API так, чтобы результаты возвращались с предпочтением определенного региона. Для этого служит параметр regionCode. Этот параметр указывает код региона в виде двухсимвольного значения ccTLD («национального домена верхнего уровня»). Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для Соединенного Королевства Великобритании и Северной Ирландии).

Запрос маршрута из "Толедо" в "Мадрид", в котором указан параметр regionCode, возвращает подходящие результаты, поскольку "Толедо" интерпретируется как город в Испании:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

Теперь ответ содержит маршрут, рассчитанный от Толедо (Испания) до Мадрида (Испания):

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Токен навигационной точки – это строка, которая содержит информацию о местоположении и дополнительный контекст маршрута. Токены точек навигации позволяют прокладывать точные маршруты к определенным точкам доступа рядом со входами, погрузочными платформами или специальными зонами получения заказов. Это полезно, например, для доставки еды или совместных поездок, когда место получения или высадки может быть неоднозначным.

Токен точки навигации можно получить, вызвав метод Destinations Geocoding API.

Чтобы указать токен точки навигации, выполните следующие действия:

  1. Получите navigationPointToken из метода SearchDestinations Geocoding API. Дополнительную информацию можно найти в документации по Geocoding API.
  2. Создайте путевую точку, передав navigationPointToken.

В следующем примере свойство navigation_point_token используется для передачи токена точки навигации для origin и destination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

Как указать местоположение с помощью кода Plus Code

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

Коды Plus Code – это своего рода адреса для мест, у которых нет обычного адреса. В отличие от адресов с названиями улиц и номерами домов, плюсы-коды основаны на координатах широты и долготы и состоят из цифр и букв.

Google разработал коды Plus Code, чтобы адреса были доступны всем. Код Plus Code – это закодированная ссылка на местоположение на основе координат широты и долготы, которая представляет область: 1/8000 градуса на 1/8000 градуса (приблизительно 14 x 14 метров на экваторе) или меньше. Коды Plus Code можно использовать в качестве замены почтовым адресам там, где эти адреса не существуют (здания не пронумерованы или улицам не присвоены названия).

Коды Plus Code должны быть отформатированы как глобальные или составные:

  • Глобальный код состоит из 4-значного кода региона и 6-значного или более длинного местного кода.

    Например, для адреса "1600 Amphitheatre Parkway, Mountain View, CA" глобальный код – "849V", а локальный – "CWC8+R9". Затем вы используете полный 10-значный код Plus Code, чтобы указать значение местоположения "849VCWC8+R9".

  • Составной код состоит из местного кода длиной не менее шести символов и точных данных о местоположении.

    Например, у адреса "450 Serra Mall, Stanford, CA 94305, USA" местный код – "CRHJ+C3". Для составного адреса объедините местный код с городом, штатом, почтовым индексом и страной в формате "CRHJ+C3 Stanford, CA 94305, USA".

    Например, чтобы рассчитать маршрут, указав путевую точку для маршрута origin и destination, используйте коды Plus Code:

    {
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}

Коды Plus поддерживаются в API платформы Google Карт, в том числе в новом сервисе автозаполнения, новом сервисе "Информация о месте" и Geocoding API. Например, с помощью Geocoding API можно выполнить обратное геокодирование местоположения, заданного координатами широты и долготы, чтобы определить код Plus Code этого местоположения.