Tworzenie wybranych tras

Z tej strony dowiesz się, jak tworzyć trasy i dodawać atrybuty niestandardowe za pomocą interfejsu Roads Selection API:

Tworzenie trasy

Aby utworzyć trasę, wyślij żądanie POST do punktu końcowego create.

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

Treść żądania musi być obiektem JSON, który definiuje zasób SelectedRoute. Ten obiekt określa te informacje:

  • Obiekt dynamicRoute z tymi informacjami:
  • Unikalny selectedRouteId. Ta wartość musi mieć od 4 do 63 znaków i zawierać tylko znaki alfanumeryczne. Jeśli nie podasz identyfikatora, system wygeneruje unikalny identyfikator wybranej trasy.

Poniższy przykładowy kod pokazuje strukturę żądania POST do punktu końcowego 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"

W przypadku powodzenia interfejs API zwraca zasób SelectedRoute. Odpowiedź zawiera selectedRouteId w polu name. Za pomocą tego selectedRouteId możesz pobrać lub usunąć zasób SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę odpowiedzi create punktu końcowego.

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

Tworzenie tras zbiorczo

Aby utworzyć wiele tras w jednym żądaniu, użyj batchCreate punktu końcowego. Ten punkt końcowy umożliwia zdefiniowanie maksymalnie 1000 tras w jednym wywołaniu.

Wyślij żądanie POST do punktu końcowego batchCreate:

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

Adres URL używa składni transkodowania gRPC.

Treść żądania musi być obiektem JSON zawierającym tablicę requests. Każdy obiekt w tej tablicy to CreateSelectedRouteRequest, który definiuje pojedynczy zasób SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę żądania POST do batchCreate punktu końcowego:

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"

W przypadku powodzenia interfejs API zwraca odpowiedź zawierającą tablicę utworzonych zasobów SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę odpowiedzi punktu końcowego 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"
    }
  ]
}

Tworzenie trasy z punktami pośrednimi

Aby utworzyć trasę, która przebiega przez określone punkty między miejscem początkowym a docelowym, dodaj intermediates tablicę w dynamicRoute obiekcie w treści żądania. Każdy element w tablicy intermediates to punkt pośredni zdefiniowany przez jego latitude i longitude. Trasa może mieć maksymalnie 25 punktów pośrednich.

Poniższy przykładowy kod pokazuje, jak utworzyć SelectedRoute z punktami pośrednimi:

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"

Używanie niestandardowych atrybutów trasy

Aby ulepszyć zarządzanie trasami i analizę danych w Statystykach dla Zarządców Dróg, obiekt SelectedRoute zawiera pole route_attributes.

Użyj pola routeAttributes, aby zdefiniować własne właściwości niestandardowe dla poszczególnych tras. Każdy atrybut jest parą klucz-wartość. Możesz podać maksymalnie 10 niestandardowych par klucz-wartość na trasę.

Te atrybuty są przydatne do identyfikowania konkretnych tras lub grupowania tras na podstawie kryteriów istotnych dla Twoich potrzeb.

Oto kilka przykładów atrybutów trasy, których możesz użyć:

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

Podczas definiowania pola routeAttributes postępuj zgodnie z tymi wytycznymi:

  • Klucze nie mogą zaczynać się od prefiksu goog.
  • Długość każdego klucza i każdej wartości nie może przekraczać 100 znaków.

Możesz używać tych niestandardowych routeAttributes w Statystykach dla Zarządców Dróg na te sposoby:

  • Filtrowanie powiadomień Pub/Sub: możesz ustawić filtry w subskrypcjach Pub/Sub, aby otrzymywać aktualizacje tylko w przypadku tras, które pasują do określonych kluczy atrybutów i ich odpowiednich wartości lub nie pasują do nich.
  • Ulepszanie analizy BigQuery: w tabelach BigQuery możesz używać tych atrybutów do filtrowania określonych tras na podstawie wartości atrybutu. Możesz też grupować trasy według określonego klucza atrybutu, aby uzyskać bardziej szczegółową analizę danych.

Poniższy przykładowy kod pokazuje, jak utworzyć SelectedRoute z niestandardowymi routeAttributes.

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"