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 une route

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 :
    • origin de l'itinéraire sélectionné.
    • destination de l'itinéraire sélectionné.
    • Tous les intermediates, également appelés points de cheminement, de l'itinéraire.
  • Un selectedRouteId unique. Cette valeur doit contenir entre 4 et 63 caractères, et les caractères valides sont a-z, A-Z, 0-9, - ou _. Si aucun identifiant n'est fourni, le système génère un identifiant unique pour la route sélectionnée.

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

curl -X POST -d '
    {
      "dynamicRoute": {
        "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 cet selectedRouteId pour récupérer ou supprimer la ressource SelectedRoute.

L'exemple de code suivant montre la structure d'une réponse de point de terminaison 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 un itinéraire avec des points de cheminement intermédiaires

Pour créer un itinéraire qui passe par des points spécifiques entre le point de départ 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 ses coordonnées latitude et longitude. Un itinéraire peut comporter jusqu'à 25 points de cheminement.

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

curl -X POST -d '
    {
      "dynamicRoute": {
        "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 de vos itinéraires et l'analyse de données dans les insights de gestion des routes, l'objet SelectedRoute inclut un champ routeAttributes.

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

Ces attributs sont utiles pour identifier des routes spécifiques ou pour regrouper des routes en fonction de critères pertinents pour vos besoins.

Voici quelques exemples d'attributs d'itinéraire que vous pouvez utiliser :

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

Suivez les consignes suivantes 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 de 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 mises à jour que pour les routes qui correspondent ou non à des clés d'attribut spécifiques et à leurs valeurs correspondantes.
  • Affiner l'analyse BigQuery : dans vos tables BigQuery, vous pouvez utiliser ces attributs pour filtrer des routes spécifiques en fonction de la valeur d'un attribut. Vous pouvez également regrouper les routes 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 un routeAttributes personnalisé.

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "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"

Créer des routes par lot

Pour créer plusieurs routes 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 envoyée au point de terminaison batchCreate :

curl -X POST -d '
    {
      "requests": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "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 réussite, l'API renvoie une réponse contenant un tableau des ressources SelectedRoute 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"
    }
  ]
}