使い方ガイド
郵便番号APIの使い方。
住所⇄郵便番号を変換する郵便番号APIを、5分で導入するためのチュートリアルです。APIキーの取得から、最初のリクエスト、使う言語への組み込み、逆引き、表記ゆれの扱いまで、順番に進めます。リファレンスの詳細はドキュメントにあります。
Step 1
APIキーを取得する
メールアドレスを入力してStripeで決済すると、その場でAPIキーが表示されます。審査や書類は不要です。
- サインアップでメールアドレスを入力(任意で利用ドメインも登録できます)
- クレジットカードで決済(月額¥1,980・税込)
- 発行されたキーはその場で一度だけ表示。安全な場所に保管してください
まだ契約せずに試したい方へ — トップの検索デモとドキュメントのライブ実行が登録なしで使えます。
Step 2
最初のリクエストを送る
住所から郵便番号を引くには GET /api/v1/search を呼びます。認証は x-api-key ヘッダー。YOUR_KEY を発行したキーに置き換えてください。
curl --get "https://api.example.jp/api/v1/search" \
--data-urlencode "address=東京都千代田区丸の内" \
-H "x-api-key: YOUR_KEY"レスポンスはJSON(UTF-8)。results に候補が入ります。
{
"query": "東京都千代田区丸の内",
"count": 1,
"results": [
{ "zipcode": "100-0005", "prefecture": "東京都", "city": "千代田区", "town": "丸の内", "kana": "トウキョウト チヨダク マルノウチ" }
]
}日本語のエンコードに注意: 住所は必ずURLエンコードしてください。URLに日本語を直書きするとCDNが本文なしの400を返すことがあります。上の
--data-urlencode や各言語のクライアントは自動でエンコードします。Step 3
使う言語で組み込む
住所→郵便番号(/api/v1/search)の呼び出し例です。タブで言語を切り替えられます。
curl --get "https://api.example.jp/api/v1/search" \
--data-urlencode "address=東京都千代田区丸の内" \
-H "x-api-key: YOUR_KEY"const url = new URL("https://api.example.jp/api/v1/search");
url.searchParams.set("address", "東京都千代田区丸の内");
const res = await fetch(url, {
headers: { "x-api-key": "YOUR_KEY" },
});
const data = await res.json();
console.log(data.results);import requests
res = requests.get(
"https://api.example.jp/api/v1/search",
params={"address": "東京都千代田区丸の内"},
headers={"x-api-key": "YOUR_KEY"},
)
res.raise_for_status()
print(res.json()["results"])<?php
$query = http_build_query(["address" => "東京都千代田区丸の内"]);
$ch = curl_init("https://api.example.jp/api/v1/search?$query");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_KEY"]);
$body = curl_exec($ch);
curl_close($ch);
$data = json_decode($body, true);
print_r($data["results"]);require "net/http"
require "json"
require "uri"
uri = URI("https://api.example.jp/api/v1/search")
uri.query = URI.encode_www_form(address: "東京都千代田区丸の内")
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = "YOUR_KEY"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)["results"]package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
)
func main() {
u, _ := url.Parse("https://api.example.jp/api/v1/search")
q := u.Query()
q.Set("address", "東京都千代田区丸の内")
u.RawQuery = q.Encode()
req, _ := http.NewRequest("GET", u.String(), nil)
req.Header.Set("x-api-key", "YOUR_KEY")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var data map[string]any
json.NewDecoder(res.Body).Decode(&data)
fmt.Println(data["results"])
}Step 4
郵便番号から住所を逆引きする
逆引きは GET /api/v1/lookup。パラメータを zipcode に変えるだけです。100-0005 と 1000005 のどちらの形式でも受け付けます。
curl "https://api.example.jp/api/v1/lookup?zipcode=100-0005" \
-H "x-api-key: YOUR_KEY"Tips
番地つき・表記ゆれのある住所を渡す
実データの住所は、番地や建物名がついていたり、表記が少しゆれていたりします。検索時に軽微なゆれを補助するので、町名まで解釈してヒットさせられます。
- 番地・建物名つき(例:
東京都千代田区丸の内1-1-1)でも、町域までを解釈して郵便番号を返します - 全角・半角や軽微な表記ゆれを検索時に補助します
- 候補が複数あるときは
resultsに並びます。limit(1〜50、既定10)で件数を調整できます
期待した候補に絞れないときは、都道府県・市区町村まで含めて渡すと精度が上がります。実際の挙動はライブ実行で試せます。
Errors & Limits
エラーとレート制限の要点
401 unauthorized—x-api-keyが未指定/無効。ヘッダー名とキーを確認400 invalid_parameter— パラメータ不正(住所は最大256文字、郵便番号は厳密形式)429 rate_limited— レート上限超過。上限はx-ratelimit-*ヘッダーで確認できます(300req/分、月間上限なし)
エラー一覧・レスポンス項目・CORSの詳細はドキュメントを参照してください。