Trimix Zipcode Search API — v1 ドキュメント

バージョン: v1（安定版）
ベースURL: https://api.trimix-data.io/v1
最終更新: 2026-06-02

概要

郵便番号から住所一覧を取得するAPIです。日本郵便の公開データ（郵便番号データ）をもとに月次更新し、郵便番号の前方一致で該当する住所を返します。

主なユースケース:

• 申込フォーム・ECの注文画面で郵便番号から住所を自動入力する
• 漢字・カナの両方を取得してふりがな欄を自動補完する
• 郵便番号の上位桁（3〜7桁）で前方一致検索し、該当エリアの住所候補を提示する

対象バージョン情報

認証

すべてのエンドポイントは x-api-key ヘッダーに有効なAPIキーが必要です。

GET /v1/zipcodes/1000001
x-api-key: your_api_key_here

APIキーは Trimixダッシュボード から取得できます。

エンドポイント一覧

GET /v1/zipcodes/{zipcode}

郵便番号（半角数字3〜7桁・ハイフンなし）の前方一致で住所を検索します。該当する住所を最大30件返します。

• 7桁を指定すると、その郵便番号に紐づく住所（複数町域がある場合は複数件）を返します。
• 3〜6桁を指定すると、そのプレフィックスに前方一致する住所を返します。
• 該当する住所がない場合も 200 OK（count: 0・results: []） を返します（404 は使いません）。
• 該当が30件を超える場合は30件に切り詰め、truncated: true を返します。

リクエスト:

GET /v1/zipcodes/1000001
x-api-key: your_api_key_here

レスポンス（200 OK）:

{
  "zipcode": "1000001",
  "count": 1,
  "truncated": false,
  "results": [
    {
      "zip1": "100",
      "zip2": "0001",
      "prefecture": "東京都",
      "prefecture_kana": "トウキョウト",
      "city": "千代田区",
      "city_kana": "チヨダク",
      "town": "千代田",
      "town_kana": "チヨダ",
      "prefecture_code": "13101"
    }
  ]
}

パスパラメータ:

レスポンスフィールド:

エラーカタログ

すべてのエラーレスポンスは RFC 7807 Problem Details 形式（application/problem+json）です。

{
  "type": "https://api.trimix-data.io/errors/<error-code>",
  "title": "エラーの概要",
  "status": 400,
  "detail": "詳細メッセージ",
  "instance": "/v1/zipcodes/100-0001"
}

「該当住所なし」は 404 ではありません。 郵便番号が形式的に正しい限り、結果が0件でも 200 OK（count: 0・results: []）を返します。

コードサンプル

curl

# 7桁で検索
curl -H "x-api-key: your_key" \
  https://api.trimix-data.io/v1/zipcodes/1000001

# 3桁（前方一致）で検索
curl -H "x-api-key: your_key" \
  https://api.trimix-data.io/v1/zipcodes/100

Node.js

const API_KEY = process.env.TRIMIX_API_KEY;
const BASE_URL = 'https://api.trimix-data.io/v1';

const response = await fetch(`${BASE_URL}/zipcodes/1000001`, {
  headers: { 'x-api-key': API_KEY },
});
if (!response.ok) {
  const error = await response.json();
  console.error(error.detail);
}
const { count, results } = await response.json();
for (const addr of results) {
  console.log(`${addr.prefecture}${addr.city}${addr.town}`);
}

Python

import httpx

API_KEY = "your_api_key"
BASE_URL = "https://api.trimix-data.io/v1"

response = httpx.get(
    f"{BASE_URL}/zipcodes/1000001",
    headers={"x-api-key": API_KEY}
)
response.raise_for_status()
data = response.json()
for addr in data["results"]:
    print(f"{addr['prefecture']}{addr['city']}{addr['town']}")

レート制限

レート制限超過時は 429 Too Many Requests + rate-limit-exceeded エラーが返ります。

データ更新サイクル

このAPIのデータは日本郵便「郵便番号データ」の公開データをもとに更新されます。

日本郵便側のデータ配信の遅延・仕様変更等により、取り込みが遅延する場合があります。