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

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

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

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

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

Маски полей

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

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

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

Об отображении авторских прав

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

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:

Массив 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 использует английский язык (США) и метрическую систему мер.