prop-id-api

不動産オープン ID 仕様

API 共通仕様

不動産オープン ID のフォーマット

[都道府県コード]-[UUID]

例: 13-xxxx-xxxx-xxxx-xxxx

認証

認証用パラメータ

Name	Type	In	Description
api-key	string	query	API キー
x-access-token	string	header	アクセストークン

リクエスト例

GET /v1/?api-key={api-key}
Host: api.propid.jp:443
X-Access-Token: {access-token}
Content-Type: application/json

不動産オープン ID 取得 API

住所から不動産オープン ID を取得します。有料プラン向けには正規化後の住所や位置情報などもレスポンスに追加されます。

エンドポイント

https://api.propid.jp/v1

リクエスト

[GET] /?api-key={api-key}&q={address}

Name	Type	In	Description
address	string	query	物件の住所

レスポンス

無料プラン

[
  {
    "ID": "xxxx-xxxx-xxxx-xxxx",
    "normalization_level": 0-3,
    "status": null | "addressPending",
    "query": {
      "input": "東京都千代田区永田町1-7-1 xxxビル",
    }
  }
]

• query.input フィールドは、クエリとして入力した住所文字列をそのまま返却します
• query.address.ja フィールドは、クエリ文字列を正規化した結果を返却します

有料プラン

[
  {
    "ID": "xxxx-xxxx-xxxx-xxxx",
    "normalization_level": 0-3,
    "geocoding_level": 1-9,
    "address": {
      "ja": {
        "prefecture": "東京都",
        "city": "千代田区",
        "address1": "永田町一丁目",
        "address2": "7-1",
        "other": "xxx ビル"
      }
    },
    "location": {
      "lat": "緯度",
      "lng": "経度"
    }
  },
  "status": null | "addressPending",
    "query": {
      "input": "東京都千代田区永田町1-7-1 xxxビル",
      "address": {
        "ja": {
          "prefecture": "東京都",
          "city": "千代田区",
          "address1": "永田町一丁目",
          "address2": "7-1",
          "other": "xxxビル"
        }
      }
    }
  }
]

不動産オープン ID 参照 API

不動産オープン ID から物件情報を取得することができます。有料プランでのご提供です。

[GET] https://api.propid.jp/v1/{id}?api-key={api-key}&lang={language}

パラメータ

Name	Type	In	Description
id	string	path	不動産オープン ID
language	string	query	言語コード

レスポンス

[
  {
    "ID": "xxxx-xxxx-xxxx-xxxx",
    "normalization_level": 0-3,
    "geocoding_level": 1-9,
    "address": {
      "ja": {
        "prefecture": "東京都",
        "city": "千代田区",
        "address1": "永田町一丁目",
        "address2": "7-1",
        "other": "xxx ビル"
      }
    },
    "status": null | "addressPending",
    "location": {
      "lat": "緯度",
      "lng": "経度"
    }
  }
]

不動産オープン ID 統合時の仕様

地名変更等で不動産オープン ID が統合された時、レスポンスの ID は統合先の ID を返します。

例

地名変更で、東京府千代田区永田町1丁目7-1（ID: xxxx-xxxx-xxxx-xxxx）が、東京都千代田区永田町1丁目7-2（ID: zzzz-zzzz-zzzz-zzzz）に統合。

レスポンス

[
  {
    "ID": "zzzz-zzzz-zzzz-zzzz",
    ...
  }
]

解析レベル

不動産オープン ID 取得 API 及び、不動産オープン ID 参照 API のレスポンスは、住所の解析レベル情報を含みます。 無料版では normalization_level のみ、有料版ではより詳細な解析レベルの geocoding_level も含みます。

normalization_level

