rainmanjam/headwater repository overview

⁠Headwater

One self-hosted API for Google Maps, News, Trends and Autocomplete, plus YouTube transcripts. Normalised JSON, no per-call vendor pricing.

Source: https://github.com/rainmanjam/headwater⁠ · License: MIT

docker run -d --name headwater -p 8000:8000 \
  -e API_KEY=choose-a-long-random-string \
  rainmanjam/headwater:latest

curl -H "X-API-Key: choose-a-long-random-string" \
  "http://localhost:8000/api/v1/google-autocomplete/autocomplete?q=n8n"

{"suggestions":["n8n","n8n workflows","n8n ai","n8n pricing","n8n github"]}

Interactive docs are at /api/docs once it is running. That list is generated from the code, so it is always the authoritative one.

⁠Tags

1.x tags predate the rename from social-flood and are kept so older deploys stay reproducible. They are byte-identical to the originals.

⁠Why

These five sources have no single official API between them. Getting search interest, a place's reviews, a news feed and a video transcript into one pipeline normally means four vendors, four auth schemes, four response shapes and four invoices that scale per call.

Headwater is one service in front of all of them — 67 operations behind one key and one base URL, running on your own infrastructure with your own IP and your own rate limits.

It is not a Google Cloud wrapper. Nothing here needs a Google API key, and nothing here is an officially supported Google interface.

⁠Running it properly

Redis is not optional in production. Without it, Maps jobs, monitors and webhooks fall back to in-memory storage that is lost on restart and invisible to sibling workers. /health/detailed reports record_storage_durable so you can assert on it rather than hope.

services:
  headwater:
    image: rainmanjam/headwater:latest
    ports: ["8000:8000"]
    environment:
      API_KEY: choose-a-long-random-string
      REDIS_URL: redis://redis:6379/0
    depends_on: [redis]
  redis:
    image: redis:7-alpine

⁠Configuration

Proxying is per host rather than all-or-nothing, because the upstreams disagree: Reddit answers 429 to datacentre IPs and needs a proxy, some providers refuse youtube.com at the tunnel, and Google Maps loads fine through a plain GET but a full browser navigation through a datacentre proxy never settles.

⁠What it covers

⁠Limits worth knowing before you adopt it

• Maps costs about 12s per result, by an order of magnitude the slowest thing here. Plan around the cache or use the async job endpoints.
• These are unofficial interfaces. Google changes markup and parameters without notice. The Maps scraper reports selectors_stale when extraction stops matching, so breakage surfaces as a signal rather than as silently empty results.
• Upstream quotas are real. Google Trends limits related queries and topics independently of anything configured here.
• summary and keywords on /article-details/ return null. They needed nltk, which carries an unfixed advisory (PYSEC-2026-3740) with no patched release, so the dependency was dropped. Everything else — title, authors, publish date, full text, images — is unaffected.

⁠Image

Multi-stage build on python:3.14-slim-trixie, pinned by digest, running as a non-root user, with Debian security updates applied at build time. Carries standard org.opencontainers.image.* labels, so docker inspect tells you the source, revision, version and license of whatever you pulled.

Full documentation, including deployment, performance tuning and troubleshooting guides: https://github.com/rainmanjam/headwater⁠