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. Em seguida, 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 trajetos alternativos Solicitar rotas alternativas
A polilinha de um trajeto inteiro, de cada trecho de um trajeto e de cada etapa de um trecho. Solicitar polilinhas do trajeto
Os pedágios estimados, considerando os descontos ou passes livres para o motorista ou veículo. Calcular tarifas de pedágio
Respostas localizadas por códigos de idiomas e unidades de medida (imperiais 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 ao extraComputations. Computação extra

Para 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, você deve especificar um campo máscara que define quais campos você quer retornar na resposta. Não há lista padrão de campos retornados. Se você omitir essa lista, os métodos retornarão uma erro.

Os exemplos neste documento mostram todo o objeto de resposta sem levar máscaras de campo em consideração. 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ê deve incluir a seguinte declaração de direitos autorais ao exibir os resultados aos seus usuários:

Powered by Google, ©YEAR Google

Exemplo:

Powered by Google, ©2023 Google

Sobre trajetos, trechos e passos

Antes de analisar a resposta retornada pela API Routes, deve ter uma compreensão dos componentes que compõem um trajeto:

O trajeto, o trecho e a etapa.

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

  • Trajeto: a viagem inteira desde o waypoint de origem, passando por qualquer waypoints intermediários até o waypoint de destino. Uma rota consiste em um ou mais trechos.

  • Trecho: o caminho de um ponto de referência em um trajeto até o próximo na trajeto. Cada trecho consiste em uma ou mais etapas distintas.

    Uma rota contém um trecho separado para o caminho de cada ponto de passagem até o próximo. Por exemplo, se o trajeto contiver um único waypoint de origem e um único waypoint de destino, a rota terá um único trecho. Para cada outro ponto de referência que você adicionar ao trajeto depois da origem e do 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. Para exemplo, um trajeto que contém um waypoint de origem, um trajeto waypoint intermediário, e um waypoint de destino contém apenas um trecho da da origem até o 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. A etapa é a etapa mais unidade atômica de uma rota. Por exemplo, uma etapa pode indicar "Vire à esquerda na Street".

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 Rota. 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 ecologicamente correto e até três trajetos alternativos.

  • geocodingResults, uma matriz de elementos do tipo GeocodingResults. Para cada local na solicitação (origem, destino ou valor intermediário) waypoint) que você especificou como uma string de endereço ou como um Plus code; a API realiza uma pesquisa de ID de lugar. Cada elemento dessa matriz contém o ID de lugar correspondente a um local. Locais na solicitação especificados como um ID de lugar ou como coordenadas de latitude/longitude não são incluídas. Se você especificou todos os locais usando IDs de lugar ou latitude e longitude , essa matriz não é 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. Ao usar substitutos é usado, este campo contém informações detalhadas sobre o estado resposta. Caso contrário, este 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)
  }
}

Decifrar a matriz de rotas

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

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

Cada rota na matriz é identificada pela 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. Os valores restantes propriedades, 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 e a rota padrão o trajeto ecológico pode ser o mesmo. 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 matriz legs o elemento é do tipo RouteLeg (em inglês). 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 matriz steps o elemento é do tipo RouteLegStep. Uma etapa corresponde a uma única instrução ao longo do trajeto. Um trecho sempre contém ao menos uma etapa.

Cada elemento na matriz steps inclui o navigationInstruction. propriedade, 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 da etapa descrevem informações sobre ela, como 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 as informações do trajeto no idioma local, transliteradas para um um script legível para o usuário, se necessário, enquanto observa o idioma de destino. Todos os componentes de endereço são retornados no mesmo idioma.

  • Use o parâmetro languageCode de um solicitação para defina explicitamente o idioma da rota na lista de opções idiomas. O Google atualiza frequentemente idiomas, portanto, esta lista pode não estar completa.

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

  • O idioma especificado pode influenciar o conjunto de resultados que o a API escolhe retornar e a ordem em que eles são retornados. O o geocodificador interpreta abreviações de maneiras diferentes dependendo do idioma, como abreviações de tipos de ruas ou sinônimos que possam ser válidos em uma em outro idioma, mas não em outro. 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 valor intermediário) waypoint) especificado como uma string de endereço ou como um Plus Code; o A API tenta encontrar o local mais relevante que tenha um local correspondente ID. Cada elemento do geocodingResults a matriz contém o campo placeID contendo o local como um ID de lugar e um campo type especificando o local tipo, 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 de 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, este campo é omitido da resposta.

  • intermediates: uma matriz que contém o ID do lugar de qualquer ponto de referência intermediário especificado como uma string de endereço ou como um Plus Code. Se você especificar um ponto de passagem intermediário usando um ID de lugar ou coordenadas de latitude e longitude, ele será omitido da resposta. Use o intermediateWaypointRequestIndex na resposta para determinar qual ponto de referência intermediário na solicitação corresponde ao ID de local em a 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 os 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 podem especificar o idioma e sistema de medidas ou use 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 imperial de unidades, terá um valor de distanceMeters de 49.889,7, mas também a localização de textos que fornecem essa medida de distância em alemão e unidades imperiais, portanto, "31 Meile".

Veja 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 medidas, a API vai inferir o idioma e unidades da seguinte forma:

  • O método ComputeRoutes infere o local e a distância de unidades do ponto de referência. Para solicitações de roteamento nos EUA, a API infere unidades de idioma en-US e IMPERIAL.
  • O método ComputeRouteMatrix tem como padrão "en-US" idioma e METRIC.