メキシコ郵便番号API 🇲🇽

Python 3.12、FastAPI、WALモードのSQLite、Dockerで構築された超高速RESTful API。メキシコの公式郵便番号、集落、市区町村、州のカタログを1ミリ秒未満で応答するよう設計されています。

📜 法的帰属条項（CC BY 4.0による必須）

このAPIは、メキシコ郵便公社（SEPOMEX）がdatos.gob.mxを通じて公開している公式カタログから得た地理情報および郵便番号情報を、Creative Commons Attribution 4.0 Internationalライセンスの下で使用・処理しています。

🚀 主な特徴

• API契約と仕様: docs/api_contract.md

• 速度とパフォーマンス: Write-Ahead Logging（WAL）モードのSQLiteとorjsonシリアライゼーションによるサブミリ秒の応答時間。

• サイバーセキュリティ: OWASPハードニング、セキュリティヘッダー、レート制限、Pydantic v2の厳格な正規表現バリデーション、Dockerの非rootユーザー。

• エンタープライズエラー処理: リクエストごとに一意のX-Correlation-IDを持つRFC 7807（Problem Details）形式。

• 監査とロギング: loguruによる構造化JSONログ、毎日深夜0時（00:00）にローテーション、.zip圧縮、30日間保持。

• デッドロック防止: PRAGMA busy_timeout=5000;を使用した読み取り専用モード（mode=ro）のHTTP接続。

• 自動取り込みスクリプト: データベースをアトミックにダウンロード、クレンジング（ISO-8859-1からUTF-8）、投入します。

📦 ローカルインストールと実行

1. 前提条件

• Python 3.10+

• Virtualenv または Docker

2. 環境設定と依存関係のインストール

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. データ取り込みの実行（SEPOMEX / datos.gob.mx）

python scripts/ingest_sepomex.py

このコマンドは、公式のCPdescarga.txtファイルをダウンロードし、148,000以上の集落と最適化されたインデックスを含むsepomex.dbを生成します。

4. 開発サーバーの起動

uvicorn app.main:app --reload --port 8000

対話型ドキュメントにアクセス: http://localhost:8000/docs

🐳 Dockerでの実行

オプションA: Docker Build & Run

docker build -t codigos-postales-api .
docker run -p 8000:8000 codigos-postales-api

オプションB: Docker Compose

docker-compose up -d

🔐 認証とレート制限（API Key & JWT）

APIは.envから設定可能なハイブリッド認証スキームを備えています:

1. 動作モード（REQUIRE_AUTH）

• REQUIRE_AUTH=False（公開APIモード、デフォルト）: エンドポイントは自由にアクセス可能。リクエスト制御はIPベースのレート制限（デフォルトで120 req/min）によって行われます。

• REQUIRE_AUTH=True（保護されたエンタープライズAPIモード）: 各リクエストでヘッダーに有効な認証情報を送信する必要があります。

2. サポートされている認証オプション

1. ヘッダー X-API-Key:

   curl -H "X-API-Key: key-dev-12345" http://localhost:8000/api/v1/codigo-postal/01000

2. JWT Bearerトークン（Authorization: Bearer <token>）:

   • JWTトークンの交換（24時間有効）:

     curl -X POST http://localhost:8000/api/v1/auth/token -H "X-API-Key: key-dev-12345"

   • 返されたトークンを使用したリクエスト:

     curl -H "Authorization: Bearer <tu_jwt_token>" http://localhost:8000/api/v1/codigo-postal/01000

🛠️ 利用可能なエンドポイント

📦 公式SDKクライアント（mx-postal-client）

このプロジェクトには、手動でHTTPリクエストを書かずにAPIを簡単に利用するための軽量SDKクライアントパッケージが2つ含まれています:

• Python SDK（sdk/python）:

  pip install ./sdk/python

  from mx_postal_client import MXPostalClient
  client = MXPostalClient(base_url="http://localhost:8080")
  cp_data = client.get_codigo_postal("01000", colonia="San Ángel")

• TypeScript / Node.js SDK（sdk/typescript）:

  npm install ./sdk/typescript

  import { MXPostalClient } from 'mx-postal-client';
  const client = new MXPostalClient({ baseUrl: 'http://localhost:8080' });
  const detail = await client.getCodigoPostal('01000');

🤖 AIエージェントとの統合（Model Context Protocol - MCP）

APIには公式MCPサーバー（scripts/mcp_server.py）が含まれており、AIエージェント（Claude Desktop、ChatGPT、Antigravity IDE、LangChain、AutoGPT）が自然言語でメキシコの公式地理データベースを照会・操作できます。

AI向け公開ツール:

1. consultar_codigo_postal(cp): 完全な地理情報と集落リストを返します。

2. validar_direccion_postal(codigo_postal, colonia, estado, municipio): SEPOMEXとのデータ一致をリアルタイムで検証します。

3. buscar_asentamientos_por_nombre(nombre_colonia, limite): キーワードによる自然言語検索。

Claude Desktop / Antigravity IDEでの設定（mcp.json）:

{
  "mcpServers": {
    "mx-postal-codes": {
      "command": "python3",
      "args": ["/ruta/absoluta/a/codigos-postales-api/scripts/mcp_server.py"]
    }
  }
}

🔄 SEPOMEXカタログの自動検証

コンテナはバックグラウンドで非同期の月次スケジューラを実行し、HTTPレイテンシ（< 1 ms）に影響を与えることなくdatos.gob.mxの更新を確認します。

Dockerコンテナ内で手動で検証を実行したり、カタログの更新を強制するには:

docker exec codigos_postales_api python3 scripts/check_updates.py --force

🏆 最先端技術との比較（2026年）

現在の市場におけるオープンソースの代替案および商用SaaSサービスと比較した、当ソリューションの技術比較:

🔬 実験

このプロジェクトには、負荷テスト、GPSジオフェンシング、税務正規化、人工知能エージェント（MCP）との相互運用性のための完全なテストスイートが含まれています。

• フェーズ1（レイテンシとバッチ）: 一括バリデーション（POST /batch-validate）で58.91倍の高速化。

• フェーズ2（SAT正規化）: 1,000サンプルのノイズを含むデータセットで100%の精度を達成し、アルゴリズムの$F_1$-スコアは90.45%。

• フェーズ3（AIエージェント / MCP）: MCPサーバーを介した相互運用により、99.43%のトークン節約。

🧪 テストの実行

pytest