Spécifier des lieux pour un itinéraire

Pour calculer un itinéraire, vous devez spécifier au minimum les emplacements de son point de départ et de sa destination. Vous définissez ces emplacements en tant que points de cheminement sur l'itinéraire.

Outre le point de départ et la destination, vous pouvez spécifier différents types de points de cheminement et comment les gérer pour un itinéraire. Pour en savoir plus et obtenir des exemples, consultez les rubriques suivantes:

Spécifier des emplacements pour un itinéraire

Pour représenter un emplacement, créez un objet Waypoint (REST) ou Waypoint (gRPC). Dans la définition d'un point de cheminement, vous pouvez spécifier un emplacement de l'une des manières suivantes:

Vous pouvez spécifier les emplacements de tous les points de cheminement d'une requête de la même manière ou les combiner. Par exemple, vous pouvez utiliser des coordonnées de latitude/longitude pour le point de cheminement de départ et un ID de lieu pour le point de cheminement de destination.

Pour plus d'efficacité et de précision, utilisez des ID de lieu plutôt que des coordonnées de latitude/longitude ou des chaînes d'adresse. Les ID de lieu sont explicites de manière unique et offrent des avantages de geocoding pour le routage, tels que des points d'accès et des variables de trafic. Elles permettent d'éviter les situations suivantes qui peuvent résulter d'autres méthodes de spécification d'un emplacement:

  • L'utilisation de coordonnées de latitude/longitude peut entraîner l'alignement du lieu sur la route la plus proche de ces coordonnées (ce qui ne correspond pas toujours à un point d'accès à la propriété, ou même à une route qui mène rapidement ou en toute sécurité à la destination).
  • Les chaînes d'adresse doivent d'abord être géocodées par l'API Routes pour les convertir en coordonnées de latitude/longitude avant de pouvoir calculer un itinéraire. Cette conversion peut avoir un impact sur vos performances.

Spécifier un lieu en tant qu'ID de lieu

Vous pouvez utiliser un ID de lieu pour spécifier l'emplacement d'un point de cheminement. Étant donné que les coordonnées de latitude et de longitude sont alignées sur les routes, vous constaterez peut-être qu'un ID de lieu offre de meilleurs résultats dans certaines circonstances.

Récupérez les ID de lieu à partir de l'API Geocoding et de l'API Places (y compris Place Autocomplete). Pour en savoir plus sur les ID de lieu, consultez la présentation des ID de lieu.

L'exemple suivant utilise la propriété placeId afin de transmettre un ID de lieu pour origin et destination:

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

Spécifiez un lieu en tant que coordonnées de latitude et de longitude.

Pour définir une position dans un point de cheminement, spécifiez la propriété Location (REST) ou Location(gRPC) en utilisant des coordonnées de latitude/longitude.

Par exemple, spécifiez un point de cheminement pour l'itinéraire origin et destination à l'aide des coordonnées latitude et longitude:

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

Spécifier un lieu en tant que chaîne d'adresse

Les chaînes d'adresse sont des adresses littérales représentées par une chaîne (par exemple, "1600 Amphitheatre Parkway, Mountain View, CA"). Le geocoding est le processus de conversion d'une chaîne d'adresse en coordonnées de latitude et de longitude (par exemple, latitude 37.423021 et longitude -122.083739).

Lorsque vous transmettez une chaîne d'adresse en tant qu'emplacement d'un point de cheminement, l'API Routes géocode la chaîne en interne pour la convertir en coordonnées de latitude et de longitude.

Par exemple, pour calculer un itinéraire, vous devez spécifier un point de cheminement pour l'itinéraire origin et destination à l'aide de chaînes d'adresse:

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

Dans cet exemple, l'API Routes géocode les deux adresses pour les convertir en coordonnées de latitude et de longitude.

Si la valeur de l'adresse est ambiguë, l'API Routes peut appeler une recherche pour distinguer les adresses similaires. Par exemple, "1re rue" peut être une valeur complète ou partielle pour "1re rue NE" ou "1re rue SE". Ce résultat peut être différent de celui renvoyé par l'API Geocoding. Vous pouvez éviter les erreurs d'interprétation possibles en utilisant des ID de lieu.

Définir la région de l'adresse

Si vous transmettez une chaîne d'adresse incomplète pour l'emplacement d'un point de cheminement, l'API peut utiliser des coordonnées de latitude/longitude géocodées incorrectes. Par exemple, vous exécutez une requête spécifiant "Tolède" comme point de départ et "Madrid" comme destination d'un itinéraire en voiture:

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

Dans cet exemple, "Toledo" est interprété comme une ville de l'État de l'Ohio aux États-Unis, et non en Espagne. Par conséquent, la requête renvoie un tableau vide, ce qui signifie qu'aucune route n'existe:

{
  []
}

Vous pouvez configurer l'API pour qu'elle renvoie des résultats pondérés en fonction d'une région particulière en incluant le paramètre regionCode. Ce paramètre spécifie le code régional sous la forme d'une valeur ccTLD ("domaine de premier niveau") à deux caractères. La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb" (techniquement pour l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord").

