Build a weather app

From your first 200 to a working app: where the key lives, the query to send, how long to keep each answer, how to read times and icons, and what to show for attribution. Every field the query returns is listed in the Weather field reference.

1. Call Smarter Weather from your own backend

Call Smarter Weather from your own backend, and have that backend serve only your own app. Your app calls your backend; your backend holds the key and calls https://api.smarterweather.com.

• Keep the key server-side. A key shipped in browser or mobile code is a key anyone can copy. Acceptable Use §4 covers keys in public clients: use a server-side or edge proxy for them.
• Serve your app, nobody else. Sharing your key with third parties, or operating a proxy, gateway or bring-your-own-key service that lets third parties use your credentials, is prohibited by Acceptable Use §1. The Acceptable Use Policy is the authority on what is allowed; this guide does not add to it.
• Put the route behind your app's own sign-in. Your backend's weather route must accept only requests from your signed-in users or your own app, checked with a session or an app token. Without that check it is an open relay for your key.
• CORS is not that check. In production the API accepts browser calls only from Smarter Weather's own sites, so a page on your domain cannot call it directly. CORS only governs what a browser lets a page read. Any other client can call your backend whatever its CORS headers say.

The two backends below are deliberately narrow:

• Each serves one route, GET /weather?lat=..&lon=...
• It answers 401 unless the request carries the X-App-Token header set to APP_TOKEN, compared in constant time. That shared token is a minimal stand-in for your app's sign-in. Replace it with your session check before you ship: a token in page code can be copied too.
• It refuses to start when SMARTERWEATHER_API_KEY or APP_TOKEN is unset or empty.
• It rejects a lat or lon that is not a number in range, and calls only /v1/weather with a fixed query.
• It caches each answer as section 3 describes. Requests for the same location that arrive while a call is in flight share that call's answer, whatever it is, so a burst makes one upstream call.
• It gives up on the API after 10 seconds for the whole call, body included, and answers 502 for a timeout, a dropped connection or a truncated body.
• It passes Retry-After and the RateLimit-* headers of the API's answer through to your app. After a 429 it answers every uncached request with a 429 of its own until Retry-After passes, without calling the API. Those local answers carry a recomputed Retry-After and no RateLimit-* headers, which described the API's call.

Set SMARTERWEATHER_API_BASE only to point the backend at a local stub in tests.

Node 20

// server.mjs. Run: node --env-file=.env server.mjs (Node 20.6+)
import { createServer } from "node:http";
import { createHash, timingSafeEqual } from "node:crypto";

const KEY = process.env.SMARTERWEATHER_API_KEY ?? "";
const APP_TOKEN = process.env.APP_TOKEN ?? ""; // stand-in for your app's own sign-in
const BASE = process.env.SMARTERWEATHER_API_BASE ?? "https://api.smarterweather.com";
const QUERY = "view=concise&days=7&hourly_hours=24&units=imperial";
const PASS = /^(content-type|retry-after|ratelimit-.*)$/i; // headers your app sees
const OUTSIDE_COVERAGE_TTL = 3600; // a point outside coverage stays outside
if (!KEY || !APP_TOKEN) {
  console.error("set SMARTERWEATHER_API_KEY and APP_TOKEN");
  process.exit(1);
}

const cache = new Map(); // "lat,lon" -> { expires, status, headers, body }
const inflight = new Map(); // "lat,lon" -> the pending upstream call, shared by every request for it
let throttled = null; // the last 429, answered locally until its Retry-After passes

const coord = (v, limit) => {
  const n = v === null || v.trim() === "" ? NaN : Number(v);
  return Math.abs(n) <= limit ? n.toFixed(4) : null;
};
const maxAge = (cc) =>
  /no-store/i.test(cc) ? 0 : Number(/(?:^|,)\s*max-age=(\d+)/i.exec(cc)?.[1] ?? 0);
const sha256 = (value) => createHash("sha256").update(value).digest();
const WANT = sha256(APP_TOKEN);
// Constant time: equal-length digests, so neither the length nor the bytes leak.
const signedIn = (req) => timingSafeEqual(sha256(String(req.headers["x-app-token"] ?? "")), WANT);
const problemType = (body) => {
  try { return JSON.parse(body).type ?? ""; } catch { return ""; }
};
// RateLimit-* describe one upstream call, so a stored copy keeps just the type.
const stored = (entry) => ({ ...entry, headers: { "content-type": entry.headers["content-type"] } });

async function upstream(lat, lon) {
  // The signal bounds the whole call, body included.
  const res = await fetch(`${BASE}/v1/weather?lat=${lat}&lon=${lon}&${QUERY}`, {
    headers: { Authorization: `Bearer ${KEY}` },
    signal: AbortSignal.timeout(10_000),
  });
  const headers = Object.fromEntries([...res.headers].filter(([name]) => PASS.test(name)));
  const body = await res.text();
  let ttl = res.ok ? maxAge(res.headers.get("cache-control") ?? "") : 0;
  if (res.status === 404 && problemType(body).endsWith("outside-coverage")) ttl = OUTSIDE_COVERAGE_TTL;
  if (res.status === 429) ttl = Number(res.headers.get("retry-after")) || 1;
  return { expires: Date.now() + ttl * 1000, status: res.status, headers, body };
}

async function fetchAndStore(key, lat, lon) {
  const entry = await upstream(lat, lon);
  for (const [k, v] of cache) if (v.expires <= Date.now()) cache.delete(k);
  if (entry.status === 429) throttled = stored(entry);
  else if (entry.expires > Date.now()) cache.set(key, stored(entry));
  return entry;
}

function weather(key, lat, lon) {
  const hit = cache.get(key);
  if (hit?.expires > Date.now()) return hit;
  if (throttled?.expires > Date.now()) return throttled;
  if (!inflight.has(key)) {
    inflight.set(key, fetchAndStore(key, lat, lon).finally(() => inflight.delete(key)));
  }
  return inflight.get(key);
}

createServer(async (req, res) => {
  const url = new URL(req.url, "http://localhost");
  if (req.method !== "GET" || url.pathname !== "/weather") return res.writeHead(404).end();
  if (!signedIn(req)) return res.writeHead(401).end("sign in first");
  const lat = coord(url.searchParams.get("lat"), 90);
  const lon = coord(url.searchParams.get("lon"), 180);
  if (lat === null || lon === null) return res.writeHead(400).end("lat and lon must be numbers");
  try {
    const entry = await weather(`${lat},${lon}`, lat, lon);
    const headers = { ...entry.headers };
    if (entry.status === 429) {
      headers["retry-after"] = String(Math.max(1, Math.ceil((entry.expires - Date.now()) / 1000)));
    }
    res.writeHead(entry.status, headers).end(entry.body);
  } catch {
    res.writeHead(502).end("weather unavailable");
  }
}).listen(8080);

Python

# server.py. Run: SMARTERWEATHER_API_KEY=... APP_TOKEN=... python3 server.py (stdlib only)
import concurrent.futures, hashlib, hmac, http.client, json, math, os, re, threading, time
import urllib.error, urllib.parse, urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

KEY = os.environ.get("SMARTERWEATHER_API_KEY", "")
APP_TOKEN = os.environ.get("APP_TOKEN", "")  # stand-in for your app's own sign-in
if not KEY or not APP_TOKEN:
    raise SystemExit("set SMARTERWEATHER_API_KEY and APP_TOKEN")
BASE = os.environ.get("SMARTERWEATHER_API_BASE", "https://api.smarterweather.com")
QUERY = "view=concise&days=7&hourly_hours=24&units=imperial"
PASS = re.compile(r"^(content-type|retry-after|ratelimit-.*)$", re.I)  # headers your app sees
OUTSIDE_COVERAGE_TTL = 3600  # a point outside coverage stays outside
DEADLINE = 10  # seconds for the whole upstream call, body included
WANT = hashlib.sha256(APP_TOKEN.encode()).digest()

cache = {}  # "lat,lon" -> (expires, status, headers, body)
inflight = {}  # "lat,lon" -> Pending, shared by every request for it while one thread calls upstream
guard = threading.Lock()  # guards cache, inflight and throttled
pool = concurrent.futures.ThreadPoolExecutor(max_workers=8)  # runs upstream calls under DEADLINE
throttled = None  # the last 429, answered locally until its Retry-After passes
FAILED = (OSError, http.client.HTTPException, concurrent.futures.TimeoutError)

class Pending:
    def __init__(self):
        self.done, self.entry, self.error = threading.Event(), None, None

def coord(values, limit):
    try:
        n = float(values[0])
    except (TypeError, ValueError, IndexError):
        return None
    return f"{n:.4f}" if abs(n) <= limit else None

def max_age(cc):
    m = re.search(r"(?:^|,)\s*max-age=(\d+)", cc or "", re.I)
    return 0 if not m or "no-store" in cc.lower() else int(m.group(1))

def problem_type(body):
    try:
        return json.loads(body).get("type", "")
    except ValueError:
        return ""

def read_body(res, deadline):
    chunks = []
    while chunk := res.read1(65536):  # whatever has arrived, so a slow drip hits the deadline
        if time.monotonic() > deadline:
            raise TimeoutError("upstream took longer than DEADLINE")
        chunks.append(chunk)
    body = b"".join(chunks)
    length = res.headers.get("Content-Length")
    if length and length.isdigit() and len(body) != int(length):
        raise http.client.IncompleteRead(body, int(length) - len(body))
    return body

def upstream(lat, lon):
    deadline = time.monotonic() + DEADLINE
    req = urllib.request.Request(f"{BASE}/v1/weather?lat={lat}&lon={lon}&{QUERY}",
                                 headers={"Authorization": f"Bearer {KEY}"})
    try:
        with urllib.request.urlopen(req, timeout=DEADLINE) as res:
            status, hdrs, body = res.status, res.headers, read_body(res, deadline)
            ttl = max_age(hdrs["Cache-Control"])
    except urllib.error.HTTPError as err:
        status, hdrs, body, ttl = err.code, err.headers, err.read(), 0
    if status == 404 and problem_type(body).endswith("outside-coverage"):
        ttl = OUTSIDE_COVERAGE_TTL
    if status == 429:
        ttl = int(hdrs["Retry-After"]) if (hdrs["Retry-After"] or "").isdigit() else 1
    headers = {k: v for k, v in hdrs.items() if PASS.match(k)}
    return (time.time() + ttl, status, headers, body)

def store(key, entry):
    global throttled
    # RateLimit-* describe one upstream call, so a stored copy keeps just the type.
    types = {k: v for k, v in entry[2].items() if k.lower() == "content-type"}
    kept = (entry[0], entry[1], types, entry[3])
    with guard:
        now = time.time()
        for k in [k for k, v in cache.items() if v[0] <= now]:
            del cache[k]
        if entry[1] == 429:
            throttled = kept
        elif entry[0] > now:
            cache[key] = kept

def weather(key, lat, lon):
    hit = cache.get(key)
    if hit and hit[0] > time.time():
        return hit
    with guard:
        hit = cache.get(key)
        if hit and hit[0] > time.time():
            return hit
        if throttled and throttled[0] > time.time():
            return throttled
        pending = inflight.get(key)
        owner = pending is None
        if owner:
            pending = inflight[key] = Pending()
    if not owner:  # another request is already calling upstream for this point
        pending.done.wait()
        if pending.error:
            raise pending.error
        return pending.entry
    try:
        pending.entry = pool.submit(upstream, lat, lon).result(timeout=DEADLINE)
        store(key, pending.entry)
        return pending.entry
    except Exception as err:
        pending.error = err
        raise
    finally:
        with guard:
            inflight.pop(key, None)
        pending.done.set()

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        url = urllib.parse.urlsplit(self.path)
        if url.path != "/weather":
            return self.send_error(404)
        got = hashlib.sha256(self.headers.get("X-App-Token", "").encode()).digest()
        if not hmac.compare_digest(got, WANT):  # constant time on equal-length digests
            return self.send_error(401, "sign in first")
        q = urllib.parse.parse_qs(url.query)
        lat, lon = coord(q.get("lat"), 90), coord(q.get("lon"), 180)
        if lat is None or lon is None:
            return self.send_error(400, "lat and lon must be numbers")
        try:
            expires, status, headers, body = weather(f"{lat},{lon}", lat, lon)
        except FAILED:
            return self.send_error(502, "weather unavailable")
        self.send_response(status)
        for name, value in headers.items():
            if not (status == 429 and name.lower() == "retry-after"):
                self.send_header(name, value)
        if status == 429:
            self.send_header("Retry-After", str(max(1, math.ceil(expires - time.time()))))
        self.end_headers()
        self.wfile.write(body)

ThreadingHTTPServer(("", 8080), Handler).serve_forever()

Both round lat and lon to 4 decimal places (about 11 m), so nearby requests share one cached answer. Other errors pass through to your app with their status and are not cached.

2. Send the recommended query

GET /v1/weather?lat=42.3601&lon=-71.0589&view=concise&days=7&hourly_hours=24&units=imperial

• view=concise returns a documented subset of the hourly[] and daily[] columns, enough for a forecast screen. The subset only grows. view=detailed (the default) returns every column.
• days=7 returns a week of daily rows, and hourly_hours=24 the next 24 hourly rows.
• units=imperial (the default) or units=metric. Read the labels from the response's units object (for example units.temperature is F or C) instead of hard-coding them.

The full list of query parameters is on the Weather endpoint page.

3. Cache each answer for its max-age

Every successful /v1/weather answer carries a Cache-Control header. Keep the body on your backend for the max-age that header gives, keyed on the coordinates and the query, and call the API again once it expires. Parse the header on each response rather than hard-coding a lifetime: the value can differ between answers, and an answer built on a degraded upstream source says no-store, which means do not cache it at all. A cached answer never reaches the API, so it does not count against your rate limit or your credits.

Error responses (application/problem+json) carry no Cache-Control, so decide per type:

• outside-coverage (404). It does not change for a point, so keep it. The backends above keep it for an hour.
• 429. Wait for Retry-After before any further call; the limit is per key, not per location.
• Others. Do not cache them.

4. Read times in the location's timezone

• hourly[].time is an ISO 8601 timestamp in UTC. Convert it to location.timezone (an IANA name such as America/New_York) for display, not to the device's timezone.
• daily[].date is a calendar date (2026-04-20) that is already local to location.timezone. Display it as is. Parsing it as a timestamp reads it as UTC midnight, which shows the previous day west of Greenwich.
• Label daily rows with relative_day (-1 yesterday, 0 today, 1 tomorrow) instead of comparing dates with the device clock. Select today by relative_day == 0, not by position: before 6 AM local, an extra relative_day: -1 row for the overnight still in progress comes first, and its high can be null.
• active_period is day or night on exactly the row that holds the current local time, and null on every other row. Use it to choose between "Today" and "Tonight".

5. Pick an icon

icon is a string slug from an open vocabulary: new slugs can appear without a new API version, so never treat the list below as closed. Each slug is a family name, sometimes followed by -day or -night. The families today are:

clear, partly-cloudy, mostly-cloudy, cloudy, showers, rain, thunder-showers, thunder-rain, thunderstorms, snow-showers, snow, rain-snow-showers, rain-snow, sleet, fog and haze.

• Suffixes. clear, partly-cloudy, mostly-cloudy, showers, thunder-showers, snow-showers and rain-snow-showers always carry -day or -night, for example partly-cloudy-night. haze can appear with or without one. The other families have none.
• Which suffix. current.icon and hourly[].icon follow the sun at the location: -day between sunrise and sunset. daily[].icon and daily[].day.icon are worked out for local noon, so they are normally day variants; daily[].night.icon is worked out for late evening, so it is normally a night variant. With view=concise, daily[].day and daily[].night carry only precip_probability: day.icon, night.icon, their conditions and narrative, and every other day/night field need view=detailed.
• Fallback. For a slug you have no artwork for, strip a trailing -day or -night, then match the longest family name the slug starts with. If nothing matches, show the row's conditions text (for example Partly Cloudy).

6. Show the attribution notice

Display the attribution.notice string from each response wherever you show its data, as returned, and link smarterweather.com/acknowledgements next to it. Read the notice from the response instead of copying it into your app, so a change to the wording reaches your users without a release. attribution.sources lists the sources that contributed, for your own records.

A point outside coverage gets a 404 with the outside-coverage problem type. Show your own "not covered" message for it, and do not retry it.

8. Look up a field

The Weather field reference lists every field of every object the /v1/weather body can carry, with its type, whether it can be null and whether it is always present, and the unit each number is in. It is generated from openapi.yaml, the full contract.