Tworzenie wybranych tras

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

Utworzenie 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 zawiera 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 dla wybranej trasy.

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

Jeśli operacja się uda, interfejs API zwróci zasób SelectedRoute. Odpowiedź zawiera selectedRouteId w polu name. Możesz użyć tego identyfikatora selectedRouteId, aby pobrać lub usunąć zasób SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę odpowiedzi punktu końcowego create informującej o powodzeniu.

{
  "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 trasy z punktami pośrednimi

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

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

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"

Korzystanie z atrybutów trasy niestandardowej

Aby ulepszyć zarządzanie trasami i analizowanie danych w usłudze Statystyki dla Zarządców Dróg, obiekt SelectedRoute zawiera pole routeAttributes.

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 25 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 przedrostka 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 wartości lub do nich nie pasują.
  • Udoskonalanie analizy BigQuery: w tabelach BigQuery możesz używać tych atrybutów do filtrowania konkretnych tras na podstawie wartości atrybutu. Możesz też grupować trasy według określonego klucza atrybutu, aby uzyskać bardziej ukierunkowaną analizę danych.

W następnym przykładzie kodu pokazujemy, jak utworzyć element SelectedRoute z niestandardowym elementem routeAttributes.

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"

Zbiorcze tworzenie tras

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

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 punktu końcowego 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"

Jeśli operacja się uda, interfejs API zwróci 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"
    }
  ]
}