pyreinfolib

国土交通省不動産情報ライブラリAPIサービスのPythonクライアントです。対応しているAPIはEndpointsにあります。

API仕様の詳細はAPI操作説明ページをご参照ください。APIキーはAPI利用申請で取得します。

Installation

pip install pyreinfolib

Quick start

import os

from pyreinfolib import Client

client = Client(api_key=os.environ["REINFOLIB_API_KEY"])

# 2024年第1四半期、渋谷区の不動産取引価格
result = client.get_real_estate_prices(year=2024, quarter=1, city="13113")

for record in result["data"]:
    print(record["Type"], record["TradePrice"], record["Area"])

APIの多くは地図のタイル座標を指定して取得します。緯度経度からの変換は pyreinfolib.tiles が行います。

from pyreinfolib import tiles

tile = tiles.containing(lon=139.7016, lat=35.6580, z=15)

for feature in client.get_use_districts(*tile)["features"]:
    print(feature["properties"]["use_area_ja"])

Endpoints

都道府県・市区町村コードで取得するAPI

タイル座標で取得するAPI

z, x, y は必須です。それ以外の引数はすべて任意で、省略するとタイル全体が返ります。

各メソッドの docstring に、引数の形式とコード表へのリンクがあります。

Tile coordinates

点を含むタイルの取得 (containing)

from pyreinfolib import tiles

tile = tiles.containing(lon=139.7016, lat=35.6580, z=15)
# Tile(z=15, x=29099, y=12905)

client.get_number_of_passengers_per_station(*tile)

Tile は z, x, y の順なので、タイル系メソッドにそのまま展開して渡せます。

引数は名前を付けて渡します（位置引数では渡せません）。緯度と経度はどちらも float なので、順序を取り違えても型では気づけないためです。

受け付けるズームレベルはエンドポイントごとに違います。上の表の「ズーム」列を見てください。範囲外を渡すと、どのエンドポイントが何を期待しているかを含む ValueError になります。

指定範囲を覆うタイルの取得 (covering / count_covering)

box = {"west": 139.665, "south": 35.640, "east": 139.724, "north": 35.679}

print(tiles.count_covering(**box, z=15))  # 30

for tile in tiles.covering(**box, z=15):
    client.get_real_estate_prices_point(*tile, period_from=20241, period_to=20242)

ズーム15ではタイル1枚が約1km四方です。1タイルが1リクエストになるので、着手前に count_covering() で枚数を確認してください。引数は covering() と同じです。

タイル範囲の取得 (bounds)

tiles.bounds(tile)
# Bounds(west=139.691162109375, south=35.65729624809628, east=139.7021484375, north=35.66622234103478)

Bounds は GeoJSON の bbox と同じ west, south, east, north の順です。

Filtering

コードでの絞り込み

コードを取る引数は、1つでもリストでも渡せます。

client.get_elementary_school_districts(z=11, x=1819, y=806, administrative_area_code="13102")
client.get_elementary_school_districts(z=11, x=1819, y=806, administrative_area_code=["01101", "13102"])

price_classification、division、land_type_code、use_category_code は pyreinfolib.enums の enum を渡します。

from pyreinfolib.enums import LandTypeCode, PriceClassification

client.get_real_estate_prices_point(
    z=15,
    x=29099,
    y=12905,
    period_from=20241,
    period_to=20242,
    price_classification=PriceClassification.CONTRACT_PRICE,
    land_type_code=[LandTypeCode.LAND, LandTypeCode.LAND_AND_BUILDING],
)

price_classification は API 上どちらも同じ名前ですが、コード体系が2つに分かれています。別の型にしてあるので取り違えは型チェックで検出されます。

それ以外のコードは str です。福祉施設の3階層（大分類、中分類、小分類）と、災害履歴の災害分類コードがこれに当たります。

client.get_welfare_facilities(
    z=13,
    x=7312,
    y=3008,
    welfare_facility_class_code=["02", "05"],  # 老人福祉施設、児童福祉施設等
)

client.get_disaster_history(z=9, x=227, y=100, disastertype_code=["11", "22"])

災害分類コードは独立したコード表がないので、XST001 のマニュアルページか get_disaster_history の docstring を見てください。

都道府県コードの形式

prefecture_code の形式はエンドポイントごとに決まっています。

引数名も型も同じなので、渡す値からは区別が付きません。XKT019 に "09" を渡すと ValueError になりますが、XKT021 と XKT022 に "9" を渡した場合は空のタイルが返り、該当データがないタイルと見分けが付きません。

引数の省略

引数を省略するか None を渡すと、その絞り込みを行いません。get_real_estate_prices(year=2024) は全国が対象になります。

空文字は省略と同じ扱いになりません。 ValueError になります。フォームや環境変数の値をそのまま渡す場合は city=value or None としてください。コードのリストが空（land_type_code=[]）の場合も ValueError です。絞り込んだつもりで全件が返るのを防ぐためです。

