Open Street Map の Nominatim APIのカスタムコネクタを作成してみた💎

Open Street Mapとは
- Nominatim API とは
必要なもの
Open Street Map Nominatim APIを把握する
カスタムコネクタを作成する
5.動作確認してみる
参考にした情報
改善したいこと
さいごに

Open Street Mapとは

OpenStreetMap (OSM) は、誰でも自由に地図を使えるよう、みんなでオープンデータの地理情報を作るプロジェクトです。このプロジェクトでは、誰でも自由に参加して地図を編集し、利用することができます。

www.openstreetmap.org

Nominatim API とは

Nominatim APIは、そんなOpenStreetMap (OSM) のデータを利用して、場所を名前や住所で検索するためのジオコーディングAPIです。

今回はNomination API を使ってPowerPlatformのカスタムコネクタで下記を利用できるようにしてみました。

ジオコーディング(地名や住所から地図上の位置を取得)
逆ジオコーディング(緯度経度から住所を取得)

必要なもの

Power Automate / Power Apps のPremium ライセンス
- カスタムコネクタはMicrosoft365付属のPower Automate, Power Appsでは利用できません。Power Automate, Power Apps のPremium ライセンスなどが必要になります。

Open Street Map Nominatim APIを把握する

Nominatim API は利用リポリシーが定められています。誰でも自由に利用することはできますが利用ポリシーを守って利用をしましょう。

operations.osmfoundation.org

カスタムコネクタ化する上で必要な情報を調べる

API ドキュメントを確認し仕様を把握します。

認証
- なし
- Nominatim APIは認証がありません。
httpメソッドはすべてGET
Search
- ```
https://nominatim.openstreetmap.org/search?<params>
```
- キーワード検索のFree-form query と住所で検索するStructured queryがありますが、今回はFree-form queryのみ対応させます

Reverse

https://nominatim.openstreetmap.org/reverse?lat=<value>&lon=<value>&<params>

カスタムコネクタを作成する

個人的に使い慣れたPower Automateから作成していきます。

Power Automateにアクセスしたら「詳細」→「すべて検出」

「データ」カテゴリの中に「カスタムコネクタ」があります。

名前の横にある📌をクリックして色を反転させておくと左のメニューに表示されアクセスしやすくなります。

「カスタムコネクタ」ページにアクセスしたらページ右上の「カスタムコネクタの新規作成」→「一から作成」をクリックします。

カスタムコネクタの名前を入力して続行します。

※名前には設定できないキーワードがあります。

名前を設定して続行するとこのようなカスタムコネクタウィザードが表示されますので、順番に設定を行っていきます。

1.全般

アイコン・アイコンの背景色・説明などはお好みでいい感じのものを設定します。

スキーマ
- HTTPS
ホスト
- nominatim.openstreetmap.org
ベースURL
- /

2.セキュリティ

今回のNominatim APIは認証がありませんので設定不要です。

3.定義-「ジオコーディング(Serach_Freeform)」アクション

「新しいアクション」をクリックして進めます。

3-1.定義-「全般」の設定

Power Automate等でコネクタを使用する際に表示される動作を定義します。

概要
- ジオコーディング
説明
- テキストの説明から場所・住所を検索する
操作ID
- SearchFreeForm
- ※内部的な識別に使われるIDです。先頭は大文字で
表示
- important
- この設定はアクションのパラメータ設定の際の表示形式になります
  - important：既定で表示されます
  - advanced：既定では表示されず「詳細オプション」扱いになります
  - internal：ユーザーには表示されません

3-2.「要求」の設定

「サンプルをインポート」をクリックして設定を進めます。

このようなインポートダイアログが表示されます。

ここを設定するためには、Nominatim API のリファレンスページを参照して進めていきます。

nominatim.org

エンドポイントURLを参考に利用したいパラメータを"format={format}"の形式で追記してきます。今回はこのような形式で作りました。

https://nominatim.openstreetmap.org/search?q={q}&format={format}&limit={limit}&addressdetails={addressdetails}&extratags={extratags}&namedetails={namedetails}&accept-language={accept-language}&countrycodes={countrycodes}

※今回のsearchのクエリパラメータは、自由形式のクエリと構造化クエリの２種類がサポートされています。今回は自由形式のクエリの指定で作成します。

※APIリファレンスにはemailパラメータがあり「多数のリクエストを行う場合は、適切な電子メールを含めてください」と記載があります。

利用ポリシーを確認しつつ該当しそうな場合はemailパラメータの負荷も推奨します。

このリファレンスページの説明を参考に、下記のように設定します。

動詞
- GET

URL

https://nominatim.openstreetmap.org/search?q={q}&format={format}&limit={limit}&addressdetails={addressdetails}&extratags={extratags}&namedetails={namedetails}&accept-language={accept-language}&countrycodes={countrycodes}

このように設定して「インポート」をクリックします。

要求の表示がこのように変わります。

クエリのパラメータを1つ1つ編集して設定を行います。

[q]

検索クエリを入力するパラメータです。

次の3か所を設定します。

概要
- 検索クエリ
必須
- はい
表示
- important

設定したら上部の「←戻る」をクリックし元のページに戻ります。

[format]

API応答フォーマットを指定します。カスタムコネクタで利用する場合はjson形式で出力する必要がありますので、xml形式は使用しません。

概要
- 出力形式
既定値
- jsonv2
必須
- はい
表示
- advanced
ドロップダウンの種類
- 静的
値
- "xml", "json", "jsonv2", "geojson", "geocodejson"

[limit]
APIの応答で返す件数の上限を設定します。

説明
- 返される結果の最大数を制限します。最大40
概要
- 制限
既定値
- 10
必須
- いいえ
表示
- advanced
種類
- integer

[addressdetails]

1を設定すると応答に住所の詳細を含まれます。

説明
- 1 に設定するとアドレスの要素への内訳が含まれます
概要
- アドレス詳細
既定値
- 0
必須
- いいえ
種類
- integer
値
- 0,1

[extratags]

1を設定するとWikipediaのリンクや営業時間などの情報が出力されます（データが登録されている場合）

説明
- 1 に設定するとウィキペディアのリンク・営業時間などの追加情報ガ出力される
概要
- エクストラタグ
既定値
- 0
必須
- いいえ
表示
- advanced
種類
- integer
値
- 0,1

[namedetails]

1に設定すると名前の詳細な情報(言語ごとの表記、古い名前など)が出力されます。

説明
- 1 に設定すると結果の名前の完全なリストが含まれる。(言語のバリエーション、古い名前、参照、ブランド)
概要
- 名前の詳細
既定値
- 0
必須
- いいえ
表示
- advanced
種類
- integer
値
- 0,1

[accept-language]

検索結果を表示する際の優先言語の順序。これは、次のいずれかです言語コードの単純なコンマ区切りリスト、または同じ形式の言語コードのリストを "Accept-Language" HTTP ヘッダーとして使用します。

説明
- 検索結果を表示する際の優先言語の順序
概要
- 表示言語の優先順序
既定値
- ja-JP,en-US
必須
- いいえ
表示
- advanced

[countrycodes]

検索結果を国コードで制限します。

説明
- 国コード(ISO 3166-1alpha2)で指定
概要
- 検索結果を国で制限
既定値
- jp
必須
- いいえ
表示
- advanced

ここまでで要求の設定はひとまず完了です。

ここが緑色のチェックに変わっていればひとまず問題ありません。

3-3.「要求」の動作確認

この状態でいったんコネクタを作成し、動作を確認してみます。
画面右上の「コネクタの作成」をクリックします。

作成に成功したら「6.テスト」をクリックします。

テストするためにはコネクタの接続が必要です。「新しい接続」をクリックします。

作成が完了するとこのように接続が選択された状態になります。

プロンプトを入力して「テスト操作」をクリックしてみます。

q
- 富士山

正常に応答が返ってきた場合は「状態(200)」となります。富士山の情報が応答として返っていることが確認できます。

ここまで動作してしまえばほぼ完成です。アクションの出力の本文がJSONとして返される形で動作しますので、このまま使うこともできます。

3-4.定義-「応答」の設定

最後に応答の設定を行い、APIの応答を動的な値として表示されるように設定します。

まず、テスト実行した応答のボディの値をメモ帳などにコピーしておきます。

「3.定義」をクリックします。

応答-defaultをクリックします。

「サンプルからのインポート」をクリックします。

インポートダイアログが表示されます。

ここに先ほどのテスト実行の応答のボディを張り付けて「インポート」をクリックします。

すると本文の箇所が変化します。

※今回はaddressdetails,namedetails,extratags を1に設定して追加される値まではカバーしていません。

最後に「コネクタを更新」します。これで作成完了です。

4.定義-「逆ジオコーディング(Reverse)」アクション

手順は3と同じなのでこちらは省略気味にまとめます。

4-1.「全般」の設定

概要
- 逆ジオコーディング
説明
- 逆ジオコーディング:緯度・経度から
操作ID
- Reverse
表示
- important

4-2.「要求」の設定

APIリファレンスページからURLを組み立てます。

nominatim.org

https://nominatim.openstreetmap.org/reverse?lat=<lat>&lon=<lon>&format={format}&addresdetails={addresdetails}&format={format}&addressdetails={addressdetails}&extratags={extratags}&namedetails={namedetails}&accept-language={accept-language}&countrycodes={countrycodes}&zoom={zoom}

これをインポートして設定します。