headwater
Headwater es una API auto-alojada que unifica acceso a Google Maps, Noticias, Tendencias y YouTube en JSON normalizado.
Ficha actualizada 24 sept 2026, 3:22 · upstream 24 sept 2026, 3:13 · release v2.2.1
Qué es headwater
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
Headwater actúa como capa unificadora frente a múltiples fuentes de datos de Google (Maps, Noticias, Tendencias, YouTube) sin requerir claves oficiales ni pagar por uso individual. Proporciona respuestas JSON planas optimizadas para consumo directo en flujos de trabajo como n8n o pasos de LLM, evitando la complejidad de manejar múltiples esquemas de respuesta y autenticación.
La arquitectura se basa en FastAPI y Python, con Redis para almacenamiento persistente de caché y registros de trabajos asíncronos. Esto garantiza que los datos no se pierdan tras reinicios del servicio, a diferencia del almacenamiento en memoria temporal. El sistema incluye gestión robusta de límites de tasa y rotación de proxies para respetar las políticas de los servicios upstream.
Es crucial entender que utiliza interfaces no oficiales de Google. Aunque ofrece normalización y estabilidad mediante caché, los cambios en la estructura de las páginas web pueden afectar la extracción. Además, el rendimiento varía significativamente entre endpoints, siendo la búsqueda de mapas particularmente lenta debido a la naturaleza de scraping de cada resultado individual.
- Integración en flujos de trabajo n8n para automatización de datos
- Ingesta de transcripciones de YouTube para análisis de contenido con LLM
- Investigación de mercado mediante Google Trends y Noticias normalizadas
- Monitorización de reputación local usando datos de Google Maps
- Expansión de keywords mediante Google Autocomplete para SEO
- API única con una clave X-API-Key para todas las operaciones
- Almacenamiento persistente en Redis evita pérdida de datos tras reinicios
- Respuestas JSON normalizadas listas para consumo directo sin transformaciones
- Soporte nativo para trabajos asíncronos y webhooks en Google Maps
- Gestión activa de límites de tasa y rotación de proxies por upstream
- La extracción de Google Maps es lenta (~12s por resultado) debido a scraping secuencial
- Dependencia de interfaces no oficiales que pueden romperse sin aviso previo
- Algunos servicios como YouTube requieren proxy o tienen restricciones de acceso directo
- El almacenamiento en memoria se pierde si Redis no está activo en producción
- No incluye claves API oficiales de Google, requiere gestión externa de límites
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. Copiar .env.example a .env y configurar REDIS_URL y API_KEY. El servicio requiere Redis para persistencia; sin él, los trabajos asíncronos se pierden al reiniciar. Verificar salud en /health/detailed. Asegurar que NO_PROXY_HOSTS excluya youtube.com y google.com si ENABLE_PROXY está activo. Imágenes firmadas disponibles en Docker Hub y GHCR.
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.