Crea route selezionati

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

Crea una route

Per creare una route, 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 i caratteri validi sono a-z, A-Z, 0-9, - o _. Se non viene fornito un ID, il sistema genera un ID univoco per la route selezionata.

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

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 corretta dell'endpoint create.

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

Crea un percorso con tappe intermedie

Per creare un percorso che passa attraverso 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 tappe.

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

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"

Utilizza gli attributi delle route personalizzate

Per migliorare la gestione delle route e l'analisi dei dati in Insight di gestione stradale, l'oggetto SelectedRoute include un campo routeAttributes.

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

Questi attributi sono utili per identificare route specifiche o per raggrupparle in base a criteri pertinenti alle tue esigenze.

Di seguito sono riportati alcuni esempi di attributi di route che puoi 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 Insight di gestione stradale nei seguenti modi:

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

Il seguente esempio di codice mostra come creare un SelectedRoute con routeAttributes personalizzati.

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"

Crea route in batch

Per creare più percorsi in un'unica richiesta, utilizza l'endpoint batchCreate. Questo endpoint ti consente di definire fino a 1000 route in una singola 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": [
        {
          "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"

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