[toc]

# 國際地圖編碼
最近有查詢 Mapcode 的需求，所以在網路上快速搜尋了一下，發現並沒有直接提供的 API 查詢方式。卻發現了幾個有趣的地方，不過資訊也是片段取得，可能無法全面了解，也可能有謬誤之處。但最終目的是要**透過 cURL 命令操作來取得指定地點的地圖編碼**。

- 國際地圖編碼(Mapcode)系統原來是個開源地理編碼(Geocode)系統，目前由 [**Mapcode Foundation**](https://www.mapcode.com/) 維護。相關訊息可以參考 [[**Mapcode@Wiki**]](https://en.wikipedia.org/wiki/Mapcode)。
- Mapcode 基金會有提供 REST API 方式進行地圖編碼資訊查詢。可參考 [[**Mapcode REST API 網頁**]](https://www.mapcode.com/rest-api) 說明自行遊玩。
- Google 似乎沒有加入上面的 Mapcode 生態系，反倒是在 Google 地圖中提供了 [[**Plus Code**]](https://maps.google.com/pluscodes/)。除了在 Google 地圖中可取得 Plus Code 資訊，這個[[網頁]](https://plus.codes/map)也可以直接查詢。
- 當然只要啟用了 [**Google 地圖平台**](https://developers.google.com/maps?hl=zh-tw) 提供的 **API 相關服務**，就可以根據需求取得對應的資訊。

:::warning
看來地圖編碼系統也很好玩，但現在還是先回到日本地圖編碼吧！
:::

# 日本地圖編碼
目前日本使用的地圖編碼，應該指的是 Denso 發展的地圖編碼系統，與上面提到的**國際地圖編碼**屬於不同的空間參考系統。可參考 [[**Denso Mapcode@Wiki**]](https://en.wikipedia.org/wiki/Denso_mapcode) 提供的資訊說明。

:::warning
以下提到的地圖編碼 Mapcode 就單指是日本所使用的地圖編碼(Japan Mapcode)。暫時就先忘記國際地圖編碼吧！
:::

Denso 開發的地圖編碼是 **7 ~ 10 位數字代碼** 用來標示日本地理位址。

:::info
識別圖標 <img width=100 src='https://upload.wikimedia.org/wikipedia/commons/thumb/a/a4/Mapcode1-768x274.jpg/220px-Mapcode1-768x274.jpg'>
:::

**但是**似乎在網路上並沒有直接找到有提供 Japan Mapcode 的 API 查詢方式。目前常被推薦使用的網站有下列兩個：
- **Mapion** [[**http://mapion.co.jp**]](http://mapion.co.jp)

這個網站僅提供日文地址查找地圖編碼，對於不懂日文的我，實用性不高。不過這個網站可提供的資訊較為豐富，若是懂日文的相棒應該是不錯的網站。
- **Japan Mapcode** [[**http://japanmapcode.com**]](http://japanmapcode.com/)

使用方式類似 Google 地圖，只要輸入要查詢的地址，或是在地圖上點擊位置，網站就會顯示其地圖代碼資訊。由於接受**中文地址輸入**，也可直接**透過瀏覽器**使用，若是有 Mapcode 查詢需求，利用該網站是強烈推薦的。

# 網站探索
雖然 [Japan Mapcode](http://japanmapcode.com/) 視覺化使用體驗很棒，但是對於想要批次查詢 Mapcode 需求的，並沒有提供 API 方式進行批次查詢。所以就花了點時間研究一下網站實際的運作模式，或許可以產生另一種不同的使用方式。

:::warning
探索過程很有趣，但對於一般地球人還是有點乏味，所以以下就簡單帶過吧！
:::

開啟 Chrome 瀏覽器，並啟用**開發人員工具**，任意挑個日本地點 **丹後天橋立大江山國定公園** 作為測試，選擇上方 **Network** 選項，觀察右側產生的網頁瀏覽行為。輸入完成網站會在下方顯示該地點的地圖編碼為 **`197 233 603*15`**。


然後我對於其中的 **`japan-mapcode-1.2.0.js`** 感到興趣！這裡似乎有使用 **Google 地圖平台進行地址或是經緯度轉換**？！

:::info
**Geocoding API 服務** 可接受地點為**地址**、**經緯度座標**或 **Place ID** 的服務。會將地址轉換成經緯度座標和地點 ID，或將經緯度座標或地點 ID 轉換成地址。
[**Geocoding API**](https://developers.google.com/maps/documentation/geocoding?hl=zh-tw)
:::

另外將右側程式碼往下滑，發現有跟 Mapcode 查詢相關的代碼(ll.217 ~ 238)。


上面的動作應該是對於 **restUri** 進行 **POST request**，而帶入的參數應為 **{"lat": "查詢地點的緯度","lng": "查詢地點的經度"}**。其中 **restUri = API_BASE + "/mapcode"**。

等等！這個動作不就是在進行 REST API 查詢動作，有沒有這麼輕鬆？！

若以 cURL 執行操作，應該可用下列命令進行相關動作：

#!/bin/bash

restUri='http://japanmapcode.com/mapcode'
lat="${place_latitude}"
lng="${place_longitude}"

curl -X POST ${restUri} --data-urlencode "lat=${lat}" --data-urlencode "lng=${lng}"

# API 測試
## 簡易編程
大致上的 API 呼叫程序應該就是上面那樣，再來還有一點需要先進行轉換的，就是**地點或地址要先轉換成經緯度格式**，看來這部份網站也是透過 [Google Geocoding Service](https://developers.google.com/maps/documentation/javascript/geocoding?hl=zh-tw) 或是 [Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/reference/geocoder?hl=zh-tw) 完成的。


:::info
- 這部份請各位自行花時間研讀，很好玩的！這裡就不多說了，以免壞了學習興致。
- 有興趣的可以直接看這篇 [[使用Google Map API (Geocoding API) 得到點位縣市鄉鎮資料]](https://icelandcheng.medium.com/%E4%BD%BF%E7%94%A8google-map-api-geocoding-api-%E5%BE%97%E5%88%B0%E9%BB%9E%E4%BD%8D%E7%B8%A3%E5%B8%82%E9%84%89%E9%8E%AE%E8%B3%87%E6%96%99-25bf5f0e4a21)，應該就可以快速上手了。
:::

所以程式構想就是：
1. 將地點或地址先轉換成經緯度格式。
2. 再將經緯度格式帶入 Mapcode API 進行查詢請求。

直接看一下結果！

**丹後天橋立大江山國定公園**
[Mapcode: 197 233 603*15]

**小樽天狗山**
[Mapcode: 164 534 874*20]

## Postman 軟體
使用 API 方式，一定要試試 Postman 軟體，也是不錯的選擇。直接看結果吧！

**旭川常盤ロータリー** [Mapcode: 79 373 629*52]

# 附錄
使用程式及 Postman 軟體讀取地點清單，批次查詢 Mapcode。

## 地點清單 place.csv
Netflix First Love 景點

place
旭川常盤ロータリー
千歲西洋軒
千歳フジボウル
札幌市天文台
Baluko Laundry Place 東苗穂 コインランドリー
小樽天狗山
平岸ハイヤー株式会社
北海道長沼町 ハイジ Heidi 牧場
LOTTERIA 札幌中央店
日本北海道上川郡美瑛車站

## 使用 mapcode.sh 程式
:::info
使用 BASH 腳本程式，只要一行！就可以將所需要地點的 Mapcode 完成查詢，真的是太棒了。之後只要編輯 `place.csv` 資料檔，就可以達成相同目標。:100:
:::

## 使用 Postman 軟體
### Environment Variables

### Request: Get Geocode

:::info

let query_place = pm.iterationData.get('place')

將會使用匯入的資料檔欄位 `place` 作為輸入內容。
:::



### Request: Get Mapcode


### Run Collection


:::info
選擇資料檔 `place.csv`，可先預覽其中的內容，透過先前 `pm.iterationData.get('place')` 取出作為批次執行的內容。如此一來，就可以快速完成 Mapcode 資料取得！:100:
:::


# 參考
- [Mapcode Foundation](https://www.mapcode.com/)
- [Mapcode REST API](https://www.mapcode.com/rest-api)
- [Google Geocoding API](https://developers.google.com/maps/documentation/geocoding/overview?hl=zh-tw)
- [使用Google Map API (Geocoding API) 得到點位縣市鄉鎮資料](https://icelandcheng.medium.com/%E4%BD%BF%E7%94%A8google-map-api-geocoding-api-%E5%BE%97%E5%88%B0%E9%BB%9E%E4%BD%8D%E7%B8%A3%E5%B8%82%E9%84%89%E9%8E%AE%E8%B3%87%E6%96%99-25bf5f0e4a21)
- [Denso Mapcode](https://en.wikipedia.org/wiki/Denso_mapcode)
- [Japan Mapcode 查詢網站](https://japanmapcode.com/zh-TW)
- [Mapion 網站](https://www.mapion.co.jp/)