API Reference

The weNow backend runs on Cloudflare Workers and exposes the endpoints listed below. All endpoints return JSON. The base URL for production is https://wenow-api.<account>.workers.dev.

Endpoint Overview

POST /api/weather

Main weather endpoint. Fans out to all active weather API sources in parallel, normalizes responses, computes a weighted ensemble median, and returns everything to the client.

Request Body

{
  "lat": 48.8566,         // Required (unless "location" is provided)
  "lon": 2.3522,          // Required (unless "location" is provided)
  "name": "Paris",        // Optional display name (max 200 chars)
  "location": "Paris",    // Alternative: city name string (backend geocodes it)
  "lang": "en",           // Optional, default "en" (max 5 chars)
  "includeHourly": false  // Optional, include hourly forecast data
}

Provide either lat/lon or location. If location is provided, the backend geocodes it to coordinates using the first search result.

Response (200)

{
  "data": [
    {
      "source": "Open-Meteo",
      "temperature": 18.5,
      "feelsLike": 17.2,
      "humidity": 62,
      "pressure": 1013,
      "windSpeed": 3.4,
      "windDirection": 220,
      "description": "Partly cloudy",
      "icon": "partly_cloudy",
      "timestamp": "2026-04-06T12:00:00Z",
      "location": {
        "city": "Paris",
        "country": "FR",
        "lat": 48.8566,
        "lon": 2.3522
      },
      "forecast": [
        {
          "date": "2026-04-07",
          "highTemp": 20.1,
          "lowTemp": 11.3,
          "description": "Sunny",
          "precipChance": 5
        }
      ],
      "hourlyForecast": [
        {
          "datetime": "2026-04-06T14:00:00Z",
          "temperature": 19.1,
          "feelsLike": 18.0,
          "humidity": 58,
          "windSpeed": 3.6,
          "windDirection": 215,
          "description": "Partly cloudy",
          "precipChance": 10
        }
      ]
    }
    // ... additional sources
  ],
  "ensemble": {
    "temperature": 18.3,
    "feelsLike": 17.0,
    "humidity": 60,
    "pressure": 1013,
    "windSpeed": 3.5,
    "description": "Partly cloudy",
    "confidence": {
      "level": "high",
      "range": 1.2,
      "sourceCount": 4,
      "totalSources": 4,
      "outliers": []
    },
    "forecast": [],
    "hourlyForecast": []
  },
  "errors": [
    {
      "source": "WeatherBit",
      "message": "Failed to fetch data"
    }
  ],
  "skipped": ["AccuWeather"],
  "rateLimit": {
    "remaining": 4,
    "limit": 5,
    "used": 1
  }
}

Error Responses

POST /api/weather/widget

Dedicated endpoint for Android home screen widgets. Identical request/response format to /api/weather, but with a separate, higher rate limit of 100 requests per day per IP. This separation ensures widget background refreshes (every 30 minutes) do not consume the app's daily quota.

Request Body

Same format as POST /api/weather.

Response

Same format as POST /api/weather. The rateLimit object reflects the widget quota (limit: 100) rather than the app quota.

GET /api/weather/status

Returns the caller's current rate limit usage for the weather endpoint. Does not consume a rate limit token. Useful for displaying remaining requests in the UI.

Response (200)

{
  "remaining": 4,
  "limit": 5,
  "used": 1
}

GET /api/geocode

City search autocomplete. Returns an array of matching cities with coordinates.

Query Parameters

Response (200)

[
  {
    "name": "Paris",
    "state": "Ile-de-France",
    "country": "FR",
    "lat": 48.8566,
    "lon": 2.3522
  },
  {
    "name": "Paris",
    "state": "Texas",
    "country": "US",
    "lat": 33.6609,
    "lon": -95.5555
  }
]

Error Responses

GET /api/geocode/reverse

Reverse geocoding: converts latitude/longitude coordinates to a city name. Used when the user taps "Use My Location" to resolve GPS coordinates to a display name.

Query Parameters

Response (200)

{
  "name": "Paris",
  "state": "Ile-de-France",
  "country": "FR",
  "lat": 48.8566,
  "lon": 2.3522
}

Error Responses

GET /api/accuracy

Returns a forecast accuracy leaderboard for a tracked location. The backend automatically snapshots forecasts and scores them against observed data daily at 08:00 UTC.

Query Parameters

Response (200)

{
  "location": {"lat": 48.86, "lon": 2.35, "name": "Paris"},
  "period": {"days": 7, "from": "2026-03-30", "to": "2026-04-06"},
  "leaderboard": [
    {
      "rank": 1,
      "source": "Open-Meteo",
      "avgHighError": 0.8,
      "avgLowError": 0.6,
      "compositeScore": 0.7,
      "daysTracked": 7,
      "trend": "stable"
    }
  ],
  "dataAvailable": true,
  "trackedSince": "2026-03-01T00:00:00Z"
}

