Spécifier des lieux pour un itinéraire

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

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

En plus du point de départ et de la destination, vous pouvez spécifier différents types de points de cheminement 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

Vous représentez un emplacement en créant 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 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 uniques et explicites. Ils offrent des avantages de géocodage pour le routage, tels que les points d'accès et les variables de trafic. Ils 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 de la position sur la route la plus proche de ces coordonnées, qui n'est peut-être pas un point d'accès à l'établissement, ni 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 affecter les performances.

Spécifier un emplacement 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 certains cas.

Obtenez des ID de lieu à partir de l'API Geocoding et de l'API Places (nouvelle version) (y compris Autocomplete (nouvelle version)). 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 à l'aide de coordonnées de latitude et de longitude

Pour définir l'emplacement d'un point de cheminement, spécifiez l'emplacement (REST) ou l'emplacement (gRPC) à l'aide de 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 emplacement 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 geocoding 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 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 spécifiez un point de cheminement pour le origin et le destination de l'itinéraire à 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 lancer une recherche pour lever l'ambiguïté entre des adresses similaires. Par exemple, "1st Street" peut être une valeur complète ou une valeur 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 les 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 risque d'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 spécifique 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 demande d'itinéraire de "Toledo" à "Madrid" incluant le paramètre regionCode renvoie des résultats appropriés, car "Toledo" est interprété comme une ville d'Espagne :

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

La réponse contient désormais l'itinéraire calculé entre Tolède (Espagne) et Madrid (Espagne) :

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

Un jeton de point de navigation est une chaîne qui encode un emplacement et un contexte d'itinéraire supplémentaire. Les jetons de point de navigation peuvent fournir un itinéraire précis vers des points d'accès spécifiques à proximité des entrées, des quais de chargement ou des zones de prise en charge désignées. Cela est utile dans des cas comme la livraison de repas ou le covoiturage, où le point de prise en charge ou de dépose peut être ambigu.

Vous pouvez obtenir un jeton de point de navigation en appelant la méthode Destinations de l'API Geocoding.

Pour spécifier un jeton de point de navigation :

  1. Obtenez un navigationPointToken à partir de la méthode SearchDestinations de l'API Geocoding. Pour en savoir plus, consultez la documentation de l'API Geocoding.
  2. Créez un point de cheminement en transmettant le navigationPointToken.

L'exemple suivant utilise la propriété navigation_point_token pour transmettre un jeton de point de navigation pour origin et destination :

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

Spécifier un emplacement sous forme de Plus Code

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

Les Plus Codes sont des adresses postales pour les personnes ou les lieux qui n'ont pas d'adresse physique. Au lieu d'adresses avec des noms de rue et des numéros, 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é les Plus Codes pour que tout le monde et tous les lieux puissent bénéficier d'une adresse. 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 ou les rues ne sont pas nommées.

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 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, soit "849VCWC8+R9".

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

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

    Par exemple, calculez un itinéraire en spécifiant un point de cheminement pour l'itinéraire origin et destination à l'aide de 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 Autocomplete (New), Place Details (New) et l'API Geocoding. Par exemple, vous pouvez utiliser l'API Geocoding pour effectuer un geocoding inversé d'un emplacement spécifié par des coordonnées de latitude/longitude afin de déterminer le Plus Code de l'emplacement.