Especificar locais para um trajeto

Para calcular um trajeto, especifique no mínimo os locais de origem e destino. Você define esses locais como waypoints no trajeto.

Além de origem e destino, você pode 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

Você representa um local criando um objeto Waypoint (REST) ou Waypoint (gRPC). Na definição do waypoint, é possível especificar um local das seguintes maneiras:

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

Para aumentar a eficiência e a precisão, use IDs de lugar em vez de coordenadas de latitude/longitude ou strings de endereço. Eles são explicitamente explícitos e oferecem benefícios de geocodificação para trajetos, como pontos de acesso e variáveis de tráfego. Eles ajudam a evitar as seguintes situações que podem resultar de outras formas de especificar um local:

  • O uso de coordenadas de latitude/longitude pode fazer com que o local seja direcionado para a via mais próxima dessas coordenadas, que pode não ser um ponto de acesso à propriedade ou até mesmo uma via que leva ao destino com rapidez ou segurança.
  • Antes de calcular um trajeto, as strings de endereço precisam ser geocodificadas pela API Routes para convertê-las em coordenadas de latitude/longitude. Essa conversão pode afetar a performance.

Especificar um local como ID de lugar

Você pode usar um ID de lugar para especificar a localização de um waypoint. Como as coordenadas de latitude e longitude são alinhadas às vias, você pode achar que um ID de lugar oferece resultados melhores em algumas circunstâncias.

Recupere IDs de lugares da API Geocoding e da API Places (incluindo Place Autocomplete). Para saber mais sobre IDs de lugar, consulte a Visão geral de IDs de lugar.

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 Local (REST) ou Location(gRPC) usando coordenadas de latitude/longitude.

Por exemplo, especifique um waypoint para o trajeto origin e destination usando as coordenadas 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 converter 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 a localização 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 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 diferenciar endereços semelhantes. Por exemplo, "1a Rua" pode ser um valor completo ou parcial para "1a rua NE" ou "1a Rua SE". Esse resultado pode ser diferente daquele retornado pela API Geocoding. Você pode evitar possíveis interpretações erradas usando IDs de lugar.

Defina a região do endereço

Se você transmitir uma string de endereço incompleta como o local de um waypoint, a API pode usar as coordenadas de latitude/longitude geocodificadas incorretas. Por exemplo, você faz uma solicitação especificando "Toledo" como a origem e "Madri" 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, não na Espanha. Portanto, a solicitação retorna uma matriz vazia, o que significa que não há rotas:

{
  []
}

É possível configurar a API para retornar resultados direcionados para uma região específica incluindo o parâmetro regionCode. Este parâmetro especifica o código regional como um valor de dois caracteres de ccTLD ("domínio de nível superior"). 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 "Reino Unido da Grã-Bretanha e Irlanda do Norte").

Uma solicitação de rota de "Toledo" a "Madri" que inclua o parâmetro regionCode retorna resultados apropriados 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, até Madri, Espanha:

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

Especificar um local como Plus Code

Muitas pessoas não têm um endereço exato, o que pode dificultar o recebimento de entregas. Ou, quem tem um endereço prefere aceitar entregas em locais mais específicos, como uma entrada dos fundos ou uma doca de carregamento.

Os Plus Codes são como endereços de pessoas ou lugares que não têm um endereço real. Em vez de endereços com nomes e números, os Plus Codes são baseados em coordenadas de latitude/longitude e aparecem como números e letras.

O Google desenvolveu o Plus Codes para oferecer o benefício dos endereços a todas as pessoas. Um Plus Code é uma referência de local codificada, derivada das coordenadas de latitude/longitude, que representa uma área: 1/8.000 de um grau por 1/8.000 de grau (cerca de 14 x 14 m no equador) ou menor. Você pode usar Plus Codes para substituir endereços em lugares onde eles não existem, onde os edifícios 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 composto:

  • Um código global é composto por um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres.

    Por exemplo, para o endereço "1600 Amphitheatre Parkway, Mountain View, CA", o código global é "849V" e o código local é "CWC8+R9". Use todo o Plus Code de 10 caracteres para especificar o valor do local como "849VCWC8+R9".

  • Um código composto é formado por um código local com, pelo menos, seis caracteres e um local explícito.

    Por exemplo, o endereço "450 Serra Mall, Stanford, CA 94305, USA" tem o código local "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 o trajeto 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, como Place Autocomplete, Place Details, API Directions e API Geocoding. Por exemplo, é possível usar a API Geocoding para geocodificar inversamente um local especificado por coordenadas de latitude/longitude e determinar o Plus Code dele.