Especificar locais para um trajeto

Desenvolvedores do Espaço Econômico Europeu (EEE)

Para calcular um trajeto, é necessário especificar pelo menos os locais de origem e destino. Você define esses locais como waypoints no trajeto.

Além da origem e do destino, é possível especificar diferentes tipos de waypoints e como processá-los em um trajeto. Para mais informações e exemplos, consulte estes tópicos:

Especificar locais para um trajeto

Para representar um local, crie um objeto Waypoint (REST) ou Waypoint (gRPC). Na definição do waypoint, é possível especificar um local de uma destas maneiras:

ID do lugar (preferencial)
Coordenadas de latitude/longitude
String de endereço ("Chicago, IL" ou "Darwin, NT, Australia")
Token de ponto de navegação
Plus Code

É possível especificar locais para todos os waypoints em uma solicitação da mesma maneira ou misturá-los. Por exemplo, use coordenadas de latitude/longitude para o waypoint de origem e um ID de lugar para o waypoint de destino.

Para eficiência e precisão, use IDs de lugares em vez de coordenadas de latitude/longitude ou strings de endereço. Os IDs de lugares são explicitamente exclusivos e oferecem benefícios de geocodificação para o roteamento, como pontos de acesso e variáveis de trânsito. Eles ajudam a evitar as seguintes situações que podem resultar de outras maneiras de especificar um local:

O uso de coordenadas de latitude/longitude pode resultar no alinhamento do local à estrada mais próxima dessas coordenadas, que pode não ser um ponto de acesso à propriedade ou até mesmo uma estrada que leve ao destino de forma rápida ou segura.
As strings de endereço precisam ser geocodificadas pela API Routes para serem convertidas em coordenadas de latitude/longitude antes que um trajeto possa ser calculado. Essa conversão pode afetar a performance.

Especificar um local como um ID de lugar

É possível usar um ID de lugar para especificar o local de um waypoint. Como as coordenadas de latitude e longitude são alinhadas às estradas, um ID de lugar pode oferecer melhores resultados em algumas circunstâncias.

Recupere IDs de lugares na API Geocoding e na API Places (incluindo o Place Autocomplete). Para mais informações sobre IDs de lugares, consulte a visão geral de IDs de lugares.

O exemplo a seguir usa a propriedade placeId para transmitir um ID de lugar para origin e destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Especificar um local como coordenadas de latitude e longitude

Para definir o local em um waypoint, especifique o Location (REST) ou Location(gRPC) usando coordenadas de latitude/longitude.

Por exemplo, especifique um waypoint para a rota origin e destination usando coordenadas de latitude e longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Especificar um local como uma string de endereço

As strings de endereço são endereços literais representados por uma string (como "1600 Amphitheatre Parkway, Mountain View, CA"). A geocodificação é o processo de conversão de uma string de endereço em coordenadas de latitude e longitude (como latitude 37.423021 e longitude -122.083739).

Quando você transmite uma string de endereço como o local de um waypoint, a API Routes geocodifica internamente a string para convertê-la em coordenadas de latitude e longitude.

Por exemplo, para calcular um trajeto, especifique um waypoint para a rota origin e destination usando strings de endereço:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

Neste exemplo, a API Routes geocodifica os dois endereços para convertê-los em coordenadas de latitude e longitude.

Se o valor do endereço for ambíguo, a API Routes poderá invocar uma pesquisa para desambiguar endereços semelhantes. Por exemplo, "1st Street" pode ser um valor completo ou parcial para "1st street NE" ou "1st St SE". Esse resultado pode ser diferente do retornado pela API Geocoding. É possível evitar possíveis interpretações incorretas usando IDs de lugares.

Definir a região do endereço

Se você transmitir uma string de endereço incompleta como o local de um waypoint, a API poderá usar as coordenadas de latitude/longitude geocodificadas incorretas. Por exemplo, você faz uma solicitação especificando "Toledo" como a origem e "Madrid" como o destino de um trajeto de carro:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

