Piomatix LBS API 仕様書 (1.4.0)

Download OpenAPI specification:Download

本文書はPioneerサーバーが提供するWebAPIについて説明するものです。
本文書で定義するWebAPI仕様は OpenAPI format に従って記載しています。

パイオニア株式会社 © Pioneer Corporation. All Rights Reserved.

What's New

1.4.0

2023/08/21

巡回最適化（非同期版）APIの仕様書を追加
巡回最適化（非同期版）結果取得APIの仕様書を追加

1.3.1

2023/08/02

巡回最適化APIのリクエストパラメータに配達時間指定がある場合、service_timeはその範囲以下の時間で設定する必要があることを明記
巡回最適化APIでリクエストされた地点間の距離が全て15m以下の場合エラーになる記述を削除

1.3.0

2023/06/30

巡回最適化APIのリクエストパラメータにnext_to_locationsを追加

1.2.2

2023/06/20

API rate limitsでの"リクエスト数制限"の記述を"リクエスト数制限(初期値)"に変更
PECTrafficProviderKey, PECTrafficProviderUserIDの説明に交通情報を利用しない場合でも文字列として入力必須であることを明記
Vehicle Routing APIの日本語名称を"配送巡回API"から"巡回最適化API"に変更
探索条件の「渋滞考慮」「規制考慮」が交通情報オプションとして利用可能であることを明記
探索条件の「時間規制」は地図データの規制情報を考慮することを明記
地点数の上限値を文中にも明記

Introduction

本WebAPIを利用するにはAPIキーによる認証が必要です。
具体的なAPIキーについては営業窓口までお問い合わせ下さい。
APIキーの利用方法については Authentication を参照下さい。

Definitions

API仕様に関する共通の定義および注意事項について列挙します。

緯度・経度は世界測地系(WGS84)になります。
文字列はUTF-8を前提としています。
時刻の定義では、"時(hour)"の有効範囲は[0,23]になります。

API rate limits

制限は、認証キー（Authorization）毎に、API毎の1秒あたりのリクエスト数に対して適用されます。
制限については下記の説明をご確認ください。
こちらを超えての使用をご希望の場合は、営業窓口までお問い合わせください。

API	リクエスト数制限(初期値)
Routing API	2[req/sec]
Vehicle Routing API	6[req/min]
Route Matrix API	6[req/min]
Traffic Timestamp API	2[req/sec]

Authentication

ApiKeyAuth

認証キー
本WebAPIを利用する場合は提供されたAPIキー(文字列)を以下のHTTPヘッダに含めてリクエストする必要があります。

Security Scheme Type: API Key

Header parameter name: Authorization

PECTrafficProviderKey

交通情報プロバイダー向け認証キー
本WebAPIを利用する場合は提供された交通情報プロバイダー向け認証キー(文字列)を以下のHTTPヘッダに含めてリクエストする必要があります。
※交通情報を利用しない場合でも、入力必須になります。交通情報を利用しない場合でも、具体的なキー(文字列)については営業窓口までお問い合わせください。

Security Scheme Type: API Key

Header parameter name: PEC-Traffic-ProviderKey

PECTrafficProviderUserID

交通情報プロバイダー向けユーザー情報
本WebAPIを利用する場合は提供された交通情報プロバイダー向けユーザー情報(文字列)を以下のHTTPヘッダに含めてリクエストする必要があります。
※交通情報を利用しない場合でも、入力必須になります。その場合、「"none"」など任意の文字列を入力してください。

Security Scheme Type: API Key

Header parameter name: PEC-Traffic-ProviderUserID

Routing API

ルート探索API

ルート探索

指定したユーザの、指定した出発地から立寄地を経由し目的地までのルートを指定した条件で探索し、ルートの形状点列の緯度・経度を取得します。
指定しない探索条件はデフォルト設定です。
立寄地は最大200地点まで指定可能です。
探索条件で探索基準を料金考慮に指定する場合の立寄地は最大5地点まで指定可能です。
区間毎の探索条件は指定できません。指定した探索条件が全ての区間に反映されます。
車両情報を指定した場合、車両規制を考慮したルート探索を行います。
ルート探索に使用する地図地域はリクエストに含まれる地点情報から自動的に判別されます。

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

