配送計画(自転車)
/auto_dispatch_bicycle [POST] [GET]
基本情報
概要
移動手段を自転車として、グループ化の条件によって分割された最適順に巡回するルートを検索します。
※当APIをご利用の場合は、オプション契約が別途必要となります
リクエスト回数について
本APIはルート検索に時間を要する場合があるため、1回のルート検索につき2回のリクエストが必要になります。
1回目はPOST形式で検索リクエストを受け付け、2回目はGET形式で検索結果を返却します。
URL
https://{HOST}/{CID}/v1/auto_dispatch_bicycle
※APIマーケットでは提供しておりません
出力形式
- JSON
対応言語
- ja, en, ko, zh-CN, zh-TW, th
パラメータ [POST]
Content-Typeヘッダーにapplication/x-www-form-urlencodedを指定し、 リクエストボディにパラメータを指定して送信してください。
signature及びrequest_codeはリクエストボディではなく、クエリパラメータに指定してください。
| パラメータ名 | 必須 | 概要 | 型名 | デフォルト値 | 上下限/選択値 | 備考 |
|---|---|---|---|---|---|---|
| num | (✔) | 経路の分割数 | 数値 | 上限：経由地数 | duration、capacityとの併用は不可（いずれかを必ず指定） 詳細はこちらをご覧ください |
|
| duration | (✔) | 各経路の所要時間(単位：分) | 数値 | 最小値：1 最大値：9999 |
num、capacityとの併用は不可（いずれかを必ず指定） 詳細はこちらをご覧ください |
|
| capacity | (✔) | 各経路の積載上限量 | 数値 | 最小値：1 最大値：9999 |
num、durationとの併用は不可（いずれかを必ず指定） 詳細はこちらをご覧ください |
|
| start | ✔ | 出発地点/到着地点 | ・地点のJSON表現 ・文字列（ノードID） ・カンマ区切りの数値（緯度,経度） |
緯度経度の指定例：35.689457,139.691935（東京都庁） | ||
| via | ✔ | 経由地 | 地点のJSON表現（配列） | 詳細はこちらをご覧ください | ||
| start_time | 出発時刻 | 文字列（日付時刻）YYYY-MM-DDThh:mm:ss |
時刻の指定例 2019-10-01T08:00:00 詳細はこちらをご覧ください |
|||
| goal_time | 到着時刻 | 文字列（日付時刻）YYYY-MM-DDThh:mm:ss |
時刻の指定例 2019-10-01T08:00:00 詳細はこちらをご覧ください |
|||
| speed | 自転車の速度(単位：km/h) | 整数値 | 15 | 最小値：5 最大値：132 |
自転車の速度を設定する場合は整数で時速を指定してください | |
| condition | 自転車ルート検索の優先考慮事項 | 文字列 | recommend | recommend：推奨ルート total_distance：総距離が短い low_pitched：坂道が少ない high_pitched：坂道が多い main_street：大通り優先 back_street：裏通り優先 cycling_road：サイクリングロード優先 |
||
| order | 出力順 | 文字列 | time | total_distance: 総移動距離 time: 所要時間 |
||
| options | 追加出力情報 | 文字列 | turn_by_turn：ターンバイターン情報 | 交差点等、進行情報を案内するための地点情報を取得します | ||
| datum | 緯度経度の測地系 | 文字列 | wgs84 | wgs84：世界測地系 tokyo：旧日本測地系 |
||
| coord_unit | 出力データに含まれる緯度経度の単位 | 文字列 | degree | degree：度表記の10進法 millisec：ミリ秒表記 |
||
| lang | 言語 | 文字列 | ja: 日本語 en: 英語 ko: 韓国語 zh-CN: 中国語(簡体字) zh-TW: 中国語(繁体字) th: タイ語 |
出力する言語を指定します ※多言語オプション申込時のみ利用可能 (APIマーケットでは利用不可) |
||
| shape | 形状出力 | 真偽値 | false | - true - false |
trueを指定時にはshapes(ルート形状)が出力されます |
グループ化の条件について
グループ化の条件は、目的に合わせてnum、duration、capacityのいずれかを指定することが可能です。
・num : 経路を分割する数を指定
利用例) 配送先(via)が100件に対して、配達担当4人(num=4)で運ぶ場合に誰がどこを回るのが効率的か
・duration : 各経路の所要時間を指定
利用例) 配送先(via)が100件に対して、各配達員の勤務時間を5時間(duration=300)とした時、何人で分割すれば良いか
・capacity : 各経路の積載量上限を指定
利用例) 各訪問先(via)に配送する量(cargo)が決まっている時、各配達員の積載量の上限を20とした場合に何台必要か
※capacityを利用する場合は、合わせて各経由地にcargo(配送貨物量)を指定してください。
また、capacityとcargoで指定する値は同じ単位を指定してください(例: kg, 個)。
※duration, capacityを指定した場合、指定した条件を満たさない場合があります。
ルート検索時の日付（時刻）指定について
出発時刻(start_time)と到着時刻(goal_time)を指定する場合は、どちらか片方を指定してください(同時指定はできません)。
・start_time（日付時刻指定）：出発地からの出発時刻の指定
・goal_time（日付時刻指定）：目的地への到着時刻の指定
両方未指定の場合は、POST通信の検索実行日時が出発時刻となります。
自転車の速度指定について
所要時間の精度向上のため、指定された速度を基準にルートの諸条件を考慮したものが利用されます。
必ずしも指定した速度の通りの所要時間にはならないことがありますので、予めご了承ください。
地点の JSON 表現
| プロパティ名 | 必須 | 概要 | 型名 | デフォルト値 | 備考 |
|---|---|---|---|---|---|
| lat | (✔) | 緯度 | 数値 | ||
| lon | (✔) | 経度 | 数値 | ||
| node | (✔) | 駅/連絡バス停ID | 文字列 | 経由地の場合は駅/連絡バス停IDは指定できません 緯度経度で指定してください |
|
| cargo | 配送貨物量 | 数値 | 0 | パラメータ「capacity」指定時に有効 指定されたcargoの値を元に積載量上限(capacity)を超えない様に経路を分割 |
|
| name | 地点名称 | 文字列 | |||
| stay-time | 経由地の滞在時間(単位：分) | 数値 | 最小値：0 最大値：300 経由地を指定する場合のみ使用可能です |
出発地点と到着地点、経由地点のJSON表現における必須項目の指定方法について
lat/lon、node の内どちらか一つの指定が必須となります(複数指定はエラー)。
latを指定した場合は、lonも必ず指定してください。
lonを指定した場合は、latも必ず指定してください。
経由地の指定方法について
経由地の数だけ地点のJSON表現を配列にして記述します。経由地が1点の場合でも配列表現が必要です。
経由地が1点の場合の記述例は以下の通りです。
via=[{"lat":35.706822,"lon":139.813956}]
最適順ルート、経由地間最適順ルートを求める場合、経由地は2地点以上登録する必要があります。
経由地指定の上限数は、250地点です。
上限数を超える経由地を指定するとエラーとなります。
レスポンス [POST]
| 名称 | レスポンス名 | 型名 | 配列 | 説明 |
|---|---|---|---|---|
| ルート検索ID | processing_id | 文字列 | リクエストを受け付けたルート検索ごとに発行されるID |
レスポンス例
{"processing_id": "8405511d33ebba6e122436b74cb6a215460609b6725b41a9d0ee0bf0b3f85ee9"}
パラメータ [GET]
| パラメータ名 | 必須 | 概要 | 型名 | デフォルト値 | 上下限/選択値 | 備考 |
|---|---|---|---|---|---|---|
| processing_id | ✔ | ルート検索ID | 文字列 | POSTリクエストで取得したIDを指定してください |
パラメータ構成例
/auto_dispatch_bicycle?processing_id=8405511d33ebba6e122436b74cb6a215460609b6725b41a9d0ee0bf0b3f85ee9
レスポンス [GET]
ルート検索が正常に完了している場合、レスポンスは/route_bicycleと同様です。
ルート検索が完了していない場合、POSTリクエストと同様のレスポンス「processing_id」を返却します。
5分程度時間をおいてから再度リクエストを実行してください。
検索結果はリクエスト実行後、24時間で削除されます。
エラー情報
エラーハンドリングについて
エラーメッセージは追加/変更/削除されることがあります。
エラーハンドリングされる場合はHTTPステータスコードをもとにご対応ください。
共通エラーについてはこちらをご参照ください。
| HTTPステータス | エラーメッセージ | 発生理由 |
|---|---|---|
| 405 | This http method is invalid : | 許可されていないHTTPメソッドでアクセスされた場合に発生します。 |
| POST リクエスト時 | --- | --- |
| 400 | request body is required | POSTリクエストでリクエストボディが指定されていない場合に発生します。 |
| 400 | parameter error: num: required field | 必須パラメータ num, duration, capacity のいずれも指定されていない場合に発生します。 |
| 400 | parameter error: num: ["'duration' must not be present with 'num'"], duration: ["'num' must not be present with 'duration'"] （等、excludes指定による組合せ） | num, duration, capacity のうち複数を同時に指定した場合に発生します。 |
| 400 | parameter error: num: min value is 1 | numが1未満の場合に発生します。 |
| 400 | parameter error: num: max value is 150 | numが150を超えている場合に発生します。 |
| 400 | parameter error: duration: min value is 1 | durationが1未満の場合に発生します。 |
| 400 | parameter error: duration: max value is 9999 | durationが9999を超えている場合に発生します。 |
| 400 | parameter error: capacity: min value is 1 | capacityが1未満の場合に発生します。 |
| 400 | parameter error: capacity: max value is 999999 | capacityが999999を超えている場合に発生します。 |
| 400 | parameter error: start: required field | 必須パラメータである start が指定されていない場合に発生します。 |
| 400 | parameter error: start: no definitions validate | start に指定した値のフォーマットが不正、または正しくない文字列が含まれている場合に発生します。 |
| 400 | parameter error: via: required field | 必須パラメータである via が指定されていない場合に発生します。 |
| 400 | parameter error: via: not json format : | via に不正なJSON文字列を指定した場合に発生します。 |
| 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: | start_time に不正な日時形式の値を指定した場合に発生します。 |
| 400 | parameter error: goal_time: an invalid datetime: | goal_time に不正な日時形式の値を指定した場合に発生します。 |
| 400 | parameter error: speed: min value is 5 | speedが5未満の場合に発生します。 |
| 400 | parameter error: speed: max value is 132 | speedが132を超えている場合に発生します。 |
| 400 | parameter error: condition: unallowed value | condition に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: order: unallowed value | order に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: options: an invalid item: | options に許可されていない値を指定した場合に発生します。 |
| 400 | parameter error: shape: unallowed value | shape に true, false 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: shape_format: unallowed value | shape_format に geojson, json 以外の不正な値を指定した場合に発生します。 |
| 400 | parameter error: shape_format: field 'shape' is required | shape_format を指定しているが、shape が指定されていない場合に発生します。 |
| 400 | parameter error: datum: unallowed value | datumにwgs84, tokyo以外を指定した場合に発生します。 |
| 400 | parameter error: coord_unit: unallowed value | coord_unitにdegree, millisec以外を指定した場合に発生します。 |
| 400 | parameter error: lang: unallowed value | langにja, en, ko, zh-CN, zh-TW, th以外を指定した場合に発生します。 |
| 400 | parameter error: coord_adjustment: unallowed value | coord_adjustmentにtrue, false以外を指定した場合に発生します。 |
| 400 | start is invalid. | start をJSON配列形式（複数地点）で指定した場合に発生します（自動配車では複数のstartは不可）。 |
| 400 | coordinate or node is required | start のJSON内に lat/lon, node のいずれも含まれていない場合に発生します。 |
| 400 | parameter error: {field}: ['{error}'] ※field は node, lat, lon, name |
start のJSON内部フィールドの値が不正な場合に発生します。 |
| 400 | via must be in json format | via のJSON文字列が正しい形式ではない場合に発生します。 |
| 400 | via must be in array format | via via がJSON配列形式ではない場合に発生します。 |
| 400 | list size is too large | via の経由地数が250を超過した場合に発生します。 |
| 400 | invalid num | num の値が via の要素数を超えている場合に発生します。 |
| 400 | parameter error: lat: required field | via の要素内に必須フィールドの lat が含まれていない場合に発生します。 |
| 400 | parameter error: lon: required field | via の要素内に必須フィールドの lon が含まれていない場合に発生します。 |
| 400 | parameter error: {field}: ['{error}'] ※field は lat, lon, name, stay-time, cargo |
via の各要素内のフィールドの値が不正な場合に発生します（stay-time は 0〜300 の範囲）。 |
| GET リクエスト時 | --- | --- |
| 400 | parameter error: processing_id: required field | 必須パラメータである processing_id が指定されていない場合に発生します。 |
| 400 | invalid processing_id | 指定された processing_id に対応するデータがS3に存在しない場合に発生します。 |