Как проверить ответ

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

При расчете маршрута Routes API использует в качестве входных данных указанные вами промежуточные точки и параметры конфигурации. Затем API возвращает ответ, содержащий основной маршрут и один или несколько альтернативных.

Ваш ответ может включать различные типы маршрутов и другие данные в зависимости от запрашиваемых вами полей:

Чтобы включить это в ответ Документация
Наиболее топливо- или энергоэффективный маршрут в зависимости от типа двигателя автомобиля. Как настроить экологичные маршруты
До трех альтернативных маршрутов. Как запросить альтернативные маршруты
Ломаная линия для всего маршрута, для каждого его этапа и для каждого шага на этапе. Запрос полилиний маршрута
Расчетная стоимость проезда с учетом скидок и абонементов, доступных водителю или транспортному средству. Как рассчитать плату за проезд
Локализованные ответы с кодами языков и единицами измерения (имперскими или метрическими). Как запросить локализованные значения
Чтобы отформатировать инструкции по навигации как текстовую строку HTML, добавьте HTML_FORMATTED_NAVIGATION_INSTRUCTIONS в extraComputations. Дополнительные вычисления

Полный список вариантов ввода приведен в разделе Доступные варианты маршрута и Тело запроса.

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

Маски полей

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

В примерах, приведенных в этом документе, показан весь объект ответа без учета масок полей. В рабочей среде ответ будет содержать только те поля, которые вы явно указали в маске.

Дополнительную информацию можно найти в разделе Выбор возвращаемой информации.

Как показывать информацию об авторских правах

При показе результатов поиска пользователям необходимо добавить следующее заявление об авторских правах:

Powered by Google, ©YEAR Google

Пример:

Powered by Google, ©2023 Google

О маршрутах, этапах и шагах

Прежде чем анализировать ответ, полученный от Routes API, ознакомьтесь с компонентами маршрута:

Маршрут, участок и шаг.

Ответ может содержать информацию о каждом из следующих компонентов маршрута:

  • Маршрут – вся поездка от начальной путевой точки через промежуточные до конечной. Маршрут состоит из одного или нескольких участков.

  • Отрезок маршрута. Путь от одной путевой точки маршрута до следующей. Каждый отрезок состоит из одного или нескольких отдельных шагов.

    Маршрут содержит отдельный отрезок для пути от каждой путевой точки до следующей. Например, если маршрут содержит одну начальную путевую точку и одну конечную путевую точку, то маршрут содержит один этап. Для каждой промежуточной путевой точки, добавленной в маршрут после пункта отправления и пункта назначения, API добавляет отдельный участок.

    API не добавляет этап для промежуточной путевой точки. Например, маршрут, который содержит начальную путевую точку, промежуточную путевую точку и конечную путевую точку, содержит только один этап от начальной до конечной точки, проходящий через путевую точку. Подробнее о путевых точках…

  • Шаг. Одна инструкция на этапе маршрута. Шаг – это самая маленькая единица измерения маршрута. Например, шаг может быть описан как "Поверните налево на Мэйн-стрит".

Что содержится в ответе

Объект JSON, представляющий ответ API, содержит следующие свойства верхнего уровня:

  • routes – массив элементов типа Route. Массив routes содержит по одному элементу для каждого маршрута, возвращенного API. Массив может содержать не более пяти элементов: маршрут по умолчанию, экологичный маршрут и до трех альтернативных маршрутов.

  • geocodingResults – массив элементов типа GeocodingResults. Для каждого местоположения в запросе (пункта отправления, пункта назначения или промежуточной путевой точки), указанного в виде строки адреса или кода Plus, API выполняет поиск идентификатора места. Каждый элемент этого массива содержит идентификатор места, соответствующий определенному местоположению. Местоположения, указанные в запросе в виде идентификатора места или координат широты и долготы, не включаются. Если вы указали все местоположения, используя идентификаторы мест или координаты широты и долготы, этот массив не предоставляется.

  • fallbackInfo типа FallbackInfo. Если API не может рассчитать маршрут на основе всех входных параметров, он может использовать другой способ расчета. Если используется резервный режим, это поле содержит подробную информацию о резервном ответе. В противном случае это поле не задано.

Ответ имеет следующий формат:

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

Как интерпретировать массив маршрутов

Ответ содержит массив routes, каждый элемент которого имеет тип Route. Каждый элемент массива представляет собой маршрут от начальной до конечной точки. API всегда возвращает хотя бы один маршрут, который называется маршрутом по умолчанию.

Вы можете запросить дополнительные маршруты. Если вы запросите экологичный маршрут, массив может содержать два элемента: маршрут по умолчанию и экологичный маршрут. Или задайте для computeAlternativeRoutes значение true в запросе, чтобы добавить в ответ до трех альтернативных маршрутов.