解析レベル	解析レベルの数字	エラー時の値	説明
解析できません	0	prefecture_not_recognized	都道府県も判別できなかった
都道府県	1	city_not_recognized	都道府県まで判別できた
市区町村	2	neighborhood_not_recognized	市区町村まで判別できた
町丁目	3		町丁目まで判別できた
番地	7		号が存在しない無い場合、番地まで判別できた (geocoding_levelが5以下の場合)
番地・号	8		番地・号まで判別できた (geocoding_levelが5以下の場合)

geocoding_level

解析レベル	レベルの数字	エラー時の値	説明
都道府県	1	geo_prefecture	県レベルでマッチしました
市区町村	2	geo_city	市区町村レベルでマッチしました
町域 (大字)	3	geo_oaza	町域レベルでマッチしました
丁目 / 小字	4	geo_koaza	丁目または小字レベルでマッチしました
番地（番）	5	geo_banchi	番地（番）レベルでマッチしました
号情報が存在しない番地	7	geo_ok_no_go	番地（番）レベルでマッチしました（号情報が存在しない地域）
号	8	geo_ok_go	号レベルでマッチしました
不明	-1	geo_undefined	不明

レート制限

各APIは現在のレート制限状況を確認できる、レスポンスヘッダーを返します。制限を超えた場合はこのヘッダーを確認して、いつ再試行できるかを判断できます。

$ curl -D /dev/stderr -G -H "x-access-token: <アクセストークン>" --data-urlencode "q=東京都千代田区永田町1-7-1" --data-urlencode "api-key=<API キー>" "https://api.propid.jp/v1/"
> x-ratelimit-limit: 10000
> x-ratelimit-remaining: 9938
> x-ratelimit-reset: 2021-06-01T00:00:00.000+09:00

ヘッダー名	説明
x-ratelimit-limit	一ヶ月当たりのリクエスト上限回数
x-ratelimit-remaining	リクエスト残数
x-ratelimit-reset	次にレート制限がリセットされる予定時刻 (JST ISO8601形式)

エラー

不動産オープン ID 取得 API 及び、不動産オープン ID 参照 API がリクエストの処理に成功すると、API はステータスコード「200」を返します。リクエストでエラーが発生すると、エラーの種類に基づいて HTTP ステータスコード、理由を含むレスポンスが API から返されます。 レスポンスの本文には、エラーの原因についての詳しい説明が記述されています。

標準エラーレスポンス

ステータス	説明	メッセージ
403	Forbidden	{"message":"Incorrect querystring parameter `api-key` or `x-access-token` header value."}
429	Too Many Requests	{"message":"Exceed requests limit."}

不動産オープン ID 取得 API

住所の正規化に失敗した場合、 { "error_code":"normalization_failed" } のと共に error_code_detail としてその理由を示す解析レベルの情報が返却されます。解析レベルは、 normalization_level または geocoding_level を示す文字列が返却されます。

ステータス	説明	メッセージ
400	Bad Request	※ パラメーター q が存在しない、または空白文字列の場合 {"message":"Missing querystring parameter `q`."}
400	Bad Request	※ パラメーター q に使用できない文字が含まれている場合 {"message": "The parameter `q` contains an invalid character '/'."}
400	Bad Request	※ 都道府県名が正規化できなかったケース { "error": true, "error_code": "normalization_failed", "error_code_detail": "prefecture_not_recognized", "address": "あああ県" }
400	Bad Request	※ 市区町村が正規化できなかったケース { "error": true, "error_code": "normalization_failed", "error_code_detail": "city_not_recognized", "address": "東京都" }
400	Bad Request	※ 町丁目が正規化できなかったケース { "error": true, "error_code": "normalization_failed", "error_code_detail": "neighborhood_not_recognized", "address": "東京都文京区" }
400	Bad Request	※ 町丁目までの住所の正規化に成功したが、番地・号が識別できなかったケース { "error": true, "error_code": "normalization_failed", "error_code_detail": "geo_koaza", "address": "東京都文京区千石4丁目" }

不動産オープン ID 参照 API

ステータス	説明	メッセージ
404	Not Found	{"error":true,"error_description":"not_found"}