Especificar locais para um trajeto

Para calcular uma rota, você precisa especificar pelo menos os locais de origem e destino dela. Você define esses locais como pontos de passagem na rota.

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

Especificar locais para um trajeto

Para representar um local, crie um objeto de 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 pontos de passagem de 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 aumentar a eficiência e a 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 vantagens de geocodificação para roteamento, 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 delas, 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 que seja convertida em coordenadas de latitude/longitude. 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 ponto de passagem. Como as coordenadas de latitude e longitude são ajustadas às vias, você pode achar que um ID de lugar oferece resultados melhores em algumas circunstâncias.

Extraia IDs de lugares da API Geocoding e da API Places (incluindo o 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 a localização em um waypoint, especifique o Local (REST) ou o Local(gRPC) usando as coordenadas de latitude/longitude.

Por exemplo, especifique um waypoint para os trajetos 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ê passa uma string de endereço como o local de um ponto de passagem, a API Routes gera o código geográfico da string internamente para convertê-la em coordenadas de latitude e longitude.

Por exemplo, para calcular uma rota, especifique um ponto de passagem 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 remover a ambiguidade de 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 erradas 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 erradas. Por exemplo, você faz uma solicitação especificando "Toledo" como a origem e "Madri" como o destino de uma rota 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á 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 de região como um valor de ccTLD ("domínio de nível superior") 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 seu 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" para "Madrid" que inclui 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 um Plus Code

Muitas pessoas não têm um endereço preciso, o que pode dificultar a entrega de produtos. Ou as pessoas com um endereço podem preferir aceitar entregas em locais mais específicos, como uma entrada de serviço ou um pátio de carga.

Plus Codes são como endereços para pessoas ou lugares que não têm um endereço real. Em vez de endereços com nomes de ruas 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 a tudo. Um Plus Code é uma referência de local codificada, derivada de coordenadas de latitude/longitude, que representa uma área: 1/8.000 de grau por 1/8.000 de grau (cerca de 14 m x 14 m no equador) ou menos. Você pode usar os Plus Codes como substitutos de endereços de rua em lugares em que eles não existem ou em que os edifícios não sã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 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 todo o Plus Code com 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 combinado com um local explícito.

    Por exemplo, o endereço "450 Serra Mall, Stanford, CA 94305, USA" 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 do endereço no formato "CRHJ+C3 Stanford, CA 94305, EUA".

    Por exemplo, calcule uma rota especificando um ponto de passagem para a rota origin e destination usando os 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 do Google Maps Platform, incluindo o Place Autocomplete, os detalhes do lugar, a API Directions e a 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 do local.