Каждый маршрут в массиве идентифицируется с помощью свойства массива routeLabels:

Значение Описание
DEFAULT_ROUTE Определяет маршрут по умолчанию.
FUEL_EFFICIENT Определяет экологичный маршрут.
DEFAULT_ROUTE_ALTERNATE I – альтернативный маршрут.

Массив legs содержит определение каждого этапа маршрута. Остальные свойства, например distanceMeters, duration и polyline,, содержат информацию о маршруте в целом:

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

Из-за текущих дорожных условий и других факторов маршрут по умолчанию и экологичный маршрут могут совпадать. В этом случае массив routeLabels содержит оба ярлыка: DEFAULT_ROUTE и FUEL_EFFICIENT.

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

Массив legs

Каждый объект route в ответе содержит массив legs, в котором каждый элемент массива legs имеет тип RouteLeg. Каждый отрезок в массиве определяет путь от одной путевой точки до следующей. Маршрут всегда содержит хотя бы один участок.

Свойство legs содержит определение каждого шага на отрезке маршрута в массиве steps. Остальные свойства, такие как distanceMeters, duration и polyline, содержат информацию об отрезке.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

Массив steps

Каждый этап в ответе содержит массив steps, где каждый элемент массива steps имеет тип RouteLegStep. Шаг соответствует одной инструкции на отрезке. Отрезок всегда содержит хотя бы один шаг.

Каждый элемент массива steps содержит свойство navigationInstruction типа NavigationInstruction, в котором указана инструкция для шага. Пример:

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

Поле instructions может содержать дополнительную информацию об этапе. Пример:

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

Остальные свойства на этом шаге описывают информацию о нем, например distanceMeters, duration и polyline:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

Как указать язык инструкций для шага

API возвращает информацию о маршруте на местном языке, при необходимости транслитерируя ее в систему письма, понятную пользователю, с учетом предпочитаемого языка. Все компоненты адреса возвращаются на одном языке.

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

  • Если название на указанном языке недоступно, API использует наиболее подходящий вариант.

  • Указанный язык может повлиять на набор результатов, которые возвращает API, и порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например сокращения типов улиц или синонимы, которые могут быть действительны на одном языке, но не на другом. Например, в венгерском языке слова utca и tér являются синонимами слова "улица".

Как интерпретировать массив geocodingResults

Для каждого местоположения в запросе (пункта отправления, пункта назначения или промежуточной путевой точки), указанного в виде строки адреса или кода Plus Code, API пытается найти наиболее подходящее местоположение с соответствующим идентификатором места. Каждый элемент массива geocodingResults содержит поле placeID с местоположением в виде идентификатора места и поле type с типом местоположения, например street_address, premise или airport.

Массив geocodingResults содержит три поля:

  • origin – идентификатор места отправления, если оно было указано в виде строки адреса или кода Plus Code. В противном случае это поле не будет включено в ответ.

  • destination – идентификатор места назначения, если оно было указано в виде строки адреса или кода Plus Code. В противном случае это поле не будет включено в ответ.

  • intermediates – массив, содержащий идентификаторы мест всех промежуточных путевых точек, указанных в виде строки адреса или кода Plus Code. Если вы укажете промежуточную путевую точку, используя идентификатор места или координаты широты и долготы, она будет исключена из ответа. Чтобы определить, какая промежуточная путевая точка в запросе соответствует идентификатору места в ответе, используйте свойство intermediateWaypointRequestIndex в ответе.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

Как интерпретировать локализованные значения ответов

Локализованные значения ответа – это дополнительное поле ответа, в котором содержится локализованный текст для возвращенных значений параметров. Текст на языке пользователя предоставляется для продолжительности поездки, расстояния и системы единиц (метрической или имперской). Чтобы запросить локализованные значения, используйте маску поля. Вы можете указать язык и систему единиц измерения или использовать значения, полученные от API. Подробнее LocalizedValues…

Например, если вы укажете код языка для немецкого (de) и имперские единицы измерения, то получите значение distanceMeters, равное 49889,7, а также локализованный текст, в котором расстояние будет указано на немецком языке и в имперских единицах измерения: "31 Meile".

Вот пример того, как будут выглядеть локализованные значения:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

Если вы не укажете язык или систему единиц, API определит их следующим образом:

  • Метод ComputeRoutes определяет местоположение и единицы измерения расстояния по начальной путевой точке. Таким образом, для запроса маршрута в США API определяет язык en-US и единицы измерения IMPERIAL.
  • Метод ComputeRouteMatrix по умолчанию использует язык en-US и метрические единицы.