Documentation — integrating with Alibrio Weather

This page is written for consumers of the service—teams embedding our schematic weather graphics in your own products, dashboards, or sites using your data and our HTTP APIs. Responses are HTML (pages or fragments) keyed by a standard WMO weather code. Use your account, API keys, and signed embed URLs as described below. Machine-readable duplicate of the consumer topics: GET /api/docs/developer-integration — JSON response with English markdown (consumer integration topics).

Trying the demo

On the demo page, choose a city in the list to see a live forecast card with the same graphic style used across the app. Data comes from Open-Meteo for those fixed locations only.

Account settings

When sign-in is enabled on this deployment, use Login and open Settings to manage your profile and API tokens.

Service status

API key

How to obtain a key

What the key is for

GET /api/weather/demo/… needs no API key.

Endpoints

MethodPathRole
POST/api/weather-graphics/signed-urlJSON: mint a short-lived signed_url for public iframes.
GET/api/weather-graphics/render?t=…HTML: load graphic from token (no Bearer).
GET/api/weather/demo/{id}HTML fragment — demo cities 1–3 only (no key).
GET/api/api-keysList your API keys (metadata only; never returns full secrets).
POST/api/api-keysCreate a key with JSON {"name":"…"}; response includes plaintext key once.
DELETE/api/api-keys/{id}Revoke the key with UUID {id} (authenticated).
GET/health, /api/healthJSON health (no auth).
GET/api/docs/developer-integrationIntegration guide as JSON (markdown): embeds, keys, limits. No auth.

How to use

Important: signed URLs are temporary

Signed URLs are intentionally short-lived. Do not store them in HTML, CMS fields, databases, or static pages as permanent embed URLs. They are like an S3 pre-signed URL or time-bound token — not a permanent widget link.

Generate a signed URL shortly before it is shown to the end user. If the page can stay open longer than the token lifetime, your app must refresh the iframe by requesting a new signed URL from your backend.

Backend caching (recommended): your server should not call mint on every page load. Keep the latest mint JSON in memory or a short-lived server cache keyed by embed identity, serve the same signed_url to clients until shortly before expires_at, then mint once more. That stays within the spirit of “temporary” URLs (they still expire) and avoids hitting per-minute mint caps.

Mint response includes:

{
  "signed_url": "https://your.host/api/weather-graphics/render?t=…",
  "expires_at": "2026-05-09T12:34:56Z",
  "ttl_seconds": 900
}

expires_at is RFC 3339 / ISO-8601 UTC. ttl_seconds is the lifetime actually applied after the server clamps your request (often 300–900 seconds — your provider may use a different range). For long-lived pages, refresh the URL before expires_at, and again after a failed iframe load.

Recommended pattern

  1. Browser requests your backend (e.g. GET /weather-card-url).
  2. Your backend authenticates to Alibrio Weather and calls POST /api/weather-graphics/signed-url.
  3. Backend returns signed_url, expires_at, ttl_seconds to the browser.
  4. Browser sets the iframe src to signed_url.
  5. Before expiry or after an error, obtain a new signed URL and reload the iframe.

Never embed a signed URL directly into a static page as a long-term src.

Example refresh helper (browser) — your backend must proxy the mint call:

async function refreshWeatherIframe() {
  const res = await fetch("/my-backend/weather-card-url");
  const { signed_url, expires_at } = await res.json();
  document.querySelector("#weather-frame").src = signed_url;
}

POST /api/weather-graphics/signed-url

Auth: signed-in session (terms accepted), or Authorization: Bearer with an API key from Settings / POST /api/api-keys, or a server credential issued by your provider. User keys typically include scope weather_graphics:sign. Rate limits apply for signing and rendering separately.

JSON body (application/json):

GET /api/weather-graphics/render?t=…

No Bearer. Parameter t is the signed token; response is the graphic HTML encoded in the token (visual or card kind from minting).

Example (curl)

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"card","code":61,"night":false,"city":"Prague","temperature":"12 °C","description":"Rain","ttl_seconds":900}' \
  "http://127.0.0.1:8080/api/weather-graphics/signed-url"

Fair-use limits

Figures below are typical defaults you may see on a standard deployment. Your subscription, trial, or private environment can differ — check your agreement or ask support. Short-lived counters are tracked inside each running instance and may reset after maintenance or scaling.

Account

POST /api/weather-graphics/signed-url — sliding window ≈ one minute per client bucket:

Integrators: cache mint responses on your backend (keyed by logical embed) and reuse signed_url until shortly before expires_at. Calling mint on every client request makes it easy to exceed 10 mints/minute per user or API key.

GET /api/weather-graphics/render?t=…

GET /api/weather/demo/{id} — Open-Meteo-backed fragments are cached per demo slot; default cache TTL is often about 15 minutes (your hosting may tune this).

API keys (JSON)

With OAuth + database: at most three active keys per user. Settings is the UI equivalent (HTML forms); these endpoints are for automation.

REST routes (authenticated session or equivalent — same as signed-in app):

MethodPathPurpose
GET/api/api-keysList your keys: ids, names, prefixes, validity — no plaintext secrets.
POST/api/api-keysCreate: JSON body {"name":"…"}; response includes plaintext key once.
DELETE/api/api-keys/{id}Revoke the key identified by UUID {id}.

GET /api/weather/demo/{id}

HTML fragment; fixed cities only: 1 Prague, 2 New York, 3 Singapore.

The service may call Open-Meteo for current conditions; responses are cached per slot (often about 15 minutes). Unknown {id} → 404. 

curl -sS "http://127.0.0.1:8080/api/weather/demo/1"

Health & meta