Une requête d'itinéraire entre "Toledo" et "Madrid" incluant le paramètre regionCode renvoie des résultats appropriés, car "Toledo" est interprété comme une ville en Espagne:

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

La réponse contient maintenant l'itinéraire calculé de Tolède (Espagne) à Madrid (Espagne) :

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

Spécifier un lieu en tant que Plus Code

Beaucoup de personnes n'ont pas d'adresse précise, ce qui peut compliquer la réception des livraisons. Les personnes disposant d'une adresse peuvent également préférer accepter les livraisons à des emplacements plus spécifiques, comme une entrée secondaire ou une station de chargement.

Les Plus Codes sont comme les adresses postales de personnes ou de lieux qui n'ont pas d'adresse réelle. Au lieu d'adresses avec des noms et des numéros de rue, les Plus Codes sont basés sur des coordonnées de latitude/longitude et s'affichent sous forme de chiffres et de lettres.

Google a développé des Plus Codes pour que tout le monde puisse profiter des adresses. Un Plus Code est une référence de lieu encodée, dérivée de coordonnées de latitude/longitude, qui représente une zone: 1/8 000e de degré par 1/8 000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Vous pouvez utiliser les Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas, ou où les bâtiments ne sont pas numérotés ni nommés.

Les Plus Codes doivent être formatés en tant que code global ou composé:

  • Un code global est composé d'un indicatif régional à quatre caractères et d'un code local d'au moins six caractères.

    Par exemple, pour l'adresse "1600 Amphitheatre Parkway, Mountain View, CA", le code global est "849V" et le code local est "CWC8+R9". Vous utilisez ensuite l'intégralité du Plus Code à 10 caractères pour spécifier la valeur de l'emplacement comme "849VCWC8+R9".

  • Un code composé est composé d'un code local de six caractères ou plus associé à un emplacement explicite.

    Par exemple, le code local de l'adresse "450 Serra Mall, Stanford, CA 94305, États-Unis" est "CRHJ+C3". Pour une adresse composée, combinez le code local avec la ville, l'État, le code postal et la partie pays de l'adresse au format "CRHJ+C3 Stanford, CA 94305, États-Unis".

    Par exemple, calculez un itinéraire en spécifiant un point de cheminement pour l'itinéraire origin et destination à l'aide des Plus Codes:

    {
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}

Les Plus Codes sont compatibles avec les API Google Maps Platform, y compris Place Autocomplete, Place Details, l'API Directions et l'API Geocoding. Par exemple, vous pouvez utiliser l'API Geocoding pour inverser le geocoding d'un lieu spécifié par des coordonnées de latitude/longitude afin de déterminer son Plus Code.