Analisar a resposta do trajeto

Quando a API Routes calcula um trajeto, ela usa os waypoints e os parâmetros de configuração fornecidos como entrada. Em seguida, a API retorna uma resposta que contém o trajeto padrão e um ou mais trajetos alternativos.

Sua resposta pode incluir diferentes tipos de trajetos e outros dados, com base nos campos solicitados:

Para conferir a lista completa de opções de entrada, consulte Opções de trajeto disponíveis e o Corpo da solicitação.

Usando a resposta, você pode fornecer aos clientes as informações necessárias para selecionar o trajeto adequado às necessidades deles.

Sobre máscaras de campo

Ao chamar um método para calcular um trajeto, é necessário especificar uma máscara de campo que defina quais campos você quer que sejam retornados na resposta. Não há uma lista padrão de campos retornados. Se você omitir essa lista, os métodos vão retornar um erro.

Os exemplos neste documento mostram o objeto de resposta inteiro sem considerar as máscaras de campo. Em um ambiente de produção, a resposta só incluiria os campos especificados explicitamente na máscara de campo.

Para mais informações, consulte Escolher quais informações retornar.

Sobre a exibição de direitos autorais

Você precisa incluir a seguinte declaração de direitos autorais ao mostrar os resultados aos usuários:

Powered by Google, ©YEAR Google

Exemplo:

Powered by Google, ©2023 Google

Sobre trajetos, trechos e etapas

Antes de analisar a resposta retornada pela API Routes, você precisa entender os componentes que compõem um trajeto:

Sua resposta pode conter informações sobre cada um desses componentes do trajeto:

• Trajeto: toda a viagem do waypoint de origem, passando por waypoints intermediários, até o waypoint de destino. Um trajeto consiste em um ou mais trechos.

• Trecho: o caminho de um waypoint em um trajeto para o próximo waypoint no trajeto. Cada trecho consiste em uma ou mais etapas discretas.

  Um trajeto contém um trecho separado para o caminho de cada waypoint para o próximo. Por exemplo, se o trajeto contiver um único waypoint de origem e um único waypoint de destino, ele terá um único trecho. Para cada waypoint adicional que você adicionar ao trajeto após a origem e o destino, chamado de waypoint intermediário, a API adiciona um trecho separado.

  A API não adiciona um trecho para um waypoint intermediário de passagem. Por exemplo, um trajeto que contém um waypoint de origem, um waypoint intermediário de passagem e um waypoint de destino contém apenas um trecho da origem ao destino, passando pelo waypoint. Para mais informações sobre waypoints de passagem, consulte Definir um waypoint de passagem.

• Etapa: uma única instrução ao longo do trecho de um trajeto. Uma etapa é a unidade mais atômica de um trajeto. Por exemplo, uma etapa pode indicar "Vire à esquerda na Rua Principal".

O que há na resposta

O objeto JSON que representa a resposta da API contém as seguintes propriedades de nível superior:

• routes, uma matriz de elementos do tipo Route. A matriz routes contém um elemento para cada trajeto retornado pela API. A matriz pode conter no máximo cinco elementos: o trajeto padrão, o trajeto ecológico e até três trajetos alternativos.

• geocodingResults, uma matriz de elementos do tipo GeocodingResults. Para cada local na solicitação (origem, destino ou waypoint intermediário ) especificado como uma string de endereço ou como um Plus Code, a API realiza uma pesquisa de ID do lugar. Cada elemento dessa matriz contém o ID do lugar correspondente a um local. Os locais na solicitação especificados como um ID do lugar ou como coordenadas de latitude/longitude não são incluídos. Se você especificou todos os locais usando IDs de lugar ou coordenadas de latitude e longitude, essa matriz não será fornecida.

• fallbackInfo, do tipo FallbackInfo. Se a API não conseguir calcular um trajeto de todas as propriedades de entrada, ela poderá usar uma maneira diferente de cálculo. Quando o modo de substituição é usado, esse campo contém informações detalhadas sobre a resposta de substituição. Caso contrário, esse campo não será definido.

A resposta tem o formato:

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

Decifrar a matriz de trajetos

A resposta contém a matriz routes, em que cada elemento da matriz é do tipo Route. Cada elemento da matriz representa um trajeto inteiro da origem ao destino. A API sempre retorna pelo menos um trajeto, chamado de trajeto padrão.

Você pode solicitar trajetos adicionais. Se você solicitar um trajeto ecológico, a matriz poderá conter dois elementos: o trajeto padrão e o trajeto ecológico. Ou defina computeAlternativeRoutes como true na solicitação para adicionar até três trajetos alternativos à resposta.

Cada trajeto na matriz é identificado com a propriedade da matriz routeLabels:

