# OSRM Python API 使用說明
OSRM (Open Street Routing Machine) 是一個開源的地圖搜尋引擎，資料來源係基於 OpenStreetMap。OSRM 的底層使用 C++ 開發，並且官方提供 HTTP 接口，可供開發人員進行串接。本篇文章為筆者自行編寫的 [OSRM Python API](https://github.com/chhuang17/osrm_api) 使用說明，此 API 即是利用官方提供之 HTTP 接口，利用 Python 的 ```requests``` 套件爬取並解析 json 資料。

## 兩點之間求取旅行資訊
### 旅行距離
當您有任意兩點的經緯度座標時，您可以呼叫 ```distance()``` 函式，取得兩點間之旅行距離。兩點間的旅行距離是 OSRM 官方利用演算法求解得出，此處不詳述。必須注意的是，__座標填入必須先填入經度，再填入緯度__，即 __(經度, 緯度)__。

distance = osrm.distance(orign, destn, unit='m', steps='false')

#### 輸入引數 (Input Arguments)
|引數名稱|說明|資料型態|
|:--|:--|:--|
|```orign```|起點經緯度座標。|```list```, ```tuple```, or array-like|
|```destn```|迄點經緯度座標。|```list```, ```tuple```, or array-like|
|```unit```|度量單位，預設為 ```'m'```。|```str```|
|```steps```|是否回傳詳細資料，預設為 ```'false'```。|```str```|

#### 輸出 (Output)
兩點間旅行距離，資料型態為 ```float```。若 ```steps='true'```，

### 旅行時間
當您有任意兩點的經緯度座標時，您可以呼叫 ```travTime()``` 函式，取得兩點間之旅行時間。必須注意的是，__官方提供的旅行時間並不會因為在不同的時間 call API 有所變化__，另外，__座標也是必須先填入經度，再填入緯度__，即 __(經度, 緯度)__。

travelTime = osrm.travTime(orign, destn, unit='m', steps='false')

#### 輸入引數 (Input Arguments)
|引數名稱|說明|資料型態|
|:--|:--|:--|
|```orign```|起點經緯度座標。|```list```, ```tuple```, or array-like|
|```destn```|迄點經緯度座標。|```list```, ```tuple```, or array-like|
|```unit```|度量單位，預設為 ```'m'```。|```str```|
|```steps```|是否顯示詳細資料，預設為 ```'false'```。|```str```|

#### 輸出 (Output)
兩點間旅行距離，資料型態為 ```float```。若 ```steps='true'```，

***
## 多點之間求取旅行資訊
在很多使用情境下，您可能需要一次求取數個點彼此之間的旅行資訊。此外，若短時間內連續向 OSRM 官方提供的 HTTP 接口發送請求，官方會阻擋並間隔約 5 秒鐘的時間，才會回傳您需要的資訊。考量到程式運行效率，因此在實作上，大多時候會一次求取數個點的旅行資訊。

### O-D 矩陣
O-D 為 Origin-Destination 的縮寫，即起點-迄點的意思，是運輸學領域和地理學領域常見名詞。當您有任意 $N$ 個點的經緯度座標時，您可以呼叫 ```odMatrix()``` 函式，取得一 O-D 矩陣。

matrix = osrm.odMatrix(
             nodeList,
             get='distance',
             sources=None,
             distUnit='m',
             timeUnit='second'
         )

#### 輸入引數 (Input Arguments)
|引數名稱|說明|資料型態|
|:--|:--|:--|
|```nodeList```|$N$ 個點的經緯度座標。|```list```|
|```get```|欲取得之資訊，預設為 ```'distance'```。|```str```|
|```sources```|原點，預設為 ```None```。|```NoneType``` or ```int```|
|```distUnit```|距離度量單位，預設為 ```'m'```。|```str```|
|```timeUnit```|時間度量單位，預設為 ```'second'```。|```str```|

#### 輸出 (Output)
$N \times N$ 的方陣，資料型態為 ```np.array```。

### 旅行距離序列
若您手邊有 $N$ 個點的經緯度座標，且您想知道 $1 \rightarrow 2 \rightarrow 3 \rightarrow \cdots \rightarrow N$ 依序之旅行距離，您可以呼叫 ```distSeq()``` 函式，取得您需要的資訊。

distSeqList = osrm.distSeq(
                  nodeList=None,
                  matrix=None,
                  sources=None,
                  distUnit='m'
              )

#### 輸入引數 (Input Arguments)
|引數名稱|說明|資料型態|
|:--|:--|:--|
|```nodeList```|$N$ 個點的經緯度座標，預設為 ```None```，與 ```matrix``` 擇一輸入。|```NoneType``` or ```list```|
|```matrix```|欲取得之資訊，預設為 ```None```，與 ```nodeList``` 擇一輸入。|```NoneType``` or ```list```|
|```sources```|原點，預設為 ```None```。|```NoneType``` or ```int```|
|```distUnit```|距離度量單位，預設為 ```'m'```。|```str```|

#### 輸出 (Output)
點到點依序之旅行距離，資料型態為 ```list```，長度為 $N-1$。

### 旅行時間序列
若您手邊有 $N$ 個點的經緯度座標，且您想知道 $1 \rightarrow 2 \rightarrow 3 \rightarrow \cdots \rightarrow N$ 依序之旅行時間，您可以呼叫 ```travTimeSeq()``` 函式，取得您需要的資訊。

travTimeSeqList = osrm.travTimeSeq(
                      nodeList=None,
                      matrix=None,
                      sources=None,
                      timeUnit='second'
                  )

#### 輸入引數 (Input Arguments)
|引數名稱|說明|資料型態|
|:--|:--|:--|
|```nodeList```|$N$ 個點的經緯度座標，預設為 ```None```，與 ```matrix``` 擇一輸入。|```NoneType``` or ```list```|
|```matrix```|欲取得之資訊，預設為 ```None```，與 ```nodeList``` 擇一輸入。|```NoneType``` or ```list```|
|```sources```|原點，預設為 ```None```。|```NoneType``` or ```int```|
|```timeUnit```|距離度量單位，預設為 ```'second'```。|```str```|

#### 輸出 (Output)
點到點依序之旅行時間，資料型態為 ```list```，長度為 $N-1$。