Client configuration

Client はコネクションを再利用します。タイル系APIを複数タイル分呼ぶ使い方では、TLSハンドシェイクが1回で済みます。使い終わったら close() するか、with を使ってください。

with Client(api_key=os.environ["REINFOLIB_API_KEY"]) as client:
    client.get_municipalities(area="13")

リトライ

スロットリング（HTTP 429）と一時的なサーバエラー（500、502、503、504）は自動で再試行します。APIはリクエスト数の上限を公開しておらず、間隔を空けて実行するよう案内しているため、429 は障害ではなく想定される応答です。

待ち時間は指数的に伸びます。既定の max_retries=3 では 0秒、2秒、4秒の順に待ち、4回目で諦めて RateLimitError を送出します。APIが Retry-After を返した場合はそちらが優先されます。

# 再試行しない
client = Client(api_key=..., max_retries=0)

検索結果0件（HTTP 404）は再試行しません。timeout は各試行を制限するもので、再試行の全体を制限するものではありません。

Error handling

このライブラリが送出する例外はすべて ReinfolibError を継承しています。requests を import せずに捕捉できます。

ReinfolibError
├── TransportError          レスポンスを得られなかった（接続失敗・タイムアウト）
└── APIError                レスポンスは返ったが利用できない（status_code / response_body / url を持つ）
    ├── AuthenticationError APIキーが未指定または拒否された（401）
    ├── NoResultsError      検索結果が0件（404）
    ├── RateLimitError      同一APIキーからのリクエストが多すぎる（429）
    └── InvalidResponseError レスポンスがJSONではなかった

結果が0件の場合

都道府県・市区町村コードで取得するAPIは、条件に合致するデータが無い場合に空の結果ではなく HTTP 404 を返します（API操作説明の3章 Q.8）。NoResultsError として送出します。

from pyreinfolib import NoResultsError

try:
    prices = client.get_real_estate_prices(year=2024, city="13109")
except NoResultsError:
    prices = {"status": "OK", "data": []}

タイル座標で取得するAPIは0件でも200と空のフィーチャ一覧を返すため、NoResultsError は発生しません。

APIError の中身

from pyreinfolib import APIError

try:
    client.get_municipalities(area="99")
except APIError as e:
    print(e.status_code, e.response_body, e.url)

Typing

型情報を同梱しています（PEP 561）。返り値の形は pyreinfolib.types に TypedDict で置いてあるので、キーの綴り間違いが型エラーになります。

prices = client.get_real_estate_prices(year=2024, city="13109")

for record in prices["data"]:
    print(record["TradePrice"])
    print(record["TradePirce"])  # 型エラー

型名はメソッド名から機械的に決まります。変数や自作関数に型注釈を付けるときに使ってください。

from pyreinfolib.types import RealEstatePricesItem, UseDistrictsResponse


def total(records: list[RealEstatePricesItem]) -> int:
    return sum(int(r["TradePrice"]) for r in records)


districts: UseDistrictsResponse = client.get_use_districts(z=15, x=29099, y=12905)

型を読むときの注意

キーと値の型は API のマニュアル通りです。 整えていないので、国土数値情報の属性コード（A27_001）、ローマ字（kubun_id）、_ja 接尾辞、XCT001 の日本語キー（全角スペース入り）、XPT002 の proximity_to_transportation_facilitites（API 側の綴り間違い）がそのまま出てきます。

値の型もマニュアルの宣言通りです。XIT001 は取引価格を含めて全フィールドが文字列型なので、record["TradePrice"] は str です。

どのキーが必ず来るかはマニュアルに記載がないため、全フィールドを省略可能として扱っています。 読み取りは型チェックを通りますが、実行時に KeyError の可能性は残ります。

geometry は6種のジオメトリの合併型です。type で絞り込んでから coordinates を読みます。

for feature in client.get_schools(z=13, x=7269, y=3235)["features"]:
    geometry = feature["geometry"]
    if geometry is not None and geometry["type"] == "Point":
        lon, lat = geometry["coordinates"][0], geometry["coordinates"][1]

get_population_projections_in_250m_grid_squares（XKT013）だけは properties が dict[str, Any] です。PT01_20XX のようにフィールド名が年を含み、マニュアルがその年をプレースホルダで書いているためです。

[!NOTE] 0.6.0 以前は全メソッドが dict[str, Any] を返していました。返り値を dict[str, Any] と型注釈していた場合、TypedDict は dict[str, Any] に代入できないため型チェックが落ちます。型注釈を外すか、対応する ...Response に差し替えてください。実行時の挙動は変わりません。

Contributing

CONTRIBUTING.md に開発環境と命名規則、GLOSSARY.md に訳語と典拠があります。

Author

@matsudan (daaamatsun@gmail.com)