This document applies to the /forecast and /history endpoints. If you are using the Timeline Weather API (/timeline), you can find the JSON structure documented on the Time Weather API documentation page.
This article describes the JSON structure returned from the weather API. This same basic structure is returned for both weather forecast, weather history and weather history summary query types. Some data fields may not be present in all results if they do not apply.
Basic structure
The result of the API includes one or more locations with their respective weather plus also the information about the data such as the full names, units etc.
There are three main structures, which depend on the locationMode parameter.
locationMode=single
Single mode output is designed for applications that will only work with a single location for each request. In this case the structure of the output JSON is:
{
"location" : {
"values" : [...],
"id" : "Miami,FL",
"address" : "Miami,FL",
"name" : "Miami,FL",
"latitude" : 25.77481,
"longitude" : -80.19773,
},
"columns" : {
"wdir" : {}
...
}
}
locationMode=array
If you are working with multiple locations and do not need to reference the locations by id, address or other look up, then the array structure returns an ordered list of location along with their data. Note that the location elements within the array are the same structure as the location returns in single mode.
{
"locations" : [{
"values" : [...],
"id" : "Miami,FL",
"address" : "Miami,FL",
"name" : "Miami,FL",
"latitude" : 25.77481,
"longitude" : -80.19773,
},
...
],
"columns" : {
"wdir" : {}
...
}
}
locationMode=lookup (default if no locationMode is provided)
If your application is dealing with many locations and you require a fast look up of location based of id, name or address, then the lookup mode will function best. In ‘lookup’ mode, the locations property contains a map of location objects based off their id or address. The location instances themselves are the same structure as previous locationMode parameters.
{
"locations" : {
"Miami,FL" :
{
"stationContributions" : null,
"values" : [...],
"id" : "Miami,FL",
"address" : "Miami,FL",
"name" : "Miami,FL",
"index" : 0,
"latitude" : 25.77481,
"longitude" : -80.19773,
},
....
},
"columns" : {
"wdir" : {}
...
}
}
Location object
Each location object contains the weather data for the location along with some additional location information. The location information returned includes the location address, id and name.
In simple requests, the id and name are set to the same value whereas in more advanced requests they may be specified by the caller. For example the name might be a store name, address the address of the store and the id the id within a database system. Also include are the latitude and longitude used for the lookup.
For historical data requests, each location also includes details of the weather stations used for the weather data look up.
Finally the values array return the actual weather data values. Each of these values represent a single time period within the data. For each hour or day in an hourly or daily forecast. In the case of history summary the period may be week, month or year.
Current conditions
Weather forecast requests for single locations include the current conditions as property ‘currentConditions’ of the location object.
The currentConditions property resembles a single row of the forecast or history values area.
"id" : "Sterling, VA, United States",
"address" : "Sterling, VA, United States",
"name" : "Sterling, VA, United States",
"latitude" : 39.03335,
"longitude" : -77.40711,
"currentConditions" : {
"wdir" : 127.0,
"temp" : 71.0,
"sunrise" : "2020-02-28T05:47:23-04:00",
"moonphase" : 0.47,
"visibility" : null,
"wspd" : 2.0,
"icon" : "rain",
"stations" : "EW4757 Potomac Falls VA US(Id=E4757,0.8mi)",
"heatindex" : null,
"cloudcover" : null,
"datetime" : "2020-02-28T08:46:38-04:00",
"precip" : 0.1,
"snowdepth" : null,
"sealevelpressure" : null,
"dew" : 69.2,
"sunset" : "2020-05-22T20:27:02-04:00",
"humidity" : 94.0,
"wgust" : 11.0,
"windchill" : null
},
Columns lookup
Each column of data within the array of data values has a details column in the columns object. The weather data values use the short variable id such as ‘maxt’ for brevity. The column look up object allows the developer to look up a full name (“Maximum Temperature”) and the unit type (degF).
Other properties within this object should not be used at this time.
"maxt" : {
"id" : "maxt",
"name" : "Maximum Temperature",
"unit" : "degF",
},
Weather Data Values
Each location will return an array of weather data values in the values array. Each value returns the weather data for a single period of time:
{
"wdir" : 177.5,
"temp" : 78.1,
"maxt" : 80.0,
"wspd" : 11.9,
"resolvedAddress" : "Miami,FL",
"cloudcover" : 65.6,
"heatindex" : null,
"pop" : 5.0,
"mint" : 76.0,
"datetime" : 1583193600000,
"precip" : 0.0,
"sealevelpressure" : 1016.9,
"snowdepth" : 0.0,
"snow" : 0.0,
"humidity" : 77.1,
"wgust" : 20.8,
"conditions" : "Partially cloudy",
"windchill" : null
},
For more information on how dates and times are returned in the Weather API results, see Dates and Times in the Weather API.
These details of the weather data, how they are calculated and other information about the weather data values are described in the Weather Data Documentation.