headwater
API auto-alojada que normaliza datos de Google Maps, Noticias, Tendencias y Autocomplete, más transcripciones de YouTube. Usa Next.js/FastAPI con Redis para caché persistente. Ofrece 67 operaciones en un solo endpoint base, sin facturación por llamada y listo para pipelines (n8n/LLMs).
Ficha actualizada 23 sept 2026, 23:17 · upstream 23 sept 2026, 23:04 · release v2.1.0
Qué es headwater
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
Headwater es una API auto-alojada que centraliza el acceso a datos de Google Maps, Noticias, Tendencias y Autocomplete, además de transcripciones de YouTube. Normaliza todas las respuestas en JSON plano, eliminando la necesidad de manejar múltiples esquemas de respuesta o facturación por llamada a proveedores externos.
El proyecto está construido con Next.js y FastAPI, utilizando Python 3.14 como lenguaje principal. Incluye Redis para almacenamiento persistente de caché y registros, lo que permite escalar horizontalmente sin perder datos entre reinicios. La arquitectura soporta despliegue en Docker o mediante un instalador one-line que configura automáticamente el entorno.
La API está diseñada específicamente para pipelines automatizados (como n8n o flujos de LLM), no para dashboards interactivos. Cada respuesta es JSON plano optimizado para consumo programático, con soporte para operaciones asíncronas en endpoints pesados como Google Maps.
- Integración en flujos automatizados (n8n) para obtener datos de mapas, noticias o tendencias sin dependencias externas
- Extracción de transcripciones de YouTube con timestamps y traducción automática a múltiples idiomas
- Normalización de respuestas de Google para evitar manejar múltiples esquemas JSON en pipelines de datos
- Monitoreo de tendencias de búsqueda y análisis de sentimiento basado en datos de Google Trends
- 67 operaciones unificadas bajo una única clave API y base URL, simplificando la integración
- Caché persistente en Redis que evita pérdida de datos entre reinicios del contenedor
- Manejo explícito de rate limiting y politeness pacing para respetar las políticas de los upstreams
- Respuestas JSON normalizadas listas para consumo por LLMs o scripts sin transformación adicional
- Google Maps tiene latencia alta (~12 segundos por resultado) debido a la necesidad de abrir cada lugar individualmente
- Las interfaces son no oficiales; Google puede cambiar sus selectores CSS sin previo aviso, rompiendo extracciones
- Algunos endpoints (como Google Trends) tienen cuotas externas que no pueden ser aumentadas desde el cliente
- YouTube requiere proxy en algunos casos y puede fallar con ciertos tipos de proxies por políticas de cumplimiento
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Despliegue recomendado con Docker Compose. Redis es obligatorio en producción para evitar pérdida de datos entre reinicios. Configurar ENABLE_PROXY=true solo si necesario, usando NO_PROXY_HOSTS para excluir youtube.com y google.com del proxy. Verificar /health/detailed antes de producción para confirmar record_storage_durable=true.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.