userID required	string ユーザID
required	object 出発地・立寄地・目的地
	object 時刻指定
	object 探索条件
	object 車種情報
needDrawData	boolean Default: true 描画用情報取得要否(true:取得する, false:取得しない) 地図に描画するための点列情報が必要な場合はtrueを、レスポンスサイズを小さくしたい場合はfalseを指定してください。

Responses

Request samples

Payload

Content type

application/json

{"userID": "testUser",
"pointinfo": {"start": {"lat": 35.93241737968212,
"lon": 139.47167252901303
},
"destination": {"lat": 35.93241737968212,
"lon": 139.47167252901303,
"alongside": false,
"info": [{"key": "address",
"value": "川越市"
}
]
},
"wayPoints": [{"kind": "stopover",
"lat": 35.93241737968212,
"lon": 139.47167252901303,
"alongside": false,
"stayTime": 30
}
]
},
"setTime": {"type": 0,
"time": "2020-01-01T08:30+09:00"
},
"options": {"priority": "recommended",
"useToll": true,
"useHighway": true,
"useFerry": true,
"useSmartIC": true,
"careJam": true,
"careRegulation": true,
"careTimeRegulation": true
},
"vehicleInfo": {"type": 0,
"ratesClass": 0,
"etc": 0,
"width": 178,
"height": 153,
"weight": 1480,
"dangerousLoaded": false
},
"needDrawData": true
}

Response samples

200

Content type

application/json

{"userID": "testUser",
"errorCode": 0,
"errorSectionNo": 0,
"routeNo": 1,
"routeKind": "お勧めルート",
"length": 1000,
"unit": "meter",
"ic": {"entrance": "川越IC",
"exit": "所沢IC"
},
"requireTime": 1000,
"etaInfo": [{"length": 1000,
"requireTime": 1000
}
],
"startTime": "2020-01-01T08:30+09:00",
"toll": 1200,
"unknownToll": false,
"unavoidableInfo": {"toll": false,
"highway": false,
"ferry": false,
"trafficRegulation": false
},
"pathPointNum": 10,
"pathPointList": [{"latitude": 35.93241737968212,
"longitude": 139.47167252901303
}
],
"pathPointInfo": {"roadKind": [{"kind": "general",
"index": 0
}
],
"toll": [{"kind": "free",
"index": 0
}
],
"section": [{"no": 0,
"index": 0
}
]
},
"mapVersion": {"status": "latest",
"use": "hs211r120210619-3",
"new": "hs211r120210619-3"
}
}

Vehicle Routing API

巡回最適化API

配送巡回最適化

指定された地点すべてを巡る最適な巡回順を返却します。
地点数や地点間の距離により、応答までに時間が掛かり過ぎた結果、下記エラーコードが出力されることがあります。
504 Gateway timeout

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

map_region	string Default: "jp" Enum: "uc" "eu" "es" "jp" 地図地域 uc :北米 ※in future release(指定しても500エラーとなる) eu :欧州 ※in future release(指定しても500エラーとなる) es :東南アジア (時刻を指定する際、フィリピンの場合はUTC+8を、それ以外の国の場合はUTC+7を用いる) jp :日本 (時刻を指定する場合はUTC+9を用いる)
user_id required	string ユーザーID (またはデバイスID)
delivery_start_time required	string 配送開始時刻 ISO8601形式 (YYYY-MM-DDThh:mm±hh:mm)
delivery_end_time required	string 配送終了時刻 ISO8601形式 (YYYY-MM-DDThh:mm±hh:mm) ※指定時刻までに配送完了するかどうかの判定に使用。 ※配送拠点に戻ってくるまでの時間も含めて判定。
required	object 配送拠点の位置情報
	object 開始地点(=現在位置) 配送拠点(depot)からの巡回順を算出したい場合は指定しないで下さい。