Error Responses

GET /api/ads

Returns one weighted-random active ad from the ads table, or {ad: null} if the inventory is empty. Ads are first-party, self-served, and contain no third-party tracking code. An impression counter is incremented in D1 — aggregate only, not linked to any user or device.

Response (200)

{
  "ad": {
    "id": 1,
    "title": "weNow Premium — Coming Soon",
    "body": "Support the project. More sources, higher accuracy, no ads.",
    "imageUrl": null,
    "clickUrl": "https://wenow.name/#pricing",
    "kind": "cross-promo"
  }
}

When inventory is empty or all rows have active = 0:

{"ad": null}

POST /api/ads/click

Increments the click counter for an ad. Best-effort, fire-and-forget — the app does not block navigation on this request. No rate limit; the counter update is a single bounded write and no personal data is accepted.

Request Body

{"id": 1}

Response (200)

{"ok": true}

Error Responses

POST /api/feedback

Submits anonymous user feedback. Messages are stored in the D1 database and emailed in a digest every 2 hours via a scheduled cron task.

Request Body

{
  "message": "The app is great but...",  // Required, max 2000 chars
  "lang": "en",                           // Optional, default "en"
  "app_version": "1.2.0"                  // Optional
}

Response (200)

{"ok": true}

Error Responses

POST /api/auth/register

Creates a new user account with email and password. Returns a JWT token valid for 30 days.

Request Body

{
  "email": "user@example.com",   // Required, valid email format
  "password": "securepass123"    // Required, 8-128 characters
}

Response (201)

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 42,
    "email": "user@example.com"
  }
}

Error Responses

POST /api/auth/login

Authenticates with email and password. Returns a JWT token valid for 30 days.

Request Body

{
  "email": "user@example.com",
  "password": "securepass123"
}

Response (200)

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 42,
    "email": "user@example.com"
  }
}

Error Responses

GET /api/auth/me

Returns the currently authenticated user. Requires a valid JWT in the Authorization header.

Request Headers

Authorization: Bearer <jwt-token>

Response (200)

{
  "user": {
    "id": 42,
    "email": "user@example.com"
  }
}

Error Responses

POST /api/users

Registers a RevenueCat user ID. Insert-only — this endpoint cannot set or override subscription status (defaults to "free"). Only the RevenueCat webhook can change subscription status.

Request Body

{
  "revenuecatId": "rc_abc123",  // Required, max 256 chars
  "platform": "android"         // Required, "ios" or "android"
}

Response (200)

{"ok": true}

Error Responses

POST /api/webhooks/revenuecat

Receives subscription lifecycle events from RevenueCat. Authenticated via a Bearer token that is compared using constant-time comparison to prevent timing attacks.

Authentication

Authorization: Bearer <REVENUECAT_WEBHOOK_SECRET>

Handled Event Types

Unrecognized event types are acknowledged with {"ok": true, "message": "ignored"}.

Error Responses

Rate Limiting

All public endpoints are rate-limited per IP address. IP addresses are hashed with SHA-256 before storage to comply with GDPR — no raw IP addresses are persisted. Rate limit counters reset daily. Old records are purged by a scheduled cron job at 01:00 UTC.

When a rate limit is exceeded, the endpoint returns HTTP 429 with {"error": "Rate limit exceeded"} (or "Daily limit reached" for the weather endpoint, which also includes limit, used, and remaining fields).

CORS Policy

Cross-origin requests are restricted to the following origins:

• https://wenow.app and https://wenow.name
• https://*.wenow.pages.dev and https://*.wenow-name.pages.dev
• http://localhost and http://localhost:* (development only)

Allowed methods: GET, POST, OPTIONS. Allowed headers: Content-Type. Preflight responses are cached for 86400 seconds (24 hours).

Authentication

User endpoints (/api/auth/register, /api/auth/login) return JWT tokens valid for 30 days. Include the token in subsequent requests:

Authorization: Bearer <jwt-token>

The /api/auth/me endpoint validates the token and returns the current user. If the token is expired or invalid, a 401 response is returned.

The RevenueCat webhook uses a separate authentication mechanism: a shared secret passed as a Bearer token, validated with constant-time comparison to prevent timing attacks.

Global Error Handling

All request bodies are limited to 4096 bytes. Requests exceeding this limit receive a 413 Request Too Large response. Unmatched routes return 404 Not Found. Unhandled exceptions return 500 Internal Server Error.