Crea route selezionati

Questa pagina descrive come creare itinerari e aggiungere attributi personalizzati utilizzando l'API Roads Selection nelle seguenti sezioni:

Crea una route

Per creare un percorso, invia una richiesta POST all'endpoint create.

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

Il corpo della richiesta deve essere un oggetto JSON che definisce la risorsa SelectedRoute. Questo oggetto specifica le seguenti informazioni:

  • Un oggetto dynamicRoute con le seguenti informazioni:
  • Un selectedRouteId univoco. Questo valore deve contenere da 4 a 63 caratteri e utilizzare solo caratteri alfanumerici. Se non fornisci un ID, il sistema ne genera uno univoco per l'itinerario selezionato.

Il seguente esempio di codice mostra la struttura di una richiesta POST all'endpoint 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"

In caso di esito positivo, l'API restituisce la risorsa SelectedRoute. La risposta include selectedRouteId nel campo name. Puoi utilizzare questo selectedRouteId per recuperare o eliminare la risorsa SelectedRoute.

Il seguente esempio di codice mostra la struttura di una risposta dell'endpoint create corretta.

{
  "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"
}

Creare route in batch

Per creare più itinerari in un'unica richiesta, utilizza l'endpoint batchCreate. Questo endpoint ti consente di definire fino a 1000 percorsi in una sola chiamata.

Invia una richiesta POST all'endpoint batchCreate:

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

L'URL utilizza la sintassi di transcodifica gRPC.

Il corpo della richiesta deve essere un oggetto JSON contenente un array requests. Ogni oggetto all'interno di questo array è un CreateSelectedRouteRequest che definisce una singola risorsa SelectedRoute.

Il seguente esempio di codice mostra la struttura di una richiesta POST all'endpoint 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"

In caso di esito positivo, l'API restituisce una risposta contenente un array delle risorse SelectedRoute create.

Il seguente esempio di codice mostra la struttura di una risposta dell'endpoint 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"
    }
  ]
}

Creare un percorso con tappe intermedie

Per creare un percorso che passi per punti specifici tra l'origine e la destinazione, includi un array intermediates all'interno dell'oggetto dynamicRoute nel corpo della richiesta. Ogni elemento dell'array intermediates è un waypoint definito da latitude e longitude. Un percorso può avere fino a 25 waypoint.

Il seguente esempio di codice mostra come creare un SelectedRoute con waypoint intermedi:

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"

Utilizzare gli attributi delle route personalizzate

Per migliorare la gestione dei percorsi e l'analisi dei dati in Roads Management Insights, l'oggetto SelectedRoute include un campo route_attributes.

Utilizza il campo routeAttributes per definire le tue proprietà personalizzate per singole route, dove ogni attributo è una coppia chiave-valore. Puoi fornire fino a 10 coppie chiave-valore personalizzate per percorso.

Questi attributi sono utili per identificare percorsi specifici o per raggruppare i percorsi in base a criteri pertinenti alle tue esigenze.

Di seguito sono riportati alcuni esempi di attributi dell'itinerario che potresti utilizzare:

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

Segui le linee guida riportate di seguito quando definisci il campo routeAttributes:

  • Le chiavi non devono iniziare con il prefisso goog.
  • La lunghezza di ogni chiave e di ogni valore non deve superare i 100 caratteri.

Puoi quindi utilizzare questi routeAttributes personalizzati in Roads Management Insights nei seguenti modi:

  • Filtra le notifiche Pub/Sub:puoi impostare filtri sulle tue sottoscrizioni Pub/Sub per ricevere aggiornamenti solo per i percorsi che corrispondono o non corrispondono a chiavi di attributo specifiche e ai relativi valori.
  • Perfeziona l'analisi BigQuery:nelle tabelle BigQuery puoi utilizzare questi attributi per filtrare itinerari specifici in base al valore di un attributo. Puoi anche raggruppare le rotte in base a una chiave di attributo specifica per un'analisi dei dati più mirata.

L'esempio di codice successivo mostra come creare un SelectedRoute con routeAttributes personalizzati.

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"