required	Array of objects [ 1 .. 25 ] items 配送リスト拡張が必要な場合は、営業窓口までお問い合わせください。最大地点数: 25
	object 探索条件
	object アルゴリズム
	Array of objects 休憩時間指定された時間範囲で指定された時間分の休憩を取る ※複数指定可
	object 車両情報
next_to_locations	Array of strings non-empty [ items >= 2 items ] 計算の結果、順番が隣り合ってほしい地点をリスト形式で指定します。 ※複数指定可順番が隣り合ってほしい地点は'unique_id'を使って指定します。使用する'unique_id'は'locations'の中で指定したものと同じものです。リスト内の順番は考慮されず、リスト内で指定された地点が連続して隣り合うような順番を返却します。
need_draw_data	boolean Default: false 描画用情報取得要否(true:取得する, false:取得しない) 地図に描画するための点列情報が必要な場合はtrueを、レスポンスサイズを小さくしたい場合はfalseを指定してください。

Responses

Request samples

Payload

Content type

application/json

{"map_region": "jp",
"user_id": "ID00110263",
"delivery_start_time": "2020-01-01T08:30+09:00",
"delivery_end_time": "2020-01-01T17:30+09:00",
"depot": {"unique_id": "depot",
"address": {"latitude": 35.93241737968212,
"longitude": 139.47167252901303
}
},
"start_location": {"unique_id": "start_location",
"latitude": 35.925045487700125,
"longitude": 139.48586784687123
},
"locations": [{"unique_id": "af6e489e-1a7e-45d3-b587-8311df6ae35d",
"address": {"latitude": 35.9078038201525,
"longitude": 139.4832576402253
},
"scheduled_time": {"range_start": "2020-01-01T08:30+09:00",
"range_end": "2020-01-01T17:30+09:00"
},
"service_time": 5
}
],
"search_condition": {"use_care_traffic": false,
"use_care_regulation": false,
"use_care_time_regulation": true,
"use_alongside": false,
"use_toll": false,
"use_hwy": false,
"use_ferry": false,
"use_smart_ic": false
},
"algorithm": {"travel_matrix_type": "time"
},
"break_time": [{"range_start": "2020-01-01T08:30+09:00",
"range_end": "2020-01-01T17:30+09:00",
"minutes": 45
}
],
"vehicle_info": {"rate_class": 0,
"etc": 0,
"type": 0,
"width": 178,
"height": 153,
"weight": 1480,
"dangerous_loaded": false
},
"next_to_locations": [["af6e489e-1a7e-45d3-b587-8311df6ae35d",
"a0221809-1ec1-48fb-ab2e-67c4395935f8"
]
],
"need_draw_data": false
}

Response samples

200

Content type

application/json

{"skipped": false,
"skipped_location": ["a0221809-1ec1-48fb-ab2e-67c4395935f8"
],
"length": 1000,
"require_time": 1000,
"total_travel_cost": 147,
"break_time": [{"break_start": "2020-01-01T08:30+09:00",
"break_end": "2020-01-01T08:30+09:00"
}
],
"order": [{"unique_id": "af6e489e-1a7e-45d3-b587-8311df6ae35d",
"arrival_time": "2020-01-01T08:30+09:00",
"departure_time": "2020-01-01T08:30+09:00",
"service_time": 5
}
],
"toll": 1200,
"path_point_num": 10,
"path_point_list": [{"latitude": 35.93241737968212,
"longitude": 139.47167252901303
}
],
"path_point_info": {"road_kind": [{"kind": "general",
"index": 0
}
],
"toll": [{"kind": "free",
"index": 0
}
],
"section": [{"no": 0,
"index": 0
}
]
},
"eta_info": [{"length": 1000,
"require_time": 1000
}
]
}

配送巡回最適化（非同期版）

