Go-MexPost 🇲🇽🚀

Microservicio ultrarrápido para consulta de colonias, códigos postales y coordenadas de México.
Report Bug · Request Feature

---

🔑 Abstract (English)

Go-MexPost is a blazing-fast, open-source microservice built in Golang, designed to simplify access to postal and geographic data in Mexico. Formerly built on Node.js, this project was completely rewritten from scratch using a strict Hexagonal Architecture and an embedded SQLite database to achieve extreme performance, high concurrency, and minimal memory footprint.

The data generation process has been decoupled into an external ETL pipeline, making this API fully agnostic and effortlessly maintainable. Users can search by postal code, partial names, or perform reverse geocoding to find neighborhoods based on geographic coordinates using GeoJSON polygons.

📍 Descripción

Go-MexPost es la evolución de nuestro proyecto original. Hemos reescrito el motor por completo utilizando Golang para ofrecer un microservicio ultrarrápido, capaz de manejar miles de peticiones por segundo consumiendo muy poca memoria RAM.

Para facilitar su mantenimiento, hemos separado la construcción de la base de datos a un repositorio externo (ETL). Esto permite que Go-MexPost funcione mediante una base de datos embebida (SQLite), lo que significa que puedes desplegar este microservicio en cualquier servidor en segundos, sin necesidad de configurar gestores de bases de datos complejos.

🎯 Objetivo

Proveer una API REST robusta, eficiente y de nivel empresarial para desarrolladores, investigadores y empresas que requieran consultar y gestionar datos de colonias en México de forma instantánea. Todo esto respaldado por un diseño modular, pruebas unitarias exhaustivas y código limpio.

🔍 Características

• ⚡ Rendimiento Extremo: Gracias a Go y Gin-Gonic, las respuestas se sirven en milisegundos.
• 📦 Base de Datos Embebida (SQLite): No requiere instalar MySQL ni PostgreSQL. Descarga la base de datos lista para usar y arranca el servidor.
• 🔎 Búsquedas Flexibles y Optimizadas:
  • Por Código Postal exacto o parcial (ej. 067%).
  • Por Nombre de Colonia exacto o parcial (ignorando mayúsculas y minúsculas).
  • Filtros combinados por Estado y Municipio.
• 📄 Paginación completa: Todos los resultados de /colonias incluyen pagina, total_paginas, pagina_anterior y pagina_siguiente para navegar grandes conjuntos de datos.
• 🛡️ Rate Limiting por IP: Protección integrada contra abuso mediante token bucket. Configurable con variables de entorno (RATE_LIMIT, RATE_BURST) sin recompilar.
• 🗺️ Soporte Geoespacial (GeoJSON): Capacidad de descargar una versión espacial de la base de datos que incluye los polígonos de cada código postal.
• 📍 Geocodificación Inversa: Búsqueda de colonias mediante coordenadas (Point-in-Polygon) y obtención de centroides geográficos.
• 🏗️ Arquitectura Hexagonal: Código desacoplado, testeable y preparado para escalar.

🚀 Instalación y Uso

Configurar el proyecto en tu máquina local es increíblemente sencillo gracias a nuestro script de inicialización integrado.

---

⚡ Opción Rápida: Probar sin programar (Releases)

Si no deseas instalar Go o compilar el código por tu cuenta, hemos preparado versiones precompiladas listas para usarse. ¡No requieren configuración!

Paso 1: Ve a nuestra página de Releases. Paso 2: Descarga el archivo .zip correspondiente a tu sistema operativo (windows, mac, o linux). Paso 3: Descomprime el archivo. Asegúrate de que tanto el ejecutable como el archivo de la base de datos (mapa.db) estén en la misma carpeta. Paso 4: Inicia el servidor:

• 🪟 Windows: Haz doble clic sobre el archivo go-mexpost-api.exe.
• 🐧 Linux / 🍏 Mac: Abre una terminal en esa carpeta, otorga permisos de ejecución y arráncalo con estos comandos:

  chmod +x go-mexpost-api
  ./go-mexpost-api

---

1. Clonar el repositorio

git clone https://github.com/open-mexico/go-mexpost.git
cd go-mexpost

2. Instalar dependencias

go mod tidy

3. Descargar la Base de Datos

Go-MexPost cuenta con un comando especial para descargar la base de datos oficial (generada en nuestro repo ETL) directamente a tu proyecto.

Opción A (Ligera): Solo datos postales y de texto (ideal para formularios).

go run ./cmd/setup/main.go

Opción B (Espacial) - Recomendada: Datos postales + Polígonos GeoJSON (ideal para mapas).

go run ./cmd/setup/main.go -geo=true

4. Iniciar el Servidor

go run ./cmd/api/main.go

La API estará corriendo en http://localhost:8080.

5. Variables de entorno (opcionales)

Variable	Default	Descripción
PORT	8080	Puerto en el que escucha el servidor
RATE_LIMIT	10	Solicitudes por segundo permitidas por IP
RATE_BURST	30	Ráfaga máxima instantánea por IP

# Ejemplo con configuración personalizada
PORT=3000 RATE_LIMIT=5 RATE_BURST=15 go run ./cmd/api/main.go

🛠️ Herramientas y Tecnologías Golang (1.26+): Lenguaje principal.

Gin-Gonic: Framework web HTTP de alto rendimiento.

SQLite (modernc.org): Driver de base de datos embebida 100% en Go (CGO-free).

Testify: Herramientas para pruebas unitarias (Mocks y Asserts).

golang.org/x/time/rate: Token bucket para rate limiting por IP.

📊 Fuente de Datos

La información es extraída, limpiada y optimizada desde las fuentes oficiales del Servicio Postal Mexicano (SEPOMEX/Correos de México) y cruzada con límites espaciales de Open Mexico GeoJSON.

🔑 Palabras Clave

• Golang
• Microservicio
• Códigos Postales México
• SEPOMEX API
• GeoJSON México
• Georreferenciación
• SQLite
• Arquitectura Hexagonal
• API REST México
• Open Source

🤝 Contribuir

¡Las contribuciones son lo que hace a la comunidad de código abierto un lugar increíble! Si tienes una sugerencia para mejorar esto, por favor haz un fork del repositorio y crea un pull request.

Haz un Fork del proyecto

Crea tu rama de característica (git checkout -b feature/CaracteristicaIncreible)

Haz commit de tus cambios usando preferentemente Gitmoji para los mensajes de commit:

git commit -m '✨ Añadir CaracteristicaIncreible'

Haz Push a la rama (git push origin feature/CaracteristicaIncreible)

Abre un Pull Request

💡 Usamos Gitmoji como convención para los mensajes de commit. Agrega el emoji correspondiente al tipo de cambio (✨ nueva función, 🐛 bug fix, 📝 documentación, ♻️ refactor, etc.).

📄 Licencia

Este proyecto está bajo la Licencia BSD-3 - mira el archivo LICENSE para más detalles.

🤗 Expresiones de Gratitud

Comparte este proyecto con otros desarrolladores 🗣📢

Invítame una cerveza 🍺 o un café ☕

Da una estrella ⭐ al repositorio si te ha sido útil.

Made with ❤️ by macarthuror - @MacarthurOr - arturo.ortegaro@gmail.com