驚くほど多機能なHEREのRouting APIを使ってみよう

![output-palette.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2788/803bd1d6-2fe9-ef91-3b9f-eb54f8690ffb.gif)

# はじめに
地図データや位置情報のプラットフォームを提供している、HEREという有名なグローバル企業があるのですが、そのHEREの提供しているAPIが多機能ですごかったので、ごく一部となりますが紹介したいと思います
グローバルな企業だと、日本語のWEBサイトの情報量が薄い事が良く見られるのですが、HEREの日本語のWEBサイトの内容はかなり充実しています

https://www.here.com/jp

# 目次

1. [前提](#Chapter1)
1. [HERE Routing API](#Chapter2)
1. [とにかく豊富なパラメーター](#Chapter3)
1. [公式デモサイト](#Chapter4)

<a id="#Chapter1"></a>
# 前提

APIを利用するためには、前提として
- HEREのDeveloper登録をしている
- その上でAPIキーの発行をしている
必要があります

Routing APIの公式ドキュメントに記載がありますので、登録してしまいましょう
登録にはお金はかかりません

HEREはとても数多くのAPIを提供していますが、今回の紹介はRouting APIに限らせていただきます
以下、Routing APIの日本語リファレンスページです

https://jp.developer.here.com/documentation/routing-api/dev_guide/index.html

英語ですがSwaggerのAPIリファレンスもあります

https://developer.here.com/documentation/routing-api/api-reference-swagger.html

<a id="#Chapter2"></a>
# HERE Routing API

そもそも、Routing APIとはなんぞや、という話なのですが
スタート地点とゴール地点の2点間の経路検索のためのAPIになります

なので、基本は
- スタート地点
- ゴール地点
- 移動手段
の3つのパラメーターを設定してあげればOKです
curlでAPIを実行してみます

```
curl -X GET \
'https://router.hereapi.com/v8/routes?transportMode=car&origin=43.068411,141.350900&destination=43.064631,141.362023&apikey={YOUR_KEY}'
```
※ {YOUR_KEY}はAPIキーを設定します
スタート地点の座標：origin
ゴール地点の座標：destination
移動手段：transportMode
- pedestrian（歩行者）
- car（自動車）
- truck（トラック）
- bicycle（自転車）
- scooter（スクーター）

移動手段にスクーターが設定出来るのが他に無いかもですが、ここまでは他のRouting APIとほぼ同様ですね
レスポンスは以下のような感じになります
```
{"routes":[{
    "id":"fd8bf9ac-6994-4da6-bd19-65bf43ad6360",
    "sections":[{
        "id":"e60d4705-43bc-452e-bd40-cde37d6f005f",
        "type":"vehicle",
        "departure":{
            "time":"2022-06-24T17:20:33+09:00",
            "place":{
                 "type":"place",
                 "location":{
                     "lat":43.0668075,
                     "lng":141.3507903
                 },
                 "originalLocation"{
                     "lat":43.0684109,
                     "lng":141.3509
                 }
             }
        },
        "arrival":{
            "time":"2022-06-24T17:24:10+09:00",
            "place":{
                "type":"place",
                "location":{
                    "lat":43.0646414,
                    "lng":141.3620202
                },
                "originalLocation":{
                    "lat":43.064631,
                    "lng":141.3620229
                }
            }
         },
        "transport":{"mode":"car"}
      }]
   }]
}
```

<a id="#Chapter3"></a>
# とにかく豊富なパラメーター

で、ココからが本題
なのですが、正直言いますと、あまりにも多すぎ把握しきれませんでした

ざっと見た感じだけでも
- ルートの形（シェイプ）を取得する
- 標高を加味した計算を行う
- 何m先右へ曲がれなどの指示のアクションを取得する
- 道路の名称を取得する
- 到着地が道路の右側か左側かを考慮する
- 道路の分離帯のありなしを加味する
- 複数経由地のルート
- 以前計算されたルートをキャッシュして新しいルート検索に利用する
- 言語や時刻帯の変更
- フェリーの利用の追加
- 最高速度の設定
- 回避する場所の設定
- etc....

中にはEV（電気自動車）に特化した、充電状態の設定、取得などもありました
総じて言えるのは、「物流」で利用したいパラメーターはほぼ揃っているのではなかろうかと思われます

最後に札幌駅からサッポロファクトリーまで徒歩で移動した場合の道のりを取得したものを貼っておきます
（YOUR_KEYのところは自分のAPIキーに置き換えてください）

```
curl -X GET \
'https://router.hereapi.com/v8/routes?transportMode=pedestrian&origin=43.068411,141.350900&destination=43.064631,141.362023&return=polyline,actions,instructions&lang=ja&apikey={YOUR_KEY}'
```
以下レスポンス
```
{
	"routes": [
		{
			"id": "b2b4c173-06d4-427c-9b73-b2e011eaa96a",
			"sections": [
				{
					"id": "f33e4177-06f7-47a7-94af-00af838feddd",
					"type": "pedestrian",
					"actions": [
						{
							"action": "depart",
							"duration": 56,
							"length": 56,
							"instruction": "南 に向かいます. 56 m 進みます.",
							"offset": 0
						},
						{
							"action": "turn",
							"duration": 70,
							"length": 59,
							"instruction": "右 に曲がります. 59 m 進みます.",
							"offset": 1,
							"direction": "right",
							"severity": "quite"
						},
						{
							"action": "turn",
							"duration": 415,
							"length": 405,
							"instruction": "左 に曲がって 北5条・手稲通 に入ります. 405 m 進みます.",
							"offset": 5,
							"direction": "left",
							"severity": "quite"
						},
						{
							"action": "turn",
							"duration": 267,
							"length": 267,
							"instruction": "右 に曲がって 創成川通 に入ります. 267 m 進みます.",
							"offset": 9,
							"direction": "right",
							"severity": "quite"
						},
						{
							"action": "turn",
							"duration": 142,
							"length": 133,
							"instruction": "小さく左 に曲がります. 133 m 進みます.",
							"offset": 12,
							"direction": "left",
							"severity": "light"
						},
						{
							"action": "turn",
							"duration": 444,
							"length": 444,
							"instruction": "左 に曲がって 北2条通 に入ります. 444 m 進みます.",
							"offset": 15,
							"direction": "left",
							"severity": "quite"
						},
						{
							"action": "arrive",
							"duration": 0,
							"length": 0,
							"instruction": "北2条通 に到着しました。.",
							"offset": 23
						}
					],
					"departure": {
						"time": "2022-06-24T18:39:24+09:00",
						"place": {
							"type": "place",
							"location": {
								"lat": 43.0675835,
								"lng": 141.3511245
							},
							"originalLocation": {
								"lat": 43.0684109,
								"lng": 141.3509
							}
						}
					},
					"arrival": {
						"time": "2022-06-24T19:02:38+09:00",
						"place": {
							"type": "place",
							"location": {
								"lat": 43.0646414,
								"lng": 141.3620202
							},
							"originalLocation": {
								"lat": 43.064631,
								"lng": 141.3620229
							}
						}
					},
					"polyline": "BG-r0kyCqtsztI3eyH3BpV1CvEzF5B1HbiLgyCyMuiDqM0lDyDwYzoCyS7xB4MrZ2G5J6FnIgC72BiO2GywBoG4vBoGyuBqH8xBkGqwBiHkxB8BuMsE6gB",
					"language": "ja-jp",
					"transport": {
						"mode": "pedestrian"
					}
				}
			]
		}
	]
}
```
これ、もう自分でナビゲーション作れますよね。。。

<a id="#Chapter4"></a>
# 公式デモサイト

ちなみにHEREのAPIを試すことの出来るWEBサイトがあります

https://demo.routing.ext.here.com/

また、HEREアカウントの認証が必要になりますが、公式のサポートデモがまとまっていいるページもあります
日本の例もかなり充実しています

https://demo.support.here.com/

以上、HEREのRoutingAPIは多機能ですごいという話でした
これが無料で試せるというのだけでも価値があるなと思いました