멕시코 우편번호 API 🇲🇽

Python 3.12, FastAPI, SQLite(WAL 모드) 및 Docker로 구축된 초고속 RESTful API로, 멕시코의 공식 우편번호, 주거지, 지방자치단체 및 주 카탈로그를 1ms 미만으로 응답하도록 설계되었습니다.

📜 법적 저작권 표시 조항 (CC BY 4.0에 따라 필수)

이 API는 datos.gob.mx를 통해 멕시코 우편 서비스(SEPOMEX)가 발행한 공식 카탈로그에서 제공되는 지리 정보 및 우편번호 정보를 사용 및 처리하며, Creative Commons Attribution 4.0 International 라이선스에 따라 제공됩니다.

🚀 주요 특징

• API 계약 및 명세: docs/api_contract.md

• 속도 및 성능: SQLite Write-Ahead Logging(WAL) 모드 및 orjson 직렬화를 통한 서브 밀리초 응답 시간.

• 사이버 보안: OWASP 강화, 보안 헤더, 속도 제한, Pydantic v2 엄격한 정규식 검증 및 Docker non-root 사용자.

• 엔터프라이즈 오류 처리: 요청별 고유 X-Correlation-ID를 포함한 RFC 7807(문제 세부 정보) 형식.

• 감사 및 로깅: loguru를 통한 구조화된 JSON 로그, 자정(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 키 및 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)

프로젝트에는 수동 HTTP 요청을 작성하지 않고도 API를 쉽게 사용할 수 있는 두 개의 경량 SDK 클라이언트 패키지가 포함되어 있습니다:

• 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에는 AI 에이전트(Claude Desktop, ChatGPT, Antigravity IDE, LangChain, AutoGPT)가 자연어로 멕시코 공식 지리 데이터베이스를 쿼리하고 상호 작용할 수 있도록 하는 공식 MCP 서버(scripts/mcp_server.py)가 포함되어 있습니다.

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