選択したルートを作成する

このページでは、道路選択 API を使用してルートを作成し、カスタム属性を追加する方法について、以下のセクションで説明します。

ルートを作成する: create エンドポイントを使用して単一のルートを定義します。
ルートをバッチで作成する: batchCreate エンドポイントを使用して、1 つのリクエストで複数のルートを定義します。
中間経由地を含むルートを作成する: 最大 25 個の中間経由地を含むルートを定義します。
カスタムルート属性を利用する: 組織の目的で、ルートに最大 10 個のカスタム Key-Value ペアを追加します。

ルートの作成

ルートを作成するには、POST リクエストを create エンドポイントに送信します。

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

リクエストの本文 は、SelectedRoute リソースを定義する JSON オブジェクトにする必要があります。このオブジェクトは、次の情報を指定します。

次の情報を含む dynamicRoute オブジェクト。
- 選択したルートの origin。
- 選択したルートの destination。
- ルートの intermediates（経由地とも呼ばれます）。
一意の selectedRouteId。この値は 4 ～ 63 文字にする必要があり、英数字のみを使用 してください。ID を指定しない場合、選択したルートの一意の ID がシステムによって生成されます。

selectedRouteId

次のコードサンプルは、POST リクエストの 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"

成功すると、API は SelectedRoute リソースを返します。レスポンスには、selectedRouteId が name フィールドに含まれます。この selectedRouteId を使用して、SelectedRoute リソースを取得または削除できます。

次のコードサンプルは、成功した 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"
}

ルートをバッチで作成する

1 つのリクエストで複数のルートを作成するには、 batchCreate エンドポイントを使用します。このエンドポイントを使用すると、1 回の呼び出しで最大 1,000 個のルートを定義できます。

POST リクエストを batchCreate エンドポイントに送信します。

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

この URL は gRPC Transcoding 構文を使用します。

リクエストの本文 は、requests 配列を含む JSON オブジェクトにする必要があります。この配列内の各オブジェクトは、個々の SelectedRoute リソースを定義する CreateSelectedRouteRequest です。

次のコードサンプルは、POST リクエストを batchCreate エンドポイントへの構造を示しています。

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"

成功すると、API は作成された SelectedRoute リソースの配列を含むレスポンスを返します。

次のコードサンプルは、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"
    }
  ]
}

中間経由地を含むルートを作成する

出発地と目的地の間の特定の地点を通過するルートを作成するには、リクエストの本文の dynamicRouteオブジェクトにintermediates配列を含めます。intermediates 配列の各要素は、latitude と longitude で定義されるウェイポイントです。ルートには最大 25 個のウェイポイントを設定できます。

次のコードサンプルは、中間経由地を含む SelectedRoute with を作成する方法を示しています。

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"

カスタムルート属性を利用する

Roads Management Insights でルート管理とデータ分析を強化するために、 SelectedRoute オブジェクトには route_attributes フィールドが含まれています。

routeAttributes フィールドを使用して、個々のルートのカスタムプロパティを定義します。各属性は Key-Value ペアです。ルートごとに最大 10 個のカスタム Key-Value ペアを指定できます。

これらの属性は、特定のルートを識別したり、ニーズに関連する条件に基づいてルートをグループ化したりするのに役立ちます。

使用できるルート属性の例を次に示します。

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

routeAttributes フィールドを定義する場合は、次のガイドラインに従ってください。

キーは接頭辞 goog で始めることはできません。
各キーと各値の長さは 100 文字を超えないようにしてください。

これらのカスタム routeAttributes は、Roads Management Insights で次の方法で使用できます。

Pub/Sub 通知をフィルタリングする: Pub/Sub サブスクリプションにフィルタを設定して、特定の属性キーとその対応する値に一致するルートまたは一致しないルートの更新のみを受信できます。
BigQuery 分析を絞り込む: BigQuery テーブルで、これらの属性を使用して、属性の値に基づいて特定のルートをフィルタできます。特定の属性キーでルートをグループ化して、より的を絞ったデータ分析を行うこともできます。

次のコードサンプルは、カスタム routeAttributesを使用してSelectedRouteを作成する方法を示しています。

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"