多地点巡回ルート検索（車）
/round_route_car [POST] [GET]
基本情報
概要
自動車を移動手段として、2地点間のルートを検索します。
/route_carよりも多くの経由地指定が可能です。
※当APIをご利用の場合は、オプション契約が別途必要となります
リクエスト回数について
本APIはルート検索に時間を要する場合があるため、1回のルート検索につき2回のリクエストが必要になります。
1回目はPOST形式で検索リクエストを受け付け、2回目はGET形式で検索結果を返却します。
実装のヒント
サンプルページはこちらからご確認いただけます。
URL
https://{HOST}/{CID}/v1/round_route_car
※APIマーケットでは提供しておりません
出力形式
- JSON
対応言語
- ja
1回目のリクエスト
パラメータ [POST]
- 「ルート検索（車）/route_car」と同等のパラメータを受け付けます
- 本API独自のパラメータは以下の通りです
| パラメータ名 | 必須 | 概要 | 型名 | デフォルト値 | 上下限/選択値 | 備考 |
|---|---|---|---|---|---|---|
| optimization_timeout_mode | ルート最適化までの時間を伸ばすか | 真偽値 | true : 最適化時間を伸ばす false : 最適化時間を伸ばさない |
レスポンスタイムを増やす代わりに、より最適化されたルート結果を返却します |
Content-Typeヘッダーにapplication/x-www-form-urlencodedを指定し、 リクエストボディにパラメータを指定して送信してください。
signature及びrequest_codeはリクエストボディではなく、クエリパラメータに指定してください。
経由地の指定方法について
経由地指定の上限数は150地点です。
出発地点、到着地点は含みません。
150地点以上の経由地を指定するとエラーとなります。
レスポンス [POST]
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| ルート検索ID | processing_id | 文字列 | リクエストを受け付けたルート検索ごとに発行されるID |
レスポンス例
{"processing_id": "8405511d33ebba6e122436b74cb6a215460609b6725b41a9d0ee0bf0b3f85ee9"}
2回目のリクエスト
パラメータ [GET]
| パラメータ名 | 必須 | 概要 | 型名 | デフォルト値 | 上下限/選択値 | 備考 |
|---|---|---|---|---|---|---|
| processing_id | ✔ | ルート検索ID | 文字列 | POSTリクエストで取得したIDを指定してください |
パラメータ構成例
/round_route_car?processing_id=8405511d33ebba6e122436b74cb6a215460609b6725b41a9d0ee0bf0b3f85ee9
レスポンス [GET]
- ルート検索が正常に完了している場合、レスポンスは/route_carと同様です。
- shape=trueを指定した場合はshapes（ルート形状）が出力されます。shapesは/shape_carのGeoJSON形式のレスポンスと同様です。
レスポンス例
・shape=trueを指定の場合
{
"items": [
{
"summary": {
"no": "1",
"start": {
"type": "point",
"coord": {
"lat": 35.676028,
"lon": 139.740678
},
"name": "start"
},
"goal": {
"type": "point",
"coord": {
"lat": 35.663267,
"lon": 139.775531
},
"name": "goal"
},
"move": {
"toll_road_distance": 0,
"type": "move",
"from_time": "2022-01-22T02:00:00+09:00",
"to_time": "2022-01-22T02:14:34+09:00",
"time": 14,
"distance": 4520,
"other_fare": {
"taxi": 1860
}
},
"via": [
{
"from_time": "2022-01-22T02:00:00+09:00",
"to_time": "2022-01-22T02:00:00+09:00",
"type": "point",
"coord": {
"lat": 35.676028,
"lon": 139.740678
},
"name": "経由地"
},
{
"from_time": "2022-01-22T02:02:02+09:00",
"to_time": "2022-01-22T02:02:02+09:00",
"type": "point",
"coord": {
"lat": 35.675967,
"lon": 139.742164
},
"name": "経由地"
}
]
},
"sections": [
{
"type": "point",
"coord": {
"lat": 35.676028,
"lon": 139.740678
},
"name": "start"
},
{
"type": "move",
"move": "car",
"from_time": "2022-01-22T02:00:00+09:00",
"to_time": "2022-01-22T02:00:00+09:00",
"time": 0,
"distance": 0,
"line_name": "車"
},
{
"type": "point",
"coord": {
"lat": 35.676028,
"lon": 139.740678
},
"name": "経由地",
"with_via": true,
"stay_time": 0
},
{
"type": "move",
"move": "car",
"from_time": "2022-01-22T02:00:00+09:00",
"to_time": "2022-01-22T02:02:02+09:00",
"time": 2,
"distance": 561,
"line_name": "車"
},
{
"type": "point",
"coord": {
"lat": 35.675967,
"lon": 139.742164
},
"name": "経由地",
"with_via": true,
"stay_time": 0
},
{
"type": "move",
"move": "car",
"from_time": "2022-01-22T02:02:02+09:00",
"to_time": "2022-01-22T02:14:34+09:00",
"time": 12,
"distance": 3959,
"line_name": "車"
},
{
"type": "point",
"coord": {
"lat": 35.663267,
"lon": 139.775531
},
"name": "goal"
}
],
"shapes": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"bbox": [
139.740678,
35.676028,
139.741473,
35.676077
],
"geometry": {
"type": "LineString",
"coordinates": [
[
139.740678,
35.676028
],
[
139.741473,
35.676077
]
]
},
"properties": {
"ways": "car",
"section": "0001",
"inline": {
"line_style": "auxiliary",
"width": 5,
"color": "#D3D3D3",
"opacity": 1.0,
"strokelinecap": "round",
"strokelinejoin": "round"
},
"outline": {
"line_style": "solid",
"width": 10,
"color": "#898989",
"opacity": 1.0,
"strokelinecap": "round",
"strokelinejoin": "round"
},
"route_no": "1"
}
},
{
...
},
...
],
"bbox": [
139.740678,
35.662681,
139.775531,
35.678119
]
}
}
],
"unit": {
"datum": "wgs84",
"coord_unit": "degree",
"distance": "metre",
"time": "minute"
}
}
ルート検索が完了していない場合、POSTリクエストと同様のレスポンス「processing_id」を返却します。
5分程度時間をおいてから再度リクエストを実行してください。
検索結果はリクエスト実行後、24時間で削除されます。
エラー情報
エラーハンドリングについて
エラーメッセージは追加/変更/削除されることがあります。
エラーハンドリングされる場合はHTTPステータスコードをもとにご対応ください。
共通エラーについてはこちらをご参照ください。
| HTTPステータス | エラーメッセージ | 発生理由 |
|---|---|---|
| 405 | This http method is invalid : PUT (等) | 許可されていないHTTPメソッドでアクセスされた場合に発生します。 |
| POST リクエスト時 | --- | --- |
| 400 | request body is required | POSTリクエストでリクエストボディが指定されていない場合に発生します。 |
| 400 | parameter error: start: ['required field'] | 必須パラメータである start が指定されていない、または空文字の場合に発生します。 |
| 400 | parameter error: start: ['no definitions validate'] | start に指定した値のフォーマットが不正、または正しくない文字列が含まれている場合に発生します。 |
| 400 | parameter error: goal: required field | 必須パラメータである goal が指定されていない、または空文字の場合に発生します。 |
| 400 | parameter error: goal: ['no definitions validate'] | goal に指定した値のフォーマットが不正、または正しくない文字列が含まれている場合に発生します。 |
| 400 | parameter error: start_time: ["'goal_time' must not be present with 'start_time'"], goal_time: ["'start_time' must not be present with 'goal_time'"] | start_time と goal_time を同時に指定した場合に発生します。 |
| 400 | parameter error: start_time: ['an invalid datetime: {value}'] または goal_time: ['an invalid datetime: {value}'] | start_time または goal_time に不正な日時形式の値を指定した場合に発生します。 |
| 400 | parameter error: via: ['not json format : {value}'] | via に不正なJSON文字列を指定した場合に発生します。 |
| 400 | parameter error: via_type: ['unallowed value {value}'] | via_type に specified, optimal, via_optimal 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: via_type: ["field 'via' is required"] | via_type を指定しているが、via が指定されていない場合に発生します。 |
| 400 | parameter error: condition: ['unallowed value {value}'] | condition に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: regulation: ['not json format : {value}'] | regulation に不正なJSON文字列を指定した場合に発生します。 |
| 400 | parameter error: order: ['unallowed value {value}'] | order に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: use_traffic: ['an invalid item: {value}'] | use_traffic に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: uid: ['min length is 1'] または uid: ['max length is 50'] | uid の文字列長が1未満または50超過の場合に発生します。 |
| 400 | parameter error: use_road: ['an invalid category: {value}'] | use_road に不正な道路IDを指定した場合に発生します。 |
| 400 | parameter error: unuse_road: ['an invalid category: {value}'] | unuse_road に不正な道路IDを指定した場合に発生します。 |
| 400 | parameter error: options: ['an invalid item: {value}'] | options に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: smart_ic: ['unallowed value {value}'] | smart_ic に use, unuse 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: ferry: ['unallowed value {value}'] | ferry に more_use, use, unuse 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: wide: ['unallowed value {value}'] | wide に more_use, use, unuse 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: etc: ['unallowed value {value}'] | etc に use, unuse 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: avoid_etc_only: ['unallowed value {value}'] | avoid_etc_only に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: search_mode: ['unallowed value {value}'] | search_mode に fast 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: shape: ['unallowed value {value}'] | shape に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: datum: ['unallowed value {value}'] | datum に wgs84, tokyo 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: coord_unit: ['unallowed value {value}'] | coord_unit に degree, millisec 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: lang: ['unallowed value {value}'] | lang に ja, en, ko, zh-CN, zh-TW, th 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: coord_adjustment: ['unallowed value {value}'] | coord_adjustment に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: divide_with: ['an invalid item: {value}'] | divide_with に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: optimize_riding_location: ['unallowed value {value}'] | optimize_riding_location に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: optimization_timeout_mode: ['unallowed value {value}'] | optimization_timeout_mode に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: use_byway: ['unallowed value {value}'] | use_byway に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: continuous_driving_time: ['min value is 120'] または continuous_driving_time: ['max value is 240'] | continuous_driving_time に数値以外の文字列を指定した場合や、下限値（120未満）や上限値（240超過）の範囲外の値を指定した場合に発生します。 |
| 400 | start and goal are both multiple. | start と goal の両方をJSON配列形式（複数地点）で指定した場合に発生します。 |
| 400 | coordinate or node or ic is required | start または goal のJSON内に lat/lon, node, ic のいずれも含まれていない場合に発生します。 |
| 400 | invalid list size | start または goal をJSON配列形式で指定し、要素数が0または10超の場合に発生します。 |
| 400 | list item must be coordinate | start または goal のJSON配列内の要素に node, ic, spot を含む場合に発生します（多対一/一対多検索では座標のみ使用可）。 |
| 400 | coordinate is required | start または goal のJSON配列内の要素に lat または lon が含まれていない場合に発生します。 |
| 400 | parameter error: {field}: ['{error}'] ※field は lat, lon, node, ic, road-type, angle, park-side, spot 等 | start または goal のJSON内部フィールドの値が不正な場合に発生します。 |
| 400 | via must be in json format | via のJSON文字列が正しい形式ではない場合に発生します。 |
| 400 | via must be in array format | viaがJSON配列形式ではない場合に発生します。 |
| 400 | coordinate or ic is required | via の要素内に lat/lon も ic も含まれていない場合に発生します。 |
| 400 | goal or start is multiple | via を指定しつつ、start または goal がJSON配列形式（複数地点）の場合に発生します。 |
| 400 | list size is too large | via の経由地数が契約上の上限値を超過した場合に発生します。 |
| 400 | invalid stay-time | via_type が optimal または via_optimal の場合に、経由地の stay-time が300（5時間）を超過した場合に発生します。 |
| 400 | invalid via_type | via に交差点IDを含みつつ via_type が specified 以外の場合、または via に IC を含みつつ via_type が specified 以外の場合に発生します。 |
| 400 | too many intersections | via 内に交差点IDが3つ以上含まれている場合に発生します。 |
| 400 | from_time must be earlier than to_time | via の arrival-times 内で from が to より後の日時の場合に発生します。 |
| 400 | list size (via) is too small | arrival-times を使用しているが、via の要素数が2未満の場合に発生します。 |
| 400 | arrival-times must use with optimal(via_type) | arrival-times を使用しているが、via_type が specified の場合に発生します。 |
| 400 | start_time or goal_time required. | arrival-times を使用し via_type が optimal だが、start_time も goal_time も指定されていない場合に発生します。 |
| 400 | parameter error: {field}: ['{error}'] ※field は lat, lon, stay-time, road-type, park-side, arrival-times, ic, ic-passing-type, intersection, cargo 等 |
via の各要素内のフィールドの値が不正な場合に発生します。 |
| 400 | parameter error: regulation-type: ['unallowed value {value}'] | regulation 内の regulation-type に許可されていない車種を指定した場合に発生します。 |
| 400 | parameter error: toll-type: ['unallowed value {value}'] | regulation 内の toll-type に許可されていない料金車種を指定した場合に発生します。 |
| 400 | parameter error: {field}: ['{error}'] ※field は height, width, length, weight, max-loading-capacity | regulation 内の car-body の各フィールドの値が不正な場合に発生します。 |
| 400 | parameter error: dangerous-goods: ['unallowed value {value}'] | regulation 内の dangerous-goods に use 以外の不正な値を指定した場合に発生します。 |
| 400 | invalid road id | use_road と unuse_road の両方に同じ道路IDを指定した場合に発生します。 |
| 400 | optimize_riding_location | optimize_riding_location=true を指定したが、start が座標（lat,lon）形式ではなく node や ic で指定されている場合に発生します。 |
| 400 | order | start と goal がいずれも単一地点（配列ではない）の場合に order パラメータを指定した場合に発生します（order は多対一/一対多のみ使用可）。 |
| 400 | bad usage on this contract : Multilingual | lang パラメータを指定したが、契約で多言語オプションが有効化されていない場合に発生します。 |
| 400 | bad usage on this contract : useZone30 | use_byway=true を指定したが、契約で Zone30 オプションが有効化されていない場合に発生します。 |
| 400 | bad usage on this contract : regulation | regulation を指定したが、契約で大型車オプションが有効化されていない場合に発生します。 |
| GET リクエスト時 | --- | --- |
| 400 | parameter error: processing_id: required field | 必須パラメータである processing_id が指定されていない場合に発生します。 |
| 400 | invalid processing_id | 指定された processing_id に対応するデータがS3に存在しない場合に発生します。 |