指定された地点すべてを巡る最適な巡回順の計算リクエストを送り、そのリクエストに対応するユニークなタスクIDを返却します。
タスクIDはリクエストに対する計算結果取得の際に使用します。計算結果の保存期間は24時間です。計算時間は最長で約400秒（6分40秒）となります。
504 Gateway timeoutが発生する場合は営業窓口までお問い合わせ下さい。

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

map_region	string Default: "jp" Enum: "uc" "eu" "es" "jp" 地図地域 uc :北米 ※in future release(指定しても500エラーとなる) eu :欧州 ※in future release(指定しても500エラーとなる) es :東南アジア (時刻を指定する際、フィリピンの場合はUTC+8を、それ以外の国の場合はUTC+7を用いる) jp :日本 (時刻を指定する場合はUTC+9を用いる)
user_id required	string ユーザーID (またはデバイスID)
delivery_start_time required	string 配送開始時刻 ISO8601形式 (YYYY-MM-DDThh:mm±hh:mm)
delivery_end_time required	string 配送終了時刻 ISO8601形式 (YYYY-MM-DDThh:mm±hh:mm) ※指定時刻までに配送完了するかどうかの判定に使用。 ※配送拠点に戻ってくるまでの時間も含めて判定。
required	object 配送拠点の位置情報
	object 開始地点(=現在位置) 配送拠点(depot)からの巡回順を算出したい場合は指定しないで下さい。
required	Array of objects [ 1 .. 200 ] items 配送リスト最大地点数: 200
	object 探索条件
	object アルゴリズム
	Array of objects 休憩時間指定された時間範囲で指定された時間分の休憩を取る ※複数指定可
	object 車両情報
next_to_locations	Array of strings non-empty [ items >= 2 items ] 計算の結果、順番が隣り合ってほしい地点をリスト形式で指定します。 ※複数指定可順番が隣り合ってほしい地点は'unique_id'を使って指定します。使用する'unique_id'は'locations'の中で指定したものと同じものです。リスト内の順番は考慮されず、リスト内で指定された地点が連続して隣り合うような順番を返却します。
need_draw_data	boolean Default: false 描画用情報取得要否(true:取得する, false:取得しない) 地図に描画するための点列情報が必要な場合はtrueを、レスポンスサイズを小さくしたい場合はfalseを指定してください。

Responses

Request samples

Payload

Content type

application/json

{"map_region": "jp",
"user_id": "ID00110263",
"delivery_start_time": "2020-01-01T08:30+09:00",
"delivery_end_time": "2020-01-01T17:30+09:00",
"depot": {"unique_id": "depot",
"address": {"latitude": 35.93241737968212,
"longitude": 139.47167252901303
}
},
"start_location": {"unique_id": "start_location",
"latitude": 35.925045487700125,
"longitude": 139.48586784687123
},
"locations": [{"unique_id": "af6e489e-1a7e-45d3-b587-8311df6ae35d",
"address": {"latitude": 35.9078038201525,
"longitude": 139.4832576402253
},
"scheduled_time": {"range_start": "2020-01-01T08:30+09:00",
"range_end": "2020-01-01T17:30+09:00"
},
"service_time": 5
}
],
"search_condition": {"use_care_traffic": false,
"use_care_regulation": false,
"use_care_time_regulation": true,
"use_alongside": false,
"use_toll": false,
"use_hwy": false,
"use_ferry": false,
"use_smart_ic": false
},
"algorithm": {"travel_matrix_type": "time"
},
"break_time": [{"range_start": "2020-01-01T08:30+09:00",
"range_end": "2020-01-01T17:30+09:00",
"minutes": 45
}
],
"vehicle_info": {"rate_class": 0,
"etc": 0,
"type": 0,
"width": 178,
"height": 153,
"weight": 1480,
"dangerous_loaded": false
},
"next_to_locations": [["af6e489e-1a7e-45d3-b587-8311df6ae35d",
"a0221809-1ec1-48fb-ab2e-67c4395935f8"
]
],
"need_draw_data": false
}

