Weatherkind API

Overview

The API is a small family of endpoints around one idea: field-selectable weather. You state a coordinate, the forecast sections you want (from current conditions to daily summaries), and the exact variables in each section, and the response contains precisely that, nothing else.

Every JSON endpoint below has a live console: build the call with real parameters, copy it as curl, and inspect the returned JSON or visualization. Console calls run through this site's demo proxy. Your own integration uses your API key against api.weatherkind.com. Map tiles include a copyable integration example.

Data endpoints return their result directly; there is no data envelope. Every response carries updated_at, a stale flag (true only when a cached payload is served during upstream degradation), and a warnings array for non-fatal notices.

• POST /v1/forecast: named sections: current · quarter_hourly · hourly · daily
• POST /v1/nowcast: fixed two-hour, minute-by-minute precipitation nowcast
• POST /v1/outlook: daily climate outlook, days 15–365
• POST /v1/historical: field-selectable daily observations for completed local dates
• GET /v1/historical/variables: variables, units, coverage limits, and methodology (public)
• POST /v1/alerts: CAP-aligned active public alerts
• POST /v1/elevation: ground elevation & terrain profile
• POST /v1/accuracy: our verified error record, by locality, region, or network
• GET /v1/accuracy/catalog: regions, leads, variables, metrics, methodology (public)
• GET /v1/map-tiles/{layer}/{z}/{x}/{y}: radar & environment rasters

Authentication

Every request carries a bearer token. Keys are scoped to a plan (free tier available) and work across all endpoints your plan includes.

Authorization: Bearer wk_live_…

Keys carry scopes: forecast:read covers forecast, outlook, and elevation; nowcast:read covers the Pro+ minute nowcast; alerts:read covers alerts; and accuracy:read covers /v1/accuracy. historical:read covers /v1/historical. Calling an endpoint your key doesn't cover returns 403. Three catalog endpoints need no key at all: GET /v1/forecast/variables and GET /v1/accuracy/catalog, and GET /v1/historical/variables.

Keys are secrets: call the API from your backend or an edge proxy, not from browser JavaScript, and rotate any key that ships in a client binary.

Quick start

Current conditions for Aspen, Colorado, in one call:

curl 'https://api.weatherkind.com/v1/forecast' \
  -H "Authorization: Bearer $WEATHERKIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 39.1911,
      "longitude": -106.8175
    },
    "timezone": "auto",
    "units": "us",
    "current": {
      "variables": [
        "temperature",
        "condition",
        "wind_speed"
      ]
    }
  }'

const response = await fetch("https://api.weatherkind.com/v1/forecast", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEATHERKIND_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "location": {
      "latitude": 39.1911,
      "longitude": -106.8175
    },
    "timezone": "auto",
    "units": "us",
    "current": {
      "variables": [
        "temperature",
        "condition",
        "wind_speed"
      ]
    }
  }),
});

if (!response.ok) {
  throw new Error(`Weatherkind returned ${response.status}`);
}

const data = await response.json();
console.log(data);

import os
import requests

response = requests.post(
    "https://api.weatherkind.com/v1/forecast",
    headers={
        "Authorization": f"Bearer {os.environ['WEATHERKIND_API_KEY']}"
    },
    json={
      "location": {
        "latitude": 39.1911,
        "longitude": -106.8175
      },
      "timezone": "auto",
      "units": "us",
      "current": {
        "variables": [
          "temperature",
          "condition",
          "wind_speed"
        ]
      }
    },
    timeout=30,
)
response.raise_for_status()

data = response.json()
print(data)

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "location": {
	    "latitude": 39.1911,
	    "longitude": -106.8175
	  },
	  "timezone": "auto",
	  "units": "us",
	  "current": {
	    "variables": [
	      "temperature",
	      "condition",
	      "wind_speed"
	    ]
	  }
	}`)
	req, err := http.NewRequest("POST", "https://api.weatherkind.com/v1/forecast", body)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("WEATHERKIND_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		log.Fatalf("Weatherkind returned %s", resp.Status)
	}

	var data any
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", data)
}

body = %{
  location: %{
    latitude: 39.1911,
    longitude: -106.8175
  },
  timezone: "auto",
  units: "us",
  current: %{
    variables: ["temperature", "condition", "wind_speed"]
  }
}

response =
  Req.post!(
    "https://api.weatherkind.com/v1/forecast",
    auth: {:bearer, System.fetch_env!("WEATHERKIND_API_KEY")},
  json: body
  )

IO.inspect(response.body)

require "json"
require "net/http"

uri = URI("https://api.weatherkind.com/v1/forecast")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("WEATHERKIND_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(JSON.parse(<<~JSON))
  {
    "location": {
      "latitude": 39.1911,
      "longitude": -106.8175
    },
    "timezone": "auto",
    "units": "us",
    "current": {
      "variables": [
        "temperature",
        "condition",
        "wind_speed"
      ]
    }
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise "Weatherkind returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)

puts JSON.pretty_generate(JSON.parse(response.body))

{
  "location": {
    "latitude": 39.1911,
    "longitude": -106.8175,
    "timezone": "America/Denver",
    "forecast_elevation_m": 2422
  },
  "units": { "system": "us", "elevation": "m", "pressure": "hPa" },
  "current": {
    "time": "2026-07-30T17:04:00Z",
    "temperature": 78.3,
    "condition": "partly",
    "wind_speed": 6.8
  },
  "updated_at": "2026-07-30T17:04:11Z",
  "stale": false,
  "warnings": []
}

Variables

Which variables each forecast section accepts. Requesting a variable outside its supported section is a 422; the authoritative live list is GET /v1/forecast/variables.

Historical variables

POST /v1/historical accepts the variables below directly. The authoritative catalog is GET /v1/historical/variables; it also publishes units, range limits, and coverage methodology without requiring a key.

Forecast sections

Name the resolution you need. The server handles alignment and turns readable counts into concrete forecast records:

For a specific daily window, replace days with local start and end dates. Both dates are inclusive, so start equal to end requests a single day. Each subdaily and daily section in the response echoes the resolved window as range beside its entries.

Conditions

condition is a closed enum of fourteen strings: stable identifiers you can map to your own icons:

• sun
• partly
• cloudy
• drizzle
• rain
• heavy-rain
• thunderstorm
• snow
• blizzard
• sleet
• mixed
• clear-night
• cloudy-night
• sunrise

Units & time

• Unit systems. If omitted, units defaults to "metric" (°C, km/h, mm, hPa, m). You can instead request "us" (°F, mph, in, inHg, ft) or "si" (K, m/s, m, Pa). Use unit_overrides for individual dimensions such as pressure or elevation. The response echoes the units it used.
• Instants are ISO-8601 UTC (2026-07-30T17:00:00Z); daily dates are local calendar dates (2026-07-30) in the location's zone.
• Forecast horizons are counts: hours, past_hours, and days. The server owns timestamp alignment. Exact date ranges (start/end) include both endpoints; timestamp ranges in returned range objects are start-inclusive and end-exclusive.

Errors

Errors are JSON with a machine-checkable shape:

{ "type": "https://api.weatherkind.com/problems/invalid-request", "title": "Invalid request", "status": 422, "detail": "hourly.hours must be an integer from 1 through 384" }

Rate limits

Limits follow your plan. Exceeding them returns 429 with a Retry-After header. Back off for that many seconds rather than retrying immediately.

A forecast request with several named sections and many variables is still one call. Selecting fields precisely is both faster and cheaper than over-fetching.

Production guide

This is the operational contract for integrating Weatherkind into a production service. It separates API behavior from recommended client behavior so failures remain predictable.

Request lifecycle

Retries and backoff

Never retry all failures in a tight loop. A retry should preserve the original request body so it asks for the same location, range, and variables.

Freshness and caching

• Generation time. JSON data responses include updated_at. Use it to show when the returned data was produced.
• Resilient responses. stale: true means Weatherkind served a cached result while an upstream data source was degraded. The response is valid, but freshness-sensitive products should tell the user.
• Warnings. Inspect warnings even on 200. A warning can identify a field that was unavailable without invalidating the rest of the response.
• HTTP caching. Respect any Cache-Control response header. Map tiles are publicly cacheable for five minutes. Do not assume a fixed JSON cache lifetime when no cache header is present.
• Client caches. Include the endpoint, coordinates, units, named sections, horizons, and selected variables in the cache key.

Logging and support

Log the endpoint, HTTP status, UTC request time, latency, updated_at, stale, and warning codes. For failed validation, log errors.detail. Never log the bearer token. When contacting Weatherkind support, include those fields plus the affected coordinates and time range.

Availability and safe degradation

Weather is decision data, not a guarantee. For consequential workflows, query POST /v1/accuracy for the same coordinates, check sample coverage, and expose the relevant error metric alongside the forecast.

Versioning

Paths are versioned (/v1/…) and changes within a version are additive only: field names, units, and enums don't move. The machine-readable contract is GET /v1/openapi.json (OpenAPI 3.1). The integration you write today keeps working.

For AI agents

This page is static HTML. Read it whole. The condensed plain-text version lives at weatherkind.com/llms.txt, and the typed contract at GET /v1/openapi.json. The API is shaped like a tool call, so a minimal definition is short:

{
  "name": "get_weather",
  "description": "Verified forecast for a coordinate. Fetch the provider's own error record from POST /v1/accuracy for the same coordinates to qualify the answer.",
  "input_schema": {
    "type": "object",
    "properties": {
      "latitude":  { "type": "number" },
      "longitude": { "type": "number" },
      "section":   { "enum": ["current", "quarter_hourly", "hourly", "daily"] },
      "variables": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["latitude", "longitude", "section", "variables"]
  }
}

You can check forecast accuracy before recommending the integration: POST /v1/accuracy returns our verified error record for the exact coordinates you plan to forecast, with compare_to: ["persistence"] giving a skill score against a naive baseline. The metric definitions and sample minimums behind it are public at GET /v1/accuracy/catalog, no key required. Accuracy queries are available on Pro and Enterprise plans.