API почтовых индексов Мексики 🇲🇽

Сверхбыстрый RESTful API, построенный на Python 3.12, FastAPI, SQLite в режиме WAL и Docker, предназначенный для ответа за < 1 мс с использованием официального каталога почтовых индексов, населенных пунктов, муниципалитетов и штатов Мексики.

📜 Пункт о юридической атрибуции (обязательный по CC BY 4.0)

Этот API использует и обрабатывает географическую информацию и информацию о почтовых индексах из официального каталога, опубликованного Почтовой службой Мексики (SEPOMEX) на datos.gob.mx по лицензии Creative Commons Attribution 4.0 International.

🚀 Основные характеристики

• Контракт API и спецификация: docs/api_contract.md

• Скорость и производительность: Время ответа менее миллисекунды с SQLite в режиме Write-Ahead Logging (WAL) и сериализацией orjson.

• Кибербезопасность: Усиление по OWASP, заголовки безопасности, ограничение скорости, строгая валидация regex Pydantic v2 и non-root пользователь Docker.

• Обработка ошибок корпоративного уровня: Формат RFC 7807 (Problem Details) с уникальным X-Correlation-ID для каждого запроса.

• Аудит и логирование: Логи в структурированном JSON с помощью loguru с ежедневной ротацией в полночь (00:00), сжатием .zip и хранением в течение 30 дней.

• Предотвращение взаимоблокировок: HTTP-соединения в режиме только чтения (mode=ro) с PRAGMA busy_timeout=5000;.

• Автоматический скрипт загрузки: Скачивает, очищает (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 и создаст sepomex.db с более чем 148 000 населенных пунктов и оптимизированными индексами.

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 запросов/мин по умолчанию).

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

Проект включает два легковесных пакета SDK-клиентов для удобного использования API без написания HTTP-запросов вручную:

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

🤖 Интеграция с ИИ-агентами (Model Context Protocol - MCP)

API имеет официальный MCP-сервер (scripts/mcp_server.py), который позволяет ИИ-агентам (Claude Desktop, ChatGPT, Antigravity IDE, LangChain, AutoGPT) запрашивать и взаимодействовать с официальной географической базой данных Мексики на естественном языке.

Инструменты, доступные для ИИ:

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

Контейнер выполняет в фоне асинхронный ежемесячный планировщик, который проверяет наличие обновлений на datos.gob.mx без влияния на задержку HTTP (< 1 мс).

Для ручного запуска проверки или принудительного обновления каталога внутри Docker-контейнера:

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

🏆 Сравнение с современными аналогами (2026)

Техническое сравнение нашего решения с открытыми альтернативами и коммерческими SaaS-сервисами на текущем рынке:

🔬 Эксперименты

Проект включает полный набор тестов нагрузки, GPS-геозонирования, налоговой нормализации и совместимости с агентами искусственного интеллекта (MCP).

• Фаза 1 (Задержка и пакетная обработка): Ускорение в 58.91x при пакетной валидации (POST /batch-validate).

• Фаза 2 (Нормализация SAT): Алгоритмический $F_1$-Score 90.45% при 100% точности на наборе данных из 1000 образцов с шумом.

• Фаза 3 (ИИ-агенты / MCP): 99.43% экономии токенов при взаимодействии через MCP-сервер.

🧪 Запуск тестов

pytest