介紹

這篇文章將透過HERE的Geocode and Search API中的地理定位功能，協助使用這快速解有效率的提供定位結果。
先要了解，什麼是Foward Geocode(定理定位)和Reverse Geocode(反向定理定位);

• Foward Geocode(定理定位) : 給予地址或所在地的文本資訊夠過API解讀後，獲取經緯度的絕對位置資訊。
• Reverse Geocode(反向定理定位) : 給予經緯度資訊，獲取該地點的相對文本地址資訊。

有興趣的同學，可參考這個網站提供的Demo(https://autosuggest-demo-app.now.sh/)。

準備

首先，使用HERE API，您必須註冊HERE的開發者帳號 developer.here.com，並於個人PROJECT內，產生一套專屬的RestFul API的憑證，在此我們會需要API-KEY的認證方式。
另外，本文章是透過Postman操作，可於該網站下載免費安裝檔(https://www.postman.com/)

Foward Geocode and Reverse Geocode

Foward Geocode將一串地址資訊翻譯為WGS84的經緯座標，用途上可以幫助用戶定位目的地，後提供路徑規劃，而Reverse Geocode則是將所在位置的經緯座標，轉換成地址資訊。用途上可協助運輸中的物品。於地圖上顯示位置，確定是否朝向正確的方向。
實現Foward and Revise Geocode的功能，這裡調用的是Geocoding and Search API 7中的/geocode端點服務，請求的URL架構如下：

• Scheme : https
• Base URL : [service].search.hereapi.com
• Version : v1
• Endpoint : /geocode or /revgeocode
• Parameters : [key]=[value]&...

必要的參數(Parameters)：

• apikey : 確認HERE使用者憑證。
• q : 可輸入任何形式語言的地址格式，例如：台北市市府路1號，或qq : 提供階層式的地址資訊，q或qq參數在foward geocode為必要的參數。例如：city=Taipei;postalCode=111;street=市府路;houseNumber=1。
• at : 提供更準確的搜尋位置，已提升搜尋結果的準確性，at參數在reverse geocode為必要的參數。格式：{緯度},{經度}，例如。at=25.03752,121.56442

非必要的參數 :

• in ：給予具體的搜尋國家，格式：Format: countryCode:{countryCode}[,{countryCode}]，例如in=countryCode:TWN,JPN
• limit : 回傳的筆數，預設為20。
• lang : 回傳內容的語言格式，例如： lang=zh。

For Example :

Foward Geocode :

https://geocode.search.hereapi.com/v1/geocode?q=台北市市府路1號&apikey=[YOURAPIKEY]&at=25.03752,121.56442&lang=en&in=countryCode:TWN

Response :

{
    "items": [
        {
            "title": "No. 1, Shi Fu Rd., Xinyi District, Taipei City, 110, Taiwan",
            "id": "here:af:streetsection:Ljel06yXXkHFgT8EXzR3ZC:CggIBCCNrcbCARABGgExKGQ",
            "resultType": "houseNumber",
            "houseNumberType": "PA",
            "address": {
                "label": "No. 1, Shi Fu Rd., Xinyi District, Taipei City, 110, Taiwan",
                "countryCode": "TWN",
                "countryName": "Taiwan",
                "county": "Taipei City",
                "city": "Taipei City",
                "district": "Xinyi District",
                "street": "Shi Fu Rd.",
                "postalCode": "110",
                "houseNumber": "1"
            },
            "position": {
                "lat": 25.03752,
                "lng": 121.56442
            },
            "access": [
                {
                    "lat": 25.03752,
                    "lng": 121.56355
                }
            ],
            "distance": 0,
            "mapView": {
                "west": 121.56343,
                "south": 25.03662,
                "east": 121.56541,
                "north": 25.03842
            },
            "scoring": {
                "queryScore": 1.0,
                "fieldScore": {
                    "city": 1.0,
                    "streets": [
                        1.0
                    ],
                    "houseNumber": 1.0
                }
            }
        }
    ]
}

Revrse Geocode :

https://revgeocode.search.hereapi.com/v1/revgeocode?lang=zh-TW&at=25.03752,121.56442&apikey=[YORAPIKEY]

Response

{
    "items": [
        {
            "title": "台灣110台北市信義區市府路1號",
            "id": "here:af:streetsection:Ljel06yXXkHFgT8EXzR3ZC:CggIBCCNrcbCARABGgEx",
            "resultType": "houseNumber",
            "houseNumberType": "PA",
            "address": {
                "label": "台灣110台北市信義區市府路1號",
                "countryCode": "TWN",
                "countryName": "台灣",
                "county": "台北市",
                "city": "台北市",
                "district": "信義區",
                "street": "市府路",
                "postalCode": "110",
                "houseNumber": "1"
            },
            "position": {
                "lat": 25.03752,
                "lng": 121.56442
            },
            "access": [
                {
                    "lat": 25.03752,
                    "lng": 121.56355
                }
            ],
            "distance": 0,
            "mapView": {
                "west": 121.56352,
                "south": 25.0359,
                "east": 121.56355,
                "north": 25.03916
            }
        }
    ]
}

另外，Geocode and Search API 也結合了POI的資訊，因此當你找地理定位時，也可加入您周邊POI的資訊，可以提供更直覺式的搜尋並回傳更準確的結果。例如，我想要找台北市市府路附近的星巴克。

https://geocode.search.hereapi.com/v1/geocode?q=台北市市府路 星巴克&apikey=[YOURAPIKEY]&at=25.03752,121.56442&lang=zh-TW&in=countryCode:TWN

RESPONSE

{
    "items": [
        {
            "title": "星巴克",
            "id": "here:pds:place:158wsqqq-2395fee183e448ff95025d45314369e9",
            "resultType": "place",
            "address": {
                "label": "星巴克, No. 45號, 市府路, 信義區, 台北市, 110, 台灣",
                "countryCode": "TWN",
                "countryName": "台灣",
                "county": "台北市",
                "city": "台北市",
                "district": "信義區",
                "street": "市府路",
                "postalCode": "110",
                "houseNumber": "45號"
            },
            "position": {
                "lat": 25.033,
                "lng": 121.56448
            },
            "access": [
                {
                    "lat": 25.033,
                    "lng": 121.56353
                }
            ],
            "distance": 503,
            "categories": [
                {
                    "id": "100-1100-0010",
                    "name": "咖啡館",
                    "primary": true
                }
            ],
            "foodTypes": [
                {
                    "id": "800-058",
                    "name": "輕食",
                    "primary": true
                }
            ],
            "scoring": {
                "queryScore": 1.0,
                "fieldScore": {
                    "city": 1.0,
                    "streets": [
                        1.0
                    ],
                    "placeName": 1.0
                }
            }
        }
    ]
}