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

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

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

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

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

Если значение адреса неоднозначно, Routes API может вызвать поиск, чтобы устранить неоднозначность среди похожих адресов. Например, "1st Street" может быть полным значением или частью значения "1st street NE" или "1st St SE". Этот результат может отличаться от того, который возвращает 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 основаны на координатах широты и долготы и состоят из цифр и букв.

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"
}

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