Spécifier des lieux pour un itinéraire

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

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 l'orientation du véhicule et le côté de la route
• Spécifier des points de cheminement intermédiaires
• Définir un arrêt sur un itinéraire
• Définir un point par lequel un itinéraire doit passer
• Optimiser l'ordre des arrêts sur votre itinéraire

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 du point de cheminement, vous pouvez spécifier un emplacement de l'une des manières suivantes:

• ID d'emplacement (recommandé)
• Coordonnées de latitude/longitude
• Chaîne d'adresse ("Chicago, IL" ou "Darwin, NT, Australie")
• Code Plus

Vous pouvez spécifier les emplacements de tous les points de cheminement d'une requête de la même manière ou les mélanger. 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 particulièrement explicites et offrent des avantages de géocodage pour l'itinéraire, 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'ancrage de l'emplacement sur la route la plus proche de ces coordonnées, qui ne correspond pas nécessairement à un point d'accès à la propriété, ni même à une route qui mène rapidement ou de manière sécurisée à la destination.
• Les chaînes d'adresses 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 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.

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

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

Spécifier un emplacement en indiquant ses coordonnées de latitude et de longitude

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

Par exemple, spécifiez un point de cheminement pour les itinéraires 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
      }
    }
  },
...
}

Remarque:Les points spécifiés par des coordonnées de latitude/longitude sont alignés sur les routes et peuvent ne pas fournir la précision dont votre application a besoin. Utilisez des coordonnées de latitude/longitude lorsque vous êtes sûr que les valeurs spécifient réellement les points dont votre application a besoin pour l'itinéraire, sans tenir compte des points d'accès possibles ni des informations de géocodage supplémentaires.

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

Les chaînes d'adresses 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 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.

Remarque:Les coordonnées de latitude et de longitude peuvent être différentes de celles renvoyées par l'API Geocoding. Par exemple, l'API Routes peut renvoyer les coordonnées d'une entrée de bâtiment plutôt que de son centre.

Par exemple, pour calculer un itinéraire, vous spécifiez un point de cheminement pour les itinéraires origin et destination à l'aide de chaînes d'adresses:

{
  "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 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 les interprétations possibles à l'aide d'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 les mauvaises coordonnées de latitude/longitude géocodées. Par exemple, vous envoyez une requête en spécifiant "Tolède" 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 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 de "Tolède" à "Madrid" incluant le paramètre regionCode renvoie des résultats appropriés, car "Tolède" 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 sous forme de plus code

De nombreuses personnes n'ont pas d'adresse précise, ce qui peut les empêcher de recevoir des livraisons. Les personnes disposant d'une adresse peuvent également préférer accepter les livraisons à 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 postales qui contiennent des noms et des numéros de rue, les Plus Codes sont basés sur la latitude et la longitude, et présentés sous forme de chiffres 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/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, où les bâtiments ne sont pas numérotés ni nommés.

Les Plus Codes doivent être au format code global ou code composé:

• Un code global se compose d'un indicatif de zone à quatre caractères et d'un code local à 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 code Plus à 10 caractères pour spécifier la valeur de l'emplacement sous la forme "849VCWC8+R9".

• Un code composé se compose 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 sous la forme "CRHJ+C3 Stanford, CA 94305, USA".

  Par exemple, calculez un itinéraire en spécifiant un point de cheminement pour les itinéraires 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 Place Autocomplete, Place Details, API Directions et API Geocoding. Par exemple, vous pouvez utiliser l'API Geocoding pour effectuer un géocodage inverse d'un lieu spécifié par des coordonnées de latitude/longitude afin de déterminer son code Plus.