Créer des routes sélectionnées

Cette page explique comment créer des itinéraires et ajouter des attributs personnalisés à l'aide de l'API Roads Selection dans les sections suivantes :

Créer un routage

Pour créer une route, envoyez une requête POST au point de terminaison create.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

Le corps de la requête doit être un objet JSON qui définit la ressource SelectedRoute. Cet objet spécifie les informations suivantes :

  • Un objet dynamicRoute contenant les informations suivantes :
    • Le origin de l'itinéraire sélectionné.
    • Le destination de l'itinéraire sélectionné.
    • Tous les intermediates, également appelés points de repère, de l'itinéraire.
  • Un selectedRouteId unique. Cette valeur doit comporter entre 4 et 63 caractères et ne doit contenir que des caractères alphanumériques. Si vous ne fournissez pas d'ID, le système génère un ID unique pour l'itinéraire sélectionné.

L'exemple de code suivant montre la structure d'une requête POST au point de terminaison create.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

En cas de réussite, l'API renvoie la ressource SelectedRoute. La réponse inclut selectedRouteId dans le champ name. Vous pouvez utiliser selectedRouteId pour récupérer ou supprimer la ressource SelectedRoute.

L'exemple de code suivant montre la structure d'une réponse create réussie.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

Créer des routes par lot

Pour créer plusieurs itinéraires dans une même requête, utilisez le point de terminaison batchCreate. Ce point de terminaison vous permet de définir jusqu'à 1 000 itinéraires en un seul appel.

Envoyez une requête POST au point de terminaison batchCreate :

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

L'URL utilise la syntaxe de transcodage gRPC.

Le corps de la requête doit être un objet JSON contenant un tableau requests. Chaque objet de ce tableau est un CreateSelectedRouteRequest qui définit une ressource SelectedRoute individuelle.

L'exemple de code suivant montre la structure d'une requête POST au point de terminaison batchCreate :

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

En cas de succès, l'API renvoie une réponse contenant un tableau des ressources SelectedRoute qui ont été créées.

L'exemple de code suivant montre la structure d'une réponse de point de terminaison batchCreate :

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

Créer un itinéraire avec des points de cheminement intermédiaires

Pour créer un itinéraire qui passe par des points spécifiques entre l'origine et la destination, incluez un tableau intermediates dans l'objet dynamicRoute du corps de votre requête. Chaque élément du tableau intermediates est un point de cheminement défini par son latitude et son longitude. Un itinéraire peut comporter jusqu'à 25 points de cheminement.

L'exemple de code suivant montre comment créer un SelectedRoute avec des waypoints intermédiaires :

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Utiliser des attributs de route personnalisés

Pour améliorer la gestion des itinéraires et l'analyse des données dans Insights sur la gestion des routes, l'objet SelectedRoute inclut un champ route_attributes.

Utilisez le champ routeAttributes pour définir vos propres propriétés personnalisées pour chaque itinéraire, où chaque attribut est une paire clé-valeur. Vous pouvez fournir jusqu'à 10 paires clé/valeur personnalisées par itinéraire.

Ces attributs sont utiles pour identifier des itinéraires spécifiques ou pour regrouper des itinéraires en fonction de critères adaptés à vos besoins.

Voici quelques exemples d'attributs de route que vous pouvez utiliser :

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

Suivez les consignes ci-dessous lorsque vous définissez le champ routeAttributes :

  • Les clés ne doivent pas commencer par le préfixe goog.
  • La longueur de chaque clé et de chaque valeur ne doit pas dépasser 100 caractères.

Vous pouvez ensuite utiliser ces routeAttributes personnalisés dans les insights sur la gestion des routes de différentes manières :

  • Filtrer les notifications Pub/Sub : vous pouvez définir des filtres sur vos abonnements Pub/Sub pour ne recevoir des notifications que pour les routes qui correspondent ou non à des clés d'attributs spécifiques et à leurs valeurs correspondantes.
  • Affiner l'analyse BigQuery : dans vos tables BigQuery, vous pouvez utiliser ces attributs pour filtrer des itinéraires spécifiques en fonction de la valeur d'un attribut. Vous pouvez également regrouper les itinéraires par clé d'attribut spécifique pour une analyse des données plus ciblée.

L'exemple de code suivant montre comment créer un SelectedRoute avec des routeAttributes personnalisés.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"