Tworzenie wybranych tras

Na tej stronie dowiesz się, jak tworzyć trasy i dodawać atrybuty niestandardowe za pomocą interfejsu Roads Selection API. Opisujemy to w tych sekcjach:

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 identyfikator selectedRouteId, Ta wartość powinna zawierać od 4 do 63 znaków, a prawidłowe znaki to a-z, A-Z, 0-9, - lub _. 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 '
    {
      "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, która informuje 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 przechodzi przez określone punkty między miejscem początkowym a docelowym, w obiekcie dynamicRoute w treści żądania umieść tablicę intermediates. Każdy element w tablicy intermediates to punkt pośredni zdefiniowany przez latitude i longitude. Trasa może zawierać maksymalnie 25 punktów pośrednich.

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

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"

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 routeAttributes.

Użyj pola routeAttributes, aby zdefiniować własne właściwości niestandardowe poszczególnych tras, gdzie 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 prefiksu goog.
  • Długość każdego klucza i każdej wartości nie może przekraczać 100 znaków.

Następnie możesz używać tych niestandardowych routeAttributes w Statystykach dla Zarządców Dróg w następujący sposób:

  • Filtrowanie powiadomień Pub/Sub: możesz ustawić filtry w subskrypcjach Pub/Sub, aby otrzymywać aktualizacje tylko dotyczące tras, które pasują lub nie pasują do określonych kluczy atrybutów i odpowiadających im wartości.
  • 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 przeprowadzić 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"

Tworzenie tras zbiorczo

Aby utworzyć wiele tras w jednym żądaniu, użyj punktu końcowego batchCreate. Ten punkt końcowy umożliwia zdefiniowanie do 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 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ę powiedzie, 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"
    }
  ]
}