Neste exemplo, "Toledo" é interpretado como uma cidade no estado de Ohio, nos Estados Unidos, e não na Espanha. Portanto, a solicitação retorna uma matriz vazia, o que significa que não há trajetos:

{
  []
}

É possível configurar a API para retornar resultados direcionados a uma região específica incluindo o parâmetro regionCode. Esse parâmetro especifica o código regional como um ccTLD ("domínio de nível superior") valor de dois caracteres. A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade do "Reino Unido da Grã-Bretanha e Irlanda do Norte").

Uma solicitação de rotas de "Toledo" para "Madrid" que inclui o parâmetro regionCode retorna resultados adequados porque "Toledo" é interpretado como uma cidade na Espanha:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

A resposta agora contém o trajeto calculado de Toledo, Espanha, para Madrid, Espanha:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Especificar um local como um token de ponto de navegação

Um token de ponto de navegação é uma string que codifica um local e um contexto de trajeto adicional. Os tokens de ponto de navegação podem fornecer um roteamento preciso para pontos de acesso específicos perto de entradas, docas de carregamento ou áreas de embarque designadas. Isso é útil em casos como entrega de comida ou carona compartilhada, em que o ponto de embarque ou desembarque pode ser ambíguo.

É possível receber um token de ponto de navegação chamando o método Destinations da API Geocoding.

Para especificar um token de ponto de navegação:

Receba um navigationPointToken do método SearchDestinations da API Geocoding. Consulte a documentação da API Geocoding para mais informações.
Crie um waypoint transmitindo o navigationPointToken.

O exemplo a seguir usa a propriedade navigation_point_token para transmitir um token de ponto de navegação para origin e destination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

Especificar um local como um Plus Code

Muitas pessoas não têm um endereço preciso, o que pode dificultar o recebimento de entregas. Ou, pessoas com um endereço podem preferir receber entregas em locais mais específicos, como uma entrada traseira ou uma doca de carregamento.

O Plus Code é como endereço para pessoas ou lugares que não têm um endereço real. Em vez de nomes de rua e números, os Plus Codes são baseados em coordenadas de latitude/longitude e são exibidos como números e letras.

O Google desenvolveu os Plus Codes para oferecer o benefício dos endereços a todos e tudo. Um Plus Code é uma referência de local codificada, derivada de coordenadas de latitude/longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14m x 14m na Linha do Equador) ou menor. É possível usar os Plus Codes em vez de endereços nos lugares em que não existem ou quando os imóveis não estão numerados ou as ruas não têm nome.

Os Plus Codes precisam ser formatados como um código global ou um código composto:

Um código global é composto por um código de área de quatro caracteres e um código local de seis caracteres ou mais.
Por exemplo, para o endereço "1600 Amphitheatre Parkway, Mountain View, CA", o código global é "849V" e o código local é "CWC8+R9". Em seguida, use o Plus Code de 10 caracteres para especificar o valor do local como "849VCWC8+R9".
Um código composto é composto por um código local de seis caracteres ou mais código local combinado com um local explícito.
Por exemplo, o endereço "450 Serra Mall, Stanford, CA 94305, EUA" tem um código local de "CRHJ+C3". Para um endereço composto, combine o código local com a cidade, o estado, o CEP e a parte do país do endereço no formato "CRHJ+C3 Stanford, CA 94305, EUA".

Por exemplo, calcule um trajeto especificando um waypoint para a rota origin e destination usando Plus Codes:
```
{
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}
```

Os Plus Codes são compatíveis com as APIs da Plataforma Google Maps, incluindo Place Autocomplete, Place Details, API Directions (legada), e API Geocoding. Por exemplo, é possível usar a API Geocoding para geocodificar inversamente um local especificado por coordenadas de latitude/longitude para determinar o Plus Code do local.

Especificar locais para um trajeto Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Especificar locais para um trajeto

Especificar um local como um ID de lugar

Especificar um local como coordenadas de latitude e longitude

Especificar um local como uma string de endereço

Definir a região do endereço

Especificar um local como um token de ponto de navegação

Especificar um local como um Plus Code

Especificar locais para um trajeto