Spécifier des lieux pour un itinéraire

Développeurs de l'Espace économique européen (EEE)

Pour calculer un itinéraire, vous devez au minimum spécifier les points de départ et d'arrivée. Vous définissez ces lieux comme des points de cheminement sur l'itinéraire.

En plus de l'origine et de la destination, vous pouvez spécifier différents types de points de repère et la manière de les gérer pour un itinéraire. Pour en savoir plus et obtenir des exemples, consultez les articles suivants :

Spécifier des lieux pour un itinéraire

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

Vous pouvez spécifier des lieux pour tous les points de cheminement d'une requête de la même manière, ou vous pouvez les mélanger. Par exemple, vous pouvez utiliser des coordonnées de latitude/longitude pour le point de cheminement d'origine 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 uniques et explicites. Ils offrent des avantages en termes de géocodage pour le routage, comme les points d'accès et les variables de trafic. Ils permettent d'éviter les situations suivantes qui peuvent résulter d'autres façons de spécifier un lieu :

  • L'utilisation de coordonnées de latitude/longitude peut entraîner l'ancrage de la position sur la route la plus proche de ces coordonnées. Il peut s'agir d'un point d'accès à la propriété, ou même d'une route qui ne mène pas 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 être converties en coordonnées de latitude et de longitude avant de pouvoir calculer un itinéraire. Cette conversion peut avoir un impact sur les 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 repère. Étant donné que les coordonnées de latitude et de longitude sont associées aux routes, il est possible qu'un ID de lieu offre de meilleurs résultats dans certains cas.

Obtenez des 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 pour transmettre un ID de lieu pour origin et destination :

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

Spécifier un lieu sous forme de coordonnées de latitude et de longitude

Pour définir un emplacement dans un point de cheminement, spécifiez Location (REST) ou Location(gRPC) à l'aide des coordonnées de latitude et de longitude.

Par exemple, spécifiez un point de cheminement pour la route 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 sous forme de 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 géocodage consiste à convertir 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 comme emplacement d'un point de repère, l'API Routes géocode en interne la chaîne pour la convertir en coordonnées de latitude et de longitude.

Par exemple, pour calculer un itinéraire, vous spécifiez un point de repère 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 invoquer une recherche pour la différencier des adresses similaires. Par exemple, "1st Street" peut être une valeur complète ou partielle pour "1st Street NE" ou "1st St SE". Ce résultat peut être différent de celui renvoyé par l'API Geocoding. Vous pouvez éviter d'éventuelles erreurs d'interprétation en utilisant des ID de lieu.

Définir la région de l'adresse

Si vous transmettez une chaîne d'adresse incomplète comme emplacement d'un point de cheminement, l'API peut utiliser des coordonnées de latitude/longitude géocodées incorrectes. Par exemple, vous envoyez une requête spécifiant "Toledo" comme point de départ et "Madrid" comme destination pour 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 faveur d'une région en particulier 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 de TLDcc 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 de "Toledo" à "Madrid" qui inclut 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 désormais l'itinéraire calculé de Tolède (Espagne) à Madrid (Espagne) :

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

Spécifier un lieu en tant que Plus Code

De nombreuses personnes ne disposent pas d'une adresse précise, ce qui peut leur rendre difficile la réception de colis. Les personnes disposant d'une adresse peuvent également préférer recevoir leurs colis à des endroits plus spécifiques, comme une entrée arrière ou un quai de chargement.

Les Plus Codes fonctionnent comme des adresses postales pour les personnes ou les lieux qui n'en ont pas. Contrairement aux adresses avec des noms et des numéros de rue, ils sont basés sur les coordonnées de latitude et de longitude, et sont affichés sous forme de numéros et de lettres.

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

Les Plus Codes doivent être mis en forme comme un code global ou un code composé :

  • Un code global est composé d'un indicatif de zone de quatre caractères et d'un code local de six caractères ou plus.

    Par exemple, pour l'adresse "1600 Amphitheatre Parkway, Mountain View, CA", le code mondial est "849V" et le code local est "CWC8+R9". Vous utilisez ensuite le code Plus complet de 10 caractères pour spécifier la valeur du lieu, par exemple "849VCWC8+R9".

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

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

    Par exemple, calculez un itinéraire en spécifiant un point de repère pour les routes origin et destination à l'aide de Plus Codes :

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

Les codes Plus sont compatibles avec les API Google Maps Platform, y compris Place Autocomplete, Place Details, Directions API (Legacy) et Geocoding API. Par exemple, vous pouvez utiliser l'API Geocoding pour effectuer le géocodage inversé d'un lieu spécifié par des coordonnées de latitude/longitude afin de déterminer son code Plus.