Blog·Craft·

Where the weather reading came from

A weather response includes when the observation was made and how far away its station is, so the reading has some context.

When you ask for the weather at your house, the temperature usually comes from a weather station somewhere nearby. Your coordinates tell the API where to look. They don't mean a thermometer took a reading at that exact spot.

That distinction is easy to lose when the entire answer is one big temperature on a screen. It matters if the station is several kilometers away, or if the latest reading is older than the person looking at it expects.

The /weather response keeps the reading and its context in three objects. current contains the measurements, including temperature, humidity, wind, and observed_at. station identifies the station and gives its distance from your coordinates. source names the agency behind the observation.

observed_at is the time the observation was made. It doesn't become a new reading just because your app fetched it again. If you're storing weather alongside an event, keeping that timestamp lets you distinguish when the event happened from when the nearby weather was measured.

The station distance has a similar job. A value can be useful without being a measurement of your exact location. Your application can show the station name, include an "observed at" label, or decide that a distant reading isn't suitable for the feature you're building.

Forecasts sit separately inside deep, when requested and available. That keeps a measured temperature and a predicted temperature from looking interchangeable as the response grows. The current reading remains something you can trace back to a place and time.