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

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

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

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

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

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

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

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

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

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

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

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

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

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

Укажите местоположение в виде координат широты и долготы.

Чтобы определить местоположение в путевой точке, укажите Location (REST) или Location (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 геокодирует оба адреса, чтобы преобразовать их в координаты широты и долготы.

Если значение адреса неоднозначно, Routes 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 – это своего рода адреса для людей или мест, у которых нет фактического адреса. Вместо названий улиц и номеров домов в них используются координаты широты и долготы, которые отображаются в виде цифр и букв.

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

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

  • Глобальный код состоит из четырехзначного кода региона и местного кода, содержащего не менее шести знаков.

    Например, для адреса "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"
}

Плюс-коды поддерживаются в API платформы Google Карт, включая Autocomplete (New), информация о местах (New) и Geocoding API. Например, вы можете использовать Geocoding API для обратного геокодирования местоположения, заданного координатами широты и долготы, чтобы определить его код Plus Code.