Response samples

200

Content type

application/json

{"task_id": "a12c048a-85ea-4dbc-8df3-921395e8fd0e"
}

配送巡回最適化（非同期版）の結果取得

巡回順計算リクエストのタスクIDに対応する計算結果を取得します。
200OK(RUNNING)が返ってきた場合、計算結果を取得する為に約1分後に再度呼出しすることを推奨します。

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

task_id

required

string

巡回順計算リクエストに対応するタスクID

Responses

Request samples

Payload

Content type

application/json

{"task_id": "a12c048a-85ea-4dbc-8df3-921395e8fd0e"
}

Response samples

200

Content type

application/json

{"match_task_id": true,
"task_id": "a12c048a-85ea-4dbc-8df3-921395e8fd0e",
"calc_state": "FINISHED",
"order_result": {"skipped": false,
"skipped_location": ["a0221809-1ec1-48fb-ab2e-67c4395935f8"
],
"length": 1000,
"require_time": 1000,
"total_travel_cost": 147,
"break_time": [{"break_start": "2020-01-01T08:30+09:00",
"break_end": "2020-01-01T08:30+09:00"
}
],
"order": [{"unique_id": "af6e489e-1a7e-45d3-b587-8311df6ae35d",
"arrival_time": "2020-01-01T08:30+09:00",
"departure_time": "2020-01-01T08:30+09:00",
"service_time": 5
}
],
"toll": 1200,
"path_point_num": 10,
"path_point_list": [{"latitude": 35.93241737968212,
"longitude": 139.47167252901303
}
],
"path_point_info": {"road_kind": [{"kind": "general",
"index": 0
}
],
"toll": [{"kind": "free",
"index": 0
}
],
"section": [{"no": 0,
"index": 0
}
]
},
"eta_info": [{"length": 1000,
"require_time": 1000
}
]
}
}

Route Matrix API

ルートマトリクスAPI

ルートマトリクス API

各地点間のルーティングマトリクスを計算します。
地点数や地点間の距離により、応答までに時間が掛かり過ぎた結果、下記エラーコードが出力されることがあります。
504 Gateway timeout

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

map_region	string Default: "jp" Enum: "uc" "eu" "es" "jp" 地図地域 uc :北米 ※in future release(指定しても500エラーとなる) eu :欧州 ※in future release(指定しても500エラーとなる) es :東南アジア (時刻を指定する際、フィリピンの場合はUTC+8を、それ以外の国の場合はUTC+7を用いる) jp :日本 (時刻を指定する場合はUTC+9を用いる)
required	Array of objects [ 2 .. 25 ] items 地点リスト最大地点数:25 拡張が必要な場合は、営業窓口までお問い合わせください。
	object 探索条件
	object 車両情報
departure_time	string 出発時刻 ISO8601形式 (YYYY-MM-DDThh:mm±hh:mm) 時刻を指定した場合はその時刻を出発時刻としてルート探索されます。時刻を指定しない場合は現在時刻を出発時刻としてルート探索されます。

Responses

Request samples

Payload

Content type

application/json

{"map_region": "jp",
"locations": [{"latitude": 35.9414519983258,
"longitude": 139.47828054428103
},
{"latitude": 35.905803375482115,
"longitude": 139.4867510677732
},
{"latitude": 35.917972333353966,
"longitude": 139.49636936187747
}
],
"search_condition": {"use_toll": false,
"use_hwy": false,
"use_ferry": false,
"use_smart_ic": false,
"use_care_traffic": false,
"use_care_regulation": false,
"use_care_time_regulation": true
},
"vehicle_info": {"type": 0,
"width": 178,
"height": 153,
"weight": 1480,
"dangerous_loaded": false
},
"departure_time": "2020-01-01T08:30+09:00"
}

Response samples

200

Content type

application/json

{"result": true,
"travel_distance": [[0,
4339,
4107
],
[4446,
0,
1901
],
[4301,
1901,
0
]
],
"travel_time": [[0,
734,
701
],
[781,
0,
357
],
[579,
343,
0
]
],
"travel_cost": [[0,
7677,
7313
],
[7955,
0,
3661
],
[579,
343,
0
]
]
}

1×n（1対多）のルートマトリクス API

1番目の地点とそれ以外の地点間のルーティングマトリクスを計算します。

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

map_region	string Default: "jp" Enum: "uc" "eu" "es" "jp" 地図地域 uc :北米 ※in future release(指定しても500エラーとなる) eu :欧州 ※in future release(指定しても500エラーとなる) es :東南アジア (時刻を指定する際、フィリピンの場合はUTC+8を、それ以外の国の場合はUTC+7を用いる) jp :日本 (時刻を指定する場合はUTC+9を用いる)
required	Array of objects [ 2 .. 25 ] items 地点リストリストの[1番目] 対 [その他地点]に対してのルートマトリクスの計算を行います。最大地点数: 25 拡張が必要な場合は、営業窓口までお問い合わせください。
	object 探索条件
	object 車両情報
departure_time	string 出発時刻 ISO8601形式 (YYYY-MM-DDThh:mm±hh:mm) 時刻を指定した場合はその時刻を出発時刻としてルート探索されます。時刻を指定しない場合は現在時刻を出発時刻としてルート探索されます。
calc_single_dir	boolean Default: false 単一方向計算オプション false: リストの[1番目] 対 [その他地点]に対してのルートマトリクス（双方向）の計算を行います。 true: リストの[1番目] 対 [その他地点]に対してのルートマトリクス（単一方向）の計算を行います。例：地点のリストが[A, B, C, D, E]だった場合、Aを出発地とした単一方向（A→B, A→C, A→D, A→E）のみの計算が行われます。（B→A, C→A, D→A, E→Aは計算されません。）

Responses

Request samples

Payload

Content type

application/json

{"map_region": "jp",
"locations": [{"latitude": 35.9414519983258,
"longitude": 139.47828054428103
},
{"latitude": 35.905803375482115,
"longitude": 139.4867510677732
},
{"latitude": 35.917972333353966,
"longitude": 139.49636936187747
}
],
"search_condition": {"use_toll": false,
"use_hwy": false,
"use_ferry": false,
"use_smart_ic": false,
"use_care_traffic": false,
"use_care_regulation": false,
"use_care_time_regulation": true
},
"vehicle_info": {"type": 0,
"width": 178,
"height": 153,
"weight": 1480,
"dangerous_loaded": false
},
"departure_time": "2020-01-01T08:30+09:00",
"calc_single_dir": false
}

Response samples

200

Content type

application/json

{"result": true,
"travel_distance": [[0,
4339,
4107
],
[4446,
0,
-1
],
[4301,
-1,
0
]
],
"travel_time": [[0,
734,
701
],
[781,
0,
-1
],
[579,
-1,
0
]
],
"travel_cost": [[0,
7677,
7313
],
[7955,
0,
-1
],
[5967,
-1,
0
]
]
}

Traffic Timestamp API

交通情報タイムスタンプAPI

タイムスタンプ取得

渋滞、規制、駐車場等の渋滞情報から最新のタイムスタンプを取得します。
日本の緯度経度以外を指定した場合、APIは正常に動作しません。

Authorizations:

(ApiKeyAuthPECTrafficProviderKeyPECTrafficProviderUserID)

Request Body schema: application/json

userID required	string ユーザID
required	object 対象位置

Responses

Request samples

Payload

Content type

application/json

{"userID": "testUser",
"position": {"lat": 35.93241737968212,
"lon": 139.47167252901303
}
}

Response samples

200

Content type

application/json

{"userID": "testUser",
"errorCode": 0,
"type": "VICS",
"validity": true,
"timestamp": "23:35",
"timestampDetails": {"primary": "23:35",
"secondary": "23:35"
}
}