郵便番号データダウンロードAPI リファレンス

このAPIを使うべきケースこの見出しへのリンク

エンドポイント一覧この見出しへのリンク

共通仕様この見出しへのリンク

GET /v1/download/postalcode/ (ファイル一覧)この見出しへのリンク

ダウンロード可能なファイルパスの一覧を取得します。

リソースURLこの見出しへのリンク

https://api.kenall.jp/v1/download/postalcode/

パラメータこの見出しへのリンク

なし

curl サンプルこの見出しへのリンク

curl -H "Authorization: Token YOUR_SECRET_API_KEY" \
  https://api.kenall.jp/v1/download/postalcode/

レスポンス例この見出しへのリンク

{
  "json": [
    "latest/kenall.json.xz",
    "2026-04-01/kenall.json.xz",
    "2026-03-01/kenall.json.xz",
    "2026-02-01/kenall.json.xz",
    "2021-06-30/kenall.json.xz"
  ]
}

レスポンスフィールドこの見出しへのリンク

ダウンロードファイルパスの形式この見出しへのリンク

ダウンロードファイルパスは {バージョン}/{ファイル名} というフォーマットで構成されています。バージョン latest は特殊なバージョン表記で、一覧内の最新のバージョンを参照します。

GET /v1/download/postalcode/{ファイルパス}(DL URL発行)この見出しへのリンク

指定ファイルの一時ダウンロードURLを発行します。HTTP 303 リダイレクトで、Location ヘッダにダウンロードURLが返ります。

リソースURLこの見出しへのリンク

https://api.kenall.jp/v1/download/postalcode/{ファイルパス}

パスパラメータこの見出しへのリンク

curl サンプル (リダイレクトを自動追跡)この見出しへのリンク

curl -L -H "Authorization: Token YOUR_SECRET_API_KEY" \
  https://api.kenall.jp/v1/download/postalcode/latest/kenall.json.xz \
  -o kenall.json.xz

-L オプションで 303 リダイレクトを自動追跡。-o でファイル保存先指定。

リダイレクト動作この見出しへのリンク

ダウンロードファイルの中身この見出しへのリンク

HTTPステータス・エラーこの見出しへのリンク

SDK で呼び出すこの見出しへのリンク

Python (毎月バッチ用サンプル)この見出しへのリンク

import os, lzma, json, requests
 
SECRET = os.environ["KENALL_SECRET_KEY"]
HEADERS = {"Authorization": f"Token {SECRET}"}
 
# 1. 最新ファイルのリダイレクトURLを取得し、ダウンロード保存
res = requests.get(
    "https://api.kenall.jp/v1/download/postalcode/latest/kenall.json.xz",
    headers=HEADERS, allow_redirects=True, timeout=60,
)
res.raise_for_status()
with open("kenall.json.xz", "wb") as f:
    f.write(res.content)
 
# 2. 展開してメモリに読み込み
with lzma.open("kenall.json.xz", "rt", encoding="utf-8") as f:
    data = json.load(f)
 
print(f"version: {data['version']}, records: {len(data['data'])}")

シェルスクリプト (cron 用)この見出しへのリンク

#!/usr/bin/env bash
set -euo pipefail
TOKEN="${KENALL_SECRET_KEY:?}"
DEST="${1:-./kenall.json.xz}"
curl -fSsL -H "Authorization: Token $TOKEN" \
  "https://api.kenall.jp/v1/download/postalcode/latest/kenall.json.xz" \
  -o "$DEST"
echo "Downloaded: $(du -h "$DEST" | cut -f1)"

注意事項・制限事項この見出しへのリンク

シークレットキー専用この見出しへのリンク

公開キーでは 401 が返ります。 シークレットキーはサーバサイドに保管し、フロントエンドJSには絶対に埋め込まないでください。漏洩した場合はダッシュボードから即時ローテーションしてください。

ダウンロードURLの一時性この見出しへのリンク

Location ヘッダで返るダウンロードURLは一時的に有効なURLで、再利用できません。保存はせず、毎回 /v1/download/postalcode/{path} を叩いてURLを取得し直してください。

ファイルサイズについてこの見出しへのリンク

全件スナップショットのため展開後のサイズは大きくなります。ストリーミング展開 (xz のパイプ) を活用するとメモリ消費を抑えられます。

更新頻度とバージョンこの見出しへのリンク

月次更新が基本。日本郵便の更新タイミングに合わせて新バージョンが公開されます。古いバージョンは一定期間保持後、削除される可能性があります。長期保存が必要な場合は自前で保管してください。

このAPIに関する技術FAQこの見出しへのリンク

関連リファレンスこの見出しへのリンク

• ⚠️ 既知の問題 (このAPIに該当する制約・破壊的変更)
• 郵便番号→住所API — 同一スキーマの都度API (差分取得もこちら)
• 市区町村API — 都道府県→市区町村マスタ
• API共通仕様 — Token認証 / HTTPステータス
• APIキー・認証 — シークレットキー vs 公開キー
• プランと料金 — データダウンロードオプション
• OpenAPI スキーマ (YAML): 2023-09-01 / 2024-01-01 / 2025-01-01

最終更新: 2026-07-14