Mexikanische Postleitzahlen-API 🇲🇽

Ultra-schnelle RESTful-API, erstellt mit Python 3.12, FastAPI, SQLite im WAL-Modus und Docker, entwickelt, um in < 1 ms mit dem offiziellen Katalog der Postleitzahlen, Siedlungen, Gemeinden und Bundesstaaten Mexikos zu antworten.

📜 Klause der rechtlichen Zuschreibung (verpflichtend nach CC BY 4.0)

Diese API verwendet und verarbeitet geografische Informationen und Postleitzahldaten aus dem offiziellen Katalog, der vom Mexikanischen Postdienst (SEPOMEX) über datos.gob.mx unter der Creative Commons Attribution 4.0 International Lizenz veröffentlicht wurde.

🚀 Hauptmerkmale

• API-Vertrag und Spezifikation: docs/api_contract.md

• Geschwindigkeit und Leistung: Antwortzeiten im Sub-Millisekundenbereich mit SQLite im Write-Ahead Logging (WAL)-Modus und orjson-Serialisierung.

• Cybersicherheit: OWASP-Härtung, Sicherheitsheader, Rate Limiting, strenge Pydantic v2-Regex-Validierung und Docker non-root user.

• Enterprise-Fehlerbehandlung: Format RFC 7807 (Problem Details) mit eindeutigem X-Correlation-ID pro Anfrage.

• Audit & Logging: Strukturierte JSON-Logs mittels loguru mit täglicher Rotation um Mitternacht (00:00), .zip-Komprimierung und 30-tägiger Aufbewahrung.

• Deadlock-Prävention: HTTP-Verbindungen im Nur-Lesen-Modus (mode=ro) mit PRAGMA busy_timeout=5000;.

• Automatisches Ingest-Skript: Lädt herunter, bereinigt (ISO-8859-1 zu UTF-8) und befüllt die Datenbank atomar.

📦 Installation und lokale Ausführung

1. Voraussetzungen

• Python 3.10+

• Virtualenv oder Docker

2. Umgebung einrichten und Abhängigkeiten installieren

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

3. Daten-Ingest ausführen (SEPOMEX / datos.gob.mx)

python scripts/ingest_sepomex.py

Dieser Befehl lädt die offizielle Datei CPdescarga.txt herunter und erzeugt sepomex.db mit über 148.000 Siedlungen und optimierten Indizes.

4. Entwicklungsserver starten

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

Besuche die interaktive Dokumentation unter: http://localhost:8000/docs

🐳 Ausführung mit Docker

Option A: Docker Build & Run

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

Option B: Docker Compose

docker-compose up -d

🔐 Authentifizierung & Rate Limiting (API-Key & JWT)

Die API verfügt über ein hybrides Authentifizierungsschema, das über .env konfigurierbar ist:

1. Betriebsmodi (REQUIRE_AUTH)

• REQUIRE_AUTH=False (Öffentlicher API-Modus, Standard): Die Endpunkte sind frei zugänglich. Die Anforderungskontrolle erfolgt über IP-basiertes Rate Limiting (Standard 120 req/min).

• REQUIRE_AUTH=True (Geschützter Enterprise-API-Modus): Erfordert, dass jede Anfrage gültige Anmeldeinformationen in den Headern sendet.

2. Unterstützte Authentifizierungsoptionen

1. Header X-API-Key:

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

2. JWT-Bearer-Token (Authorization: Bearer <token>):

   • Einlösen eines JWT-Tokens (gültig für 24 Stunden):

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

   • Anfrage mit dem zurückgegebenen Token:

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

🛠️ Verfügbare Endpunkte

📦 Offizielle SDK-Client-Pakete (mx-postal-client)

Das Projekt enthält zwei schlanke SDK-Client-Pakete, um die API einfach zu nutzen, ohne manuelle HTTP-Anfragen schreiben zu müssen:

• 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');

🤖 Integration mit KI-Agenten (Model Context Protocol - MCP)

Die API verfügt über einen offiziellen MCP-Server (scripts/mcp_server.py), der es KI-Agenten (Claude Desktop, ChatGPT, Antigravity IDE, LangChain, AutoGPT) ermöglicht, die offizielle geografische Datenbank Mexikos in natürlicher Sprache abzufragen und zu interagieren.

Für KI bereitgestellte Werkzeuge:

1. consultar_codigo_postal(cp): Gibt den vollständigen geografischen Steckbrief und die Liste der Siedlungen zurück.

2. validar_direccion_postal(codigo_postal, colonia, estado, municipio): Validiert in Echtzeit die Übereinstimmung der Daten mit SEPOMEX.

3. buscar_asentamientos_por_nombre(nombre_colonia, limite): Natürlichsprachliche Suche nach Schlüsselwörtern.

Konfiguration in Claude Desktop / Antigravity IDE (mcp.json):

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

🔄 Automatische Überprüfung des SEPOMEX-Katalogs

Der Container führt im Hintergrund einen asynchronen monatlichen Planer aus, der das Vorhandensein von Neuerungen auf datos.gob.mx überprüft, ohne die HTTP-Latenz zu beeinträchtigen (< 1 ms).

Zum manuellen Ausführen der Überprüfung oder zum Erzwingen einer Katalogaktualisierung innerhalb des Docker-Containers:

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

🏆 Vergleich mit dem Stand der Technik (2026)

Technischer Vergleich unserer Lösung mit aktuellen Open-Source-Alternativen und kommerziellen SaaS-Diensten:

🔬 Experimente

Das Projekt verfügt über eine vollständige Suite von Lasttests, GPS-Geofencing, Steuer-Normalisierung und Interoperabilität mit KI-Agenten (MCP).

• Phase 1 (Latenz und Batch): Beschleunigung um 58,91x bei der Batch-Validierung (POST /batch-validate).

• Phase 2 (SAT-Normalisierung): Algorithmischer $F_1$-Score von 90,45% mit 100% Präzision in einem Datensatz von 1.000 verrauschten Stichproben.

• Phase 3 (KI-Agenten / MCP): 99,43% Token-Einsparung bei der Interoperation über den MCP-Server.

🧪 Tests ausführen

pytest