Especificar locais para um trajeto

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

Para calcular um trajeto, é preciso especificar pelo menos os locais de origem e destino. Você define esses locais como pontos de referência na rota.

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

Especificar locais para uma rota

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

Você pode especificar locais para todos os pontos de referência em uma solicitação da mesma forma ou misturá-los. Por exemplo, você pode usar coordenadas de latitude/longitude para o ponto de referência de origem e um ID de lugar para o ponto de referência de destino.

Para eficiência e precisão, use IDs de lugar em vez de coordenadas de latitude/longitude ou strings de endereço. Os IDs de lugar são explicitamente exclusivos e oferecem benefícios de geocodificação para rotas, como pontos de acesso e variáveis de tráfego. Elas 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 fazer com que o local seja ajustado à via mais próxima dessas coordenadas, que pode não ser um ponto de acesso à propriedade ou até mesmo uma via 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 de calcular um trajeto. Essa conversão pode afetar a performance.

Especificar um local como um ID de lugar

Você pode usar um ID de lugar para especificar a localização de um ponto de parada. Como as coordenadas de latitude e longitude são ajustadas às vias, talvez um ID de lugar ofereça resultados melhores em algumas circunstâncias.

Recupere IDs de lugares da API Geocoding e da API Places (incluindo o Place Autocomplete). Para mais informações sobre IDs de lugar, consulte a Visão geral do ID 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 o Location (REST) ou Location(gRPC) usando coordenadas de latitude/longitude.

Por exemplo, especifique um ponto de referência para a rota 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 o local de um ponto de parada, a API Routes faz a geocodificação interna da string para convertê-la em coordenadas de latitude e longitude.

Por exemplo, para calcular uma rota, especifique um ponto de referência 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 de endereços semelhantes. Por exemplo, "Rua 1" pode ser um valor completo ou parcial para "Rua 1 NE" ou "Rua 1 SE". Esse resultado pode ser diferente do retornado pela API Geocoding. Você pode evitar possíveis interpretações incorretas usando IDs de lugares.

Defina a região do endereço

Se você transmitir uma string de endereço incompleta como o local de um ponto de parada, a API poderá usar as coordenadas de latitude/longitude geocodificadas erradas. 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" é interpretada 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á rotas:

{
  []
}

É 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 valor de dois caracteres ccTLD ("domínio de nível superior"). A maioria dos códigos de 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 rotas de "Toledo" para "Madri" que inclui o parâmetro regionCode retorna resultados adequados porque "Toledo" é interpretada como uma cidade na Espanha:

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

A resposta agora contém a rota calculada de Toledo, Espanha, para Madri, Espanha:

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

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 dos fundos ou um cais de carga.

Os Plus Codes são como endereços para pessoas ou lugares que não têm um endereço físico. Em vez de nomes de rua, os Plus Codes têm como base as coordenadas de latitude/longitude e são exibidos como números e letras.

O Google desenvolveu os Plus Codes para que todos e tudo tenham os benefícios de um endereço. 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. Você pode usar os Plus Codes em vez de endereços nos lugares em que não existem, ou seja, 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 local é "CWC8+R9". Em seguida, use o código 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 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 o país no formato "CRHJ+C3 Stanford, CA 94305, EUA".

    Por exemplo, calcule uma rota especificando um ponto de parada 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, você pode usar a API Geocoding para fazer a geocodificação inversa de um local especificado por coordenadas de latitude/longitude e determinar o Plus Code dele.