このページでは、次のセクションで Roads Selection API を使用してルートを作成し、カスタム属性を追加する方法について説明します。
- ルートを作成する:
createエンドポイントを使用して単一のルートを定義します。 - ルートのバッチ作成:
batchCreateエンドポイントを使用して、1 回のリクエストで複数のルートを定義します。 - 中間地点を含むルートを作成する: 最大 25 個の中間地点を含むルートを定義します。
- カスタムルート属性を利用する: 組織の目的で、ルートに最大 10 個のカスタム Key-Value ペアを追加します。
ルートの作成
ルートを作成するには、create エンドポイントに POST リクエストを送信します。
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 を生成します。
次のコードサンプルは、create エンドポイントに対する POST リクエストの構造を示しています。
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 リソースを返します。レスポンスには、name フィールドに selectedRouteId が含まれます。この 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 個のルートを定義できます。
batchCreate エンドポイントに POST リクエストを送信します。
https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate
この URL は gRPC Transcoding 構文を使用します。
リクエストの本文は、requests 配列を含む JSON オブジェクトにする必要があります。この配列内の各オブジェクトは、個々の SelectedRoute リソースを定義する CreateSelectedRouteRequest です。
次のコードサンプルは、batchCreate エンドポイントへの POST リクエストの構造を示しています。
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 を作成する方法を示しています。
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"カスタムルート属性を利用する
道路情報管理の分析情報でルート管理とデータ分析を強化するため、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 は、道路管理インサイトで次のように使用できます。
- 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"