Esta página foi traduzida pela API Cloud Translation.

Analisar a resposta do trajeto

Quando a API Routes calcula uma rota, ela usa os pontos de passagem e os parâmetros de configuração que você fornece como entrada. A API retorna uma resposta que contém a rota padrão e uma ou mais rotas alternativas.

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

Para incluir isso na resposta	Consulte esta documentação
O trajeto mais econômico com base no tipo de motor do veículo.	Configurar trajetos ecológicos
Até três rotas alternativas	Solicitar rotas alternativas
A polilinha de um trajeto inteiro, para cada trecho e para cada etapa de um trecho.	Solicitar polilinhas do trajeto
Os pedágios estimados, considerando os descontos ou tags disponíveis para o motorista ou veículo.	Calcular taxas de pedágio
Respostas localizadas por códigos de idioma e unidade de medida (imperial ou métrica).	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 conferir a lista completa de opções de entrada, consulte Opções de rota disponíveis e o Corpo da solicitação.

Com a resposta, você pode fornecer aos clientes as informações necessárias para selecionar a rota adequada para os requisitos deles.

Sobre as máscaras de campo

Ao chamar um método para calcular uma rota, é necessário especificar uma máscara de campo que define 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 inclui apenas os campos especificados explicitamente na máscara de campo.

Para mais informações, consulte Escolher as informações a serem retornadas.

Sobre a exibição de direitos autorais

Inclua a seguinte declaração de direitos autorais ao mostrar os resultados aos usuários:

Powered by Google, ©YEAR Google

Exemplo:

Sobre rotas, etapas e trajetos

Antes de analisar a resposta retornada pela API Routes, você precisa 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 rota:

Trajeto: toda a viagem do ponto de passagem de origem, passando por todos os pontos de passagem intermediários, até o ponto de passagem de destino. Uma rota consiste em um ou mais trechos.
Trajeto: o caminho de um ponto de passagem em um trajeto até o próximo ponto de passagem no mesmo trajeto. Cada trecho consiste em um ou mais passos distintos.

Uma rota contém um trecho separado para o caminho de cada ponto de passagem até o próximo. Por exemplo, se o trajeto tiver um único waypoint de origem e um único waypoint de destino, ele terá um único trecho. Para cada ponto de passagem adicional adicionado à rota após a origem e o destino, chamado de ponto de passagem intermediário, a API adiciona uma etapa separada.

A API não adiciona uma etapa para um ponto de referência intermediário de passagem. Por exemplo, um trajeto que contém um waypoint de origem, um waypoint intermediário 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 de uma perna de uma rota. Uma etapa é a unidade mais elementar de uma rota. Por exemplo, uma etapa pode indicar "Vire à esquerda na Rua Principal'.

O que tem 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: a rota padrão, a rota ecológica e até três rotas alternativas.
geocodingResults, uma matriz de elementos do tipo GeocodingResults. Para cada local na solicitação (origem, destino ou ponto de passagem intermediário) especificado como uma string de endereço ou um Plus Code, a API realiza uma pesquisa de ID de lugar. Cada elemento dessa matriz contém o ID do lugar correspondente a um local. Os locais na solicitação especificados como um ID de 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 uma rota de todas as propriedades de entrada, ela poderá usar uma maneira diferente de cálculo. Quando o modo de fallback é usado, esse campo contém informações detalhadas sobre a resposta de fallback. Caso contrário, esse campo não será definido.

A resposta tem a seguinte forma:

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

Decifrar 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 uma rota completa da origem ao destino. A API sempre retorna pelo menos uma rota, chamada de rota padrão.

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

Cada rota na matriz é identificada com a propriedade de matriz routeLabels:

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

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 a outros fatores, a rota padrão e a rota ecológica podem ser as mesmas. 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 pernas

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 até 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 de matriz steps é do tipo RouteLegStep. Uma etapa corresponde a uma única instrução ao longo do trajeto. Uma etapa 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"
}

O instructions pode conter mais informações sobre a etapa. Por 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 das etapas

A API retorna informações de rota no idioma local, transliteradas para um script legível 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 com frequência, portanto, esta 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.
O idioma especificado pode influenciar o conjunto de resultados que a API escolhe para retornar e a ordem em que eles são retornados. O codificador geográfico interpreta abreviações de formas variadas 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 outros. Por exemplo, utca e tér são sinônimos para 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 de lugar correspondente. Cada elemento da matriz geocodingResults contém o campo placeID que contém o local 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 como um Plus Code, o ID do lugar da origem. Caso contrário, este campo será omitido da resposta.
destination: se foi especificado como uma string de endereço ou como um Plus Code, o ID do lugar do destino. Caso contrário, esse campo será omitido da resposta.
intermediates: uma matriz que contém o ID de lugar de todos os waypoints intermediários especificados 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 ponto de passagem 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âmetro 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, vai receber um valor de distanceMeters de 49889,7, mas também um texto localizado que fornece essa medição de distância em alemão e unidades imperiais, ou seja, "31 Meile".

Confira um exemplo do que você vai encontrar 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 considera o tráfego. 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 o local e as unidades de distância do ponto de passagem de origem. Portanto, para uma solicitação de roteamento nos EUA, a API infere a linguagem en-US e as unidades IMPERIAL.
O método ComputeRouteMatrix tem como padrão o idioma "en-US" e as unidades METRIC.