A matriz legs contém a definição de cada trecho do trajeto. As propriedades restantes, como distanceMeters, duration e polyline,, contêm informações sobre o trajeto como um todo:

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

Devido às condições de direção atuais e outros fatores, o trajeto padrão e o trajeto ecológico podem ser os mesmos. Nesse caso, a matriz routeLabels contém os dois rótulos: DEFAULT_ROUTE e FUEL_EFFICIENT.

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

Entender a matriz de trechos

Cada route na resposta contém uma matriz legs, em que cada elemento da matriz legs é do tipo RouteLeg. Cada trecho na matriz define o caminho de um waypoint para o próximo ao longo do trajeto. Um trajeto sempre contém pelo menos um trecho.

A propriedade legs contém a definição de cada etapa ao longo do trecho na matriz steps. As propriedades restantes, como distanceMeters, duration e polyline, contêm informações sobre o trecho.

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

Entender a matriz de etapas

Cada trecho na resposta contém uma matriz steps, em que cada elemento da matriz steps é do tipo RouteLegStep. Uma etapa corresponde a uma única instrução ao longo do trecho. Um trecho sempre contém pelo menos uma etapa.

Cada elemento na matriz steps inclui a propriedade navigationInstruction, do tipo NavigationInstruction, que contém a instrução da etapa. Exemplo:

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

As instructions podem conter informações adicionais sobre a etapa. Exemplo:

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

As propriedades restantes na etapa descrevem informações sobre a etapa, como distanceMeters, duration e polyline:

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

Especificar o idioma das instruções da etapa

A API retorna informações de trajeto no idioma local, transliteradas para um script legível pelo usuário, se necessário, observando o idioma preferido. Os componentes de endereço são retornados no mesmo idioma.

• Use o parâmetro languageCode de uma solicitação para definir explicitamente o idioma do trajeto na lista de idiomas aceitos. O Google costuma atualizar os idiomas aceitos, então essa lista pode não ser exaustiva.

• Se um nome não estiver disponível no idioma especificado, a API usará a correspondência mais próxima.

• O idioma especificado pode influenciar o conjunto de resultados que a API escolhe retornar e a ordem em que eles são retornados. O geocodificador interpreta abreviações de maneira diferente, dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro. Por exemplo, utca e tér são sinônimos de rua em húngaro.

Entender a matriz geocodingResults

Para cada local na solicitação (origem, destino ou waypoint intermediário ) especificado como uma string de endereço ou como um Plus Code, a API tenta encontrar o local mais relevante que tenha um ID do lugar correspondente. Cada elemento da geocodingResults matriz contém o campo placeID com o local como um ID do lugar e um campo type que especifica o tipo de local , como street_address, premise ou airport.

A matriz geocodingResults contém três campos:

• origin: se foi especificado como uma string de endereço ou como um Plus Code, o ID do lugar de origem. Caso contrário, esse campo será omitido da resposta.

• destination: se foi especificado como uma string de endereço ou como um Plus Code, o ID do lugar de destino. Caso contrário, esse campo será omitido da resposta.

• intermediates: uma matriz que contém o ID do lugar de waypoints intermediários especificados como uma string de endereço ou como um Plus Code. Se você especificar um waypoint intermediário usando um ID do lugar ou coordenadas de latitude e longitude, ele será omitido da resposta. Use a propriedade intermediateWaypointRequestIndex na resposta para determinar qual waypoint intermediário na solicitação corresponde ao ID do lugar na resposta.

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

Entender os valores de resposta localizados

Os valores de resposta localizados são um campo de resposta adicional que fornece texto localizado para valores de parâmetros retornados. O texto localizado é fornecido para duração da viagem, distância e sistema de unidades (métrico ou imperial). Você solicita valores localizados usando uma máscara de campo e pode especificar o idioma e o sistema de unidades ou usar os valores inferidos pela API. Para mais detalhes, consulte LocalizedValues.

Por exemplo, se você especificar um código de idioma para alemão (de) e unidades imperiais, receberá um valor para distanceMeters de 49889,7, mas também texto localizado que fornece essa medida de distância em alemão e unidades imperiais, ou seja, "31 Meile".

Confira um exemplo do que você veria para valores localizados:

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

Se você não especificar o idioma ou o sistema de unidades, a API vai inferir o idioma e as unidades da seguinte maneira:

• O método ComputeRoutes infere as unidades de local e distância do waypoint de origem. Portanto, para uma solicitação de roteamento nos EUA, a API infere o idioma en-US e as unidades IMPERIAL.
• O método ComputeRouteMatrix usa o idioma 'en-US' e as unidades METRIC como padrão.