what3words APIを使ってみる #Ruby

whats3wordsのAPIを使ってみます.

そもそも, what3wordsとは
Wikipediaより

what3words（ホワットスリーワーズ）は、3メートルの解像度で場所を伝達するためのジオコーディングシステムである。what3wordsでは、地理的座標を3つの単語で符号化する。例えば、自由の女神像の持つ松明の位置は、"toned.melt.ship"の3語で表している。従来のほかの位置エンコードシステムとの違いは、長い文字(たとえば住所)や数字(たとえば経緯度)ではなく、3つの単語で簡単に表される点にある。what3wordsは、ウェブサイトやiOS、Androidのアプリ、 APIで利用でき、what3wordsのアドレスは緯度-経度座標と双方向に変換することができる。特定のアルゴリズムに依存したシステムではなく、地球上のあらゆる場所の巨大なデータベースも必要ないので、インターネットに接続せずとも容量に制限のあるデバイスで動作させることができる、さらに、その符号化は、恒久的に固定で、変わらないものとなる。

簡単にまとめると, 世界中の住所を3単語で表現するシステムです.

API 使用手順

ライセンスキーを発行(https://accounts.what3words.com/register/)
- アカウント作成
- Create your first application
- アプリケーション名と説明を記入し, 作成
- Create applicationキーを押すと, アプリケーションが作成され, APIKEYが取得できます.
APIを使用するためのリクエストURL

3 words address => coordinate (Forward Geocoding)
- 3 wordsから緯度経度情報に変換します.

https://api.what3words.com/v2/forward?addr=index.home.raft&key=MY-API-KEY

Coordinate => 3 word address (Reverse Geocoding)
- 緯度経度情報から3 wordsに変更します.

https://api.what3words.com/v2/reverse?coords=51.521251%2C-0.203586&key=MY-API-KEY

テストするには, Postmanがおすすめです.
Postmanでの実行結果

注意点

HTTPS GETメソッドのみ
リクエストURLにAPIKEYを入れる key=api-key
もしくは, リクエストヘッダーに入れるX-Api-Key: [API-KEY
CORSをサポートしています.

Forward Geocoding ( 3 words address => coordinate )

リソースURL https://api.what3words.com/v2/forward

リクエスト例

require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v2/forward?addr=index.home.raft&key=MY-API-KEY&lang=en&format=json&display=full")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

リクエスト結果(JSON)

{
    "crs": {
        "properties": {
            "type": "ogcwkt",
            "href": "http://spatialreference.org/ref/epsg/4326/ogcwkt/"
        },
        "type": "link"
    },
    "bounds": {
        "southwest": {
            "lng": -0.203607,
            "lat": 51.521238
        },
        "northeast": {
            "lng": -0.203564,
            "lat": 51.521265
        }
    },
    "words": "index.home.raft",
    "map": "http://w3w.co/index.home.raft",
    "language": "en",
    "geometry": {
        "lng": -0.203586,
        "lat": 51.521251
    },
    "status": {
        "code": 200,
        "message": "OK"
    },
    "thanks": "Thanks from all of us at index.home.raft for using a what3words API"
}

Reverse Geocoding ( Coordinate => 3 word address )

リソースURL https://api.what3words.com/v2/reverse

リクエスト例

require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v2/reverse?coords=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&format=json&display=full")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

リクエスト結果(JSON)

{
    "crs": {
        "type": "link",
        "properties": {
            "href": "http://spatialreference.org/ref/epsg/4326/ogcwkt/",
            "type": "ogcwkt"
        }
    },
    "words": "index.home.raft",
    "bounds": {
        "southwest": {
            "lng": -0.203607,
            "lat": 51.521238
        },
        "northeast": {
            "lng": -0.203564,
            "lat": 51.521265
        }
    },
    "geometry": {
        "lng": -0.203586,
        "lat": 51.521251
    },
    "language": "en",
    "map": "http://w3w.co/index.home.raft",
    "status": {
        "code": 200,
        "message": "OK"
    },
    "thanks": "Thanks from all of us at index.home.raft for using a what3words API"
}

その他機能

この記事ではまとめませんが, 他にも以下のような機能があります.

AutoSuggest
- 与えられたパラメータから, 推測される3×3エリアの候補を返します.
Voice AutoSuggest
- 音声による入力から, 推測される3×3エリアの候補を返します.
StandardBlend
- 完全もしくは部分的な3wordsから, 関連性のある3words候補を返します.
Voice StandardBlend
- 音声による入力の完全もしくは部分的な3wordsから, 関連性のある3words候補を返します.
Grid
- パラメータとして与えられたエリアの3×3の情報を返します.
Get Languages
- 現在3wordsで使用可能な言語を返します.

おわりに

次回は, iOS(swift)からwhat3wordsAPIを使用する方法についてまとめます.