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 określa te informacje:

  • Obiekt dynamicRoute zawierający te informacje:
  • 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ę powiedzie, interfejs API zwróci zasób SelectedRoute. Odpowiedź zawiera selectedRouteId w polu name. Możesz użyć tego 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 określony przez 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 odpowiadających Twoim potrzebom.

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.

Kolejny przykładowy kod pokazuje, jak utworzyć SelectedRoute z niestandardowym 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"
    }
  ]
}