Weather API

Overview

The response holds up to four blocks: the conditions now, a 60 minute rain forecast, 240 hourly rows, and 10 daily rows.

Build a request

curl "https://graysky.net/free/v1/forecast/42.35,-71.05?dataSets=current,daily"

const response = await fetch('https://graysky.net/free/v1/forecast/42.35,-71.05?dataSets=current,daily');
const forecast = await response.json();
console.log(forecast.current);

import requests

forecast = requests.get("https://graysky.net/free/v1/forecast/42.35,-71.05?dataSets=current,daily").json()
print(forecast["current"])

Endpoint

$ curl "https://graysky.net/free/v1/forecast/42.35,-71.05?dataSets=current,hourly,daily"

The coordinate cell

The service moves your position to a 0.05 degree cell. A cell is about 5.5 km across. The response header X-Gc-Grid shows the cell. Example: the point 42.3601,-71.0589 becomes the cell 42.35,-71.05.

Query parameters

The service ignores an unknown query parameter. A link with ?utm_source= works. The service resolves the time zone from the coordinate and returns it in location.timezone. Do not send a timezone parameter.

Data blocks

The dataSets parameter selects the blocks. Each block is one part of the response. See Response format for the shared field rules.

Two gaps to know. pressureMb is in the current block only. Precipitation is one precipMm amount plus a precipType value; there are no separate rain, shower, and snowfall fields.

Response format

The response is one JSON object with location, meta, and the blocks you requested. These rules hold everywhere:

• SI on the wire. Values are metric with a unit suffix: temperatureC, windSpeedMs, precipMm. The imperial option adds companion fields. It removes nothing. See Units.
• RFC 3339 timestamps. Each time field is an RFC 3339 string with an explicit offset, not a Unix epoch.
• Percentages are 0-100. humidityPercent, cloudCoverPercent, precipChancePercent.
• Wind comes paired. windDirectionDeg (0-360) and windDirectionCardinal (for example SW).
• Conditions are an enum. conditionCode is a fixed string with a human conditionLabel beside it. See condition codes.
• Nullable, not absent. A field with no data is null, not dropped. A decoder can rely on the shape.

location

meta

Condition codes

conditionCode is one value from a fixed set. New values are additive. Treat an unknown value as cloudy. The current set:

clear-day, clear-night, mostly-clear-day, mostly-clear-night, partly-cloudy-day, partly-cloudy-night, mostly-cloudy-day, mostly-cloudy-night, cloudy, rain, sleet, snow, wind, fog, hail, thunderstorm, scattered-thunderstorms, isolated-thunderstorms, tornado, limited.

limited marks a degraded entry. The validAt is valid, but the numeric fields are null, because every model source ran out of coverage for that lead. Show "data unavailable", not a zero.

The machine-readable contract is /dev/openapi.yaml (OpenAPI 3.1).

Units

A companion appears only when the SI source field is present. A null SI value makes a null imperial value. The API never invents a number.

SI to imperial companion map

Response headers

The service sends Access-Control-Allow-Origin: *. A browser page can call the API directly.

Errors

Each error is an RFC 9457 Problem Details object with Content-Type: application/problem+json:

{
  "type": "https://graysky.net/dev#bad-coordinate",
  "title": "Bad Request",
  "status": 400,
  "detail": "The path needs latitude,longitude in degrees. Example: /free/v1/forecast/42.35,-71.05",
  "traceId": "8f1c2a7d9e3b4c01-BOS"
}

The type URI ends with one of these fragments:

Good fits

• Fixed displays. A Raspberry Pi panel, a smart mirror, a desk widget, or a lamp that turns blue before rain.
• Home automation. A Home Assistant sensor. Skip the irrigation when today's precipMm is above 2. Close the blinds when uvIndex passes 7.
• A rain warning for one place. The minutely block holds 61 per-minute rows. Use it to warn yourself 20 minutes before the rain starts.
• Classroom projects. For students building web apps that work on the first try.
• Chat bots. A bot that posts one daily forecast for one town.
• Personal scripts. A shell prompt, a terminal weather command, or a morning cron job.
• Garden and sensor logs. Log the forecast rain total (precipMm) for one yard. Or compare a home weather station's own readings with the forecast.

Poor fits

These uses empty the shared budget, or the rules do not permit them.

Limits and rules

This API needs no key and no account. It has rules.

Caching

The service caches each answer at the edge. A cache hit does not use the shared budget. A repeat of a warm cell costs the service almost nothing.

The Cache-Control header shows how long an answer stays fresh. Keep each answer for at least that time. An answer with the minutely block stays fresh for about 2 minutes. All other answers stay fresh for about 10 minutes.

Data sources

GraySky makes the forecast with a proprietary multi-model engine. The engine blends these inputs:

• Short-term models. Kilometer-scale numerical models over North America. They power the first 48 hours of the hourly block and most of the current block.
• Global models. Two independent global models make the 2 to 10 day outlook in the daily block and the second half of the hourly block.
• Live radar. Radar mosaics over the United States and Europe feed our nowcaster. The nowcaster makes the minutely block.
• Surface observations. Tens of thousands of stations feed our verification pipeline. The pipeline trains the calibration layer.

We add three layers on top:

• Bias calibration. We correct temperatures with per-city tables. We fit the tables each night against station observations. We recalibrate rain probabilities each night against radar truth.
• Model blending. Where two models disagree, we use the model with the better score for that location and that variable.
• Plain-language summaries. A deterministic rule set writes the summary fields from the numbers. No generative model writes them.

Refresh cadence

Coverage

FAQ

Do I need an API key?

No. Send the request. There is no key, no account, and no sign-up.

Can I call the API from a browser page?

Yes. The service sends CORS headers. A page on any origin can call the API. The rules also apply to a page.

Is there an SDK?

No. The API is plain HTTP and JSON. Every language can call it. To get a typed client, generate one from /dev/openapi.yaml with an OpenAPI 3.1 tool.

What is the coverage outside the United States?

The current, hourly, and daily blocks are global. The minutely block covers the United States and Europe.

Can I use the data in a commercial product?

No. The free API is for non-commercial work only. For commercial use, email [email protected].

Can I republish the data?

Show the data to your users, with credit to GraySky. Do not mirror the API. Do not sell the raw JSON.

How do I contact you?

Email [email protected]. Include the traceId from the error response when you report a problem.