Python×HeartRails Geo APIで都道府県や駅名の地理情報をサクッと取得する方法

PythonでWebスクレイピングやアプリ開発をしていると、「全国の都道府県一覧が欲しい」「郵便番号から住所を検索したい」「現在地の最寄り駅を表示したい」といった場面に遭遇することがありますよね。

しかし、地理情報APIの多くはユーザー登録やAPIキーの発行が必要で、少し面倒に感じることも多いはず。

そこで今回は、面倒な登録やAPIキーが一切不要で、今すぐ無料で使える超便利API「HeartRails Geo API」をPythonから活用する方法をご紹介します！

HeartRails Geo APIとは？

HeartRails Geo APIは、日本全国の町域、郵便番号、駅などの地理情報データをXMLやJSON形式で取得できる無料のAPIサービスです。

最大のメリットは「登録不要・APIキー不要」であること。

思い立った瞬間にコードを書いてデータを取得できるため、ハッカソンやプロトタイプ開発、個人の学習用として非常に重宝します。

事前準備

今回はPythonからAPIを叩くために、標準ライブラリよりも扱いやすい requests ライブラリを使用します。

まだインストールしていない方は、ターミナル（コマンドプロンプト）で以下のコマンドを実行しておきましょう。

pip install requests

準備はこれだけです。さっそくコードを書いていきましょう！

実践1：全国の「都道府県」一覧を取得しよう

まずは一番シンプルなAPI呼び出しから。全国の都道府県リストを取得してみます。

import requests

def get_prefectures():
    url = "http://geoapi.heartrails.com/api/json"
    params = {
        "method": "getPrefectures"
    }

    # APIにリクエストを送信
    response = requests.get(url, params=params)
    data = response.json()

    # JSONデータから都道府県リストを抽出
    prefectures = data["response"]["prefecture"]

    print(f"取得した都道府県の数: {len(prefectures)}")
    print(prefectures) 

if __name__ == "__main__":
    get_prefectures()

【解説】
APIのエンドポイントURLに、パラメータとして method=getPrefectures を渡すだけです。

戻り値はJSON形式なので、response.json() でPythonの辞書型に変換し、必要なデータだけを取り出しています。

実践2：指定した都道府県の「市区町村」一覧を取得しよう

次は、「東京都」や「大阪府」など、特定の都道府県を指定して、その中に含まれる市区町村のデータを取得してみましょう。

import requests

def get_cities(prefecture_name):
    url = "http://geoapi.heartrails.com/api/json"
    params = {
        "method": "getCities",
        "prefecture": prefecture_name
    }

    response = requests.get(url, params=params)
    data = response.json()

    # エラーチェック（存在しない都道府県を入力した場合など）
    if "error" in data["response"]:
        print(f"エラー: {data['response']['error']}")
        return

    # 市区町村データを抽出
    locations = data["response"]["location"]

    print(f"【{prefecture_name}の市区町村一覧】")
    for loc in locations:
        city = loc["city"]
        city_kana = loc["city_kana"]
        print(f"・{city} ({city_kana})")

if __name__ == "__main__":
    get_cities("東京都")

【解説】
日本語（「東京都」など）をURLに含める場合、通常はURLエンコードが必要ですが、requestsライブラリを使えば params に渡すだけで自動的に処理してくれます。

ふりがな（city_kana）も一緒に取得できるのが地味に嬉しいポイントですね！

実践3：緯度・経度から周辺の「最寄り駅」を検索しよう

最後に、スマホのGPSデータなどと連携する際によく使う「座標からの最寄り駅検索」をやってみます。

今回は例として、東京駅付近（経度139.7670, 緯度35.6811）の座標を指定してみます。

import requests

def get_nearby_stations(longitude, latitude):
    url = "http://geoapi.heartrails.com/api/json"
    params = {
        "method": "getStations",
        "x": longitude, # 経度
        "y": latitude   # 緯度
    }

    response = requests.get(url, params=params)
    data = response.json()

    if "error" in data["response"]:
        print(f"エラー: {data['response']['error']}")
        return

    stations = data["response"]["station"]

    print(f"【指定座標周辺の駅】")
    for station in stations:
        name = station["name"]
        line = station["line"]
        distance = station["distance"] # 指定座標からの距離(m)
        print(f"駅名: {name}駅 | 路線: {line} | 距離: {distance}m")

if __name__ == "__main__":
    # 東京駅周辺の緯度経度を指定
    get_nearby_stations(139.7670, 35.6811)

【実行結果のイメージ】

【指定座標周辺の駅】
駅名: 東京駅 | 路線: JR山手線 | 距離: 10m
駅名: 大手町駅 | 路線: 東京メトロ丸ノ内線 | 距離: 450m
...

このように、指定した座標から近い順に、駅名・路線名・距離（メートル）が取得できます。お出かけアプリや不動産情報のスクレイピングなどに応用できそうですね！

APIを利用する際のマナーと注意点

非常に便利なHeartRails Geo APIですが、利用する際は以下の点に注意しましょう。

1. エラーハンドリングを必ず入れる
   パラメータを間違えた場合でも、システムエラーにならずJSONの中にエラーメッセージ（{"error": "..."}）が含まれて返ってきます。
   
   コード内でエラー判定を行うようにしましょう。
   
2. サーバーに負荷をかけない（アクセス間隔を空ける）
   無料・登録不要で提供してくださっている素晴らしいサービスです。
   
   もしプログラムのループ処理で大量のデータを連続して取得する場合は、必ず time.sleep(1) などを入れて、1秒以上の待機時間を設けるのがAPI利用の最低限のマナーです。

まとめ

今回は「HeartRails Geo API」とPythonの requests ライブラリを使って、地理情報を簡単に取得する方法をご紹介しました。

他にも「郵便番号から住所を取得する」「特定の路線の駅一覧を取得する」など、様々なメソッド（機能）が用意されています。

気になった方はぜひ公式ドキュメントをチェックして、ご自身のアプリ開発や業務効率化に役立ててみてください！

この記事が役に立った！という方は、ぜひシェアをお願いします。

それでは、良いPythonライフを！

本ブログ「ゴマフリーダムのPython教室」のトップページへは以下へアクセス！