Esta página foi traduzida pela API Cloud Translation.

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 a rota default e uma ou mais rotas alternativas.

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

Para incluir isso na resposta	Consultar esta documentação
O trajeto mais eficiente em termos de combustível ou energia com base no tipo de motor do veículo.	Configurar rotas ecológicas
Até três trajetos alternativos	Solicitar rotas alternativas
A polilinha de um trajeto inteiro, para cada trecho de um trajeto e para cada etapa de um trecho.	Solicitar polilinhas do trajeto
Os pedágios estimados, considerando todos os descontos ou passes livres disponíveis para o motorista ou veículo.	Calcular tarifas de pedágio
Respostas localizadas por códigos de idioma e unidade de medida (imperiais ou métricas).	Solicitar valores localizados
Para formatar as instruções de navegação como uma string de texto HTML, adicione `HTML_FORMATTED_NAVIGATION_INSTRUCTIONS` a `extraComputations`.	Cálculos extras

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

Usando a resposta, é possível fornecer aos seus clientes as informações necessárias para selecionar a rota apropriada para seus requisitos.

Sobre as máscaras de campo

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

Os exemplos neste documento mostram todo o objeto de resposta sem considerar as máscaras de campo. Em um ambiente de produção, sua resposta incluiria apenas os campos que você especificar explicitamente na máscara de campo.

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

Sobre a exibição de direitos autorais

Você deve incluir a seguinte declaração de direitos autorais ao exibir os resultados para seus usuários:

Powered by Google, ©YEAR Google

Exemplo:

Sobre trajetos, trechos e passos

Antes de analisar a resposta retornada pela API Routes, é preciso entender os componentes que compõem uma rota:

O trajeto, o trecho e a etapa.

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

Trajeto: toda a viagem desde o waypoint de origem, passando por quaisquer 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 até o próximo waypoint no trajeto. Cada trecho consiste em uma ou mais etapas discretas.

Um trajeto contém um trecho separado entre cada waypoint e o próximo. Por exemplo, se o trajeto tiver um único waypoint de origem e um de destino, ele conterá um único trecho. Para cada waypoint adicional que você adicionar ao trajeto depois da origem e do destino, chamado waypoint intermediário, a API adiciona um trecho separado.

A API não adiciona um trecho para um waypoint intermediário de pass-through. 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 até o destino enquanto passa pelo waypoint. Para mais informações sobre os waypoints de passagem, consulte Definir um waypoint de passagem.
Etapa: uma única instrução ao longo do trecho de um trajeto. Uma etapa é a menor unidade atômica de uma rota. Por exemplo, uma etapa pode indicar "Vire à esquerda na rua principal".

Qual é a 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 um Plus code, a API executa uma pesquisa de ID de lugar. Cada elemento dessa matriz contém o ID correspondente a uma localização. Os locais na solicitação especificados como um ID de lugar ou coordenadas de latitude/longitude não são incluídos. Se você tiver especificado 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 uma rota de todas as propriedades de entrada, ela poderá usar outra maneira de cálculo. Quando o modo substituto é usado, esse campo contém informações detalhadas sobre a resposta substituta. Caso contrário, o campo não será definido.

A resposta tem o seguinte formato:

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

Decodificar a matriz de rotas

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 uma rota, chamada de rota padrão.

É possível solicitar outros trajetos. Se você solicitar uma rota ecológica, a matriz poderá conter dois elementos: a rota padrão e a ecológica. Ou defina computeAlternativeRoutes como true na solicitação para adicionar até três trajetos alternativos à resposta.

Cada trajeto na matriz é identificado pela propriedade routeLabels:

Valor	Descrição
`DEFAULT_ROUTE`	Identifica a rota padrão.
`FUEL_EFFICIENT`	Identifica o trajeto ecológico.
`DEFAULT_ROUTE_ALTERNATE`	Indica uma rota alternativa.

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 atuais de trânsito e outros fatores, o trajeto padrão e o 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"
      ],
     …
    }
  ]
}

Compreender a matriz de trechos

Cada route na resposta contém uma matriz legs, em que cada elemento de 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 demais propriedades, 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. Um passo corresponde a uma única instrução ao longo do trecho. Um trecho sempre tem pelo menos um passo.

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

O instructions pode conter mais informações 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 demais propriedades da etapa descrevem informações sobre ela, como distanceMeters, duration e polyline:

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

Especifique o idioma das instruções da etapa

A API retorna informações de rota no idioma local, transliteradas para um script que pode ser lido pelo usuário, se necessário, enquanto observa o idioma preferido. Os componentes de endereço são todos retornados no mesmo idioma.

Use o parâmetro languageCode de uma solicitação para definir explicitamente o idioma da rota na lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, portanto, essa lista pode não estar completa.
Se um nome não estiver disponível no idioma especificado, a API usará a correspondência mais próxima.
A linguagem especificada pode influenciar o conjunto de resultados que a API escolhe retornar e a ordem em que são retornados. O geocodificador interpreta abreviações de maneiras diferentes dependendo do idioma, como 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 para ruas em húngaro.

Entender a matriz GeocodingResults

Para cada local na solicitação (origem, destino ou waypoint intermediário) que foi especificado como uma string de endereço ou um Plus code, a API tenta encontrar o local mais relevante com um ID de lugar correspondente. Cada elemento da matriz geocodingResults contém o campo placeID, que contém a localização como um ID de lugar, e um campo type especificando 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 um Plus Code, o ID do lugar da origem. Caso contrário, esse campo é omitido da resposta.
destination: se especificado como uma string de endereço ou um Plus Code, o ID de lugar do destino. Caso contrário, esse campo será omitido da resposta.
intermediates: uma matriz que contém o ID de lugar de qualquer waypoint intermediário especificado como uma string de endereço ou um Plus Code. Se você especificar um waypoint intermediário usando um ID de 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 de 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âmetro retornados. O texto localizado é fornecido para a duração da viagem, a distância e o sistema de unidades (métrico ou imperial). É possível solicitar valores localizados usando uma máscara de campo. É possível 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 unidades em alemão (de) e imperiais, terá um valor para distanceMeters de 49889,7, mas também um texto localizado fornecendo essa medida de distância em unidades alemãs e imperiais, ou seja, "31 Meile".

Veja um exemplo do que seria exibido para valores localizados:

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

Observação: você recebe dois valores para a duração esperada: duration usa o modelo de tráfego especificado e static_duration não leva o tráfego em consideração. Portanto, se o modelo de tráfego solicitado for TRAFFIC_UNAWARE, esses tempos serão idênticos.

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 localização 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 assume como padrão o idioma "en-US" e unidades METRIC.