Conditions
https://data.api.xweather.com/conditions/The conditions endpoint provides interpolated global current, forecast, and historical weather conditions and up to 60 minutes of minutely precipitation forecast. Data is generated for the location and time requested, leveraging a proprietary blend of data, including weather station observations, radar & satellite information, global & regional models, and other proprietary sources.
Passing no parameter modifiers provides the conditions for the current time. Utilizing just the for parameter provides conditions at a specific point in time, and utilizing both the from/to parameters provides hourly increments.
Minutely precipitation forecasts are available in one-minute intervals for the next 60 minutes for locations globally (with higher-resolution coverage available in select geographies) by utilizing filter=minutelyprecip.
Historical conditions are available from April 2011 through today.
Hourly conditions allows up to 1 month of hourly data to be returned in a single query. Please note, each day will cost an API access, including partial days. For example, querying 60 hours worth of data (2.5 days) will cost 3 API accesses.
Minutely data can be retrieved for up to 24 hours in a single query. Each hour of minutely data, including partial hours, will count as a single API access. For example, 90 minutes of minutely data (1.5 hours) will cost 2 API accesses.
View our engineers’ walk-through (opens in a new tab) of the conditions endpoint in the release blog.
Requests
Every request to the endpoint must include one of the supported actions in the url.
https://data.api.xweather.com/conditions/{action}?client_id={client_id}&client_secret={client_secret}&{params}Supported Actions
The following actions are supported with the /conditions endpoint:
| Action | Description |
|---|---|
| :id | Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more. |
| route | Type: stringAllows you to pass several coordinates along a custom route to return data points at each location. Learn more. |
Response
The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.
Properties
loc.lat (number)
The latitude coordinate of the record.
loc.long (number)
The place or nearest place to the record.
place.name (string)
The place or nearest place to the record.
place.state (string)
The state abbreviation in which the record is located. This may be null depending on the country.
place.country (string)
The 2 letter ISO-3166 country abbreviation in which the response is located.
periods.#.timestamp (number)
The unix timestamp of the time of the condition
periods.#.dateTimeISO (string)
The ISO 8601 date/time of the condition
periods.#.tempC (number)
The temperature in Celsius. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.tempF (number)
The temperature in Fahrenheit. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.feelslikeC (number)
The feels-like / apparent temperature in Celsius. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
The feels-like temperature is often based on a combination of the NOAA heat index and/or wind chill specifications.
Locations with a temperature of 80F (26.67C) or higher will high humidity will have a feels-like temperature higher than the air temperature. Likewise, locations with a temperature of 40F (4.44C) and lower winds speeds of 3 mph or higher will often have a feels like temperature less than the air temperature.
periods.#.feelslikeF (number)
The feels-like / apparent temperature in Fahrenheit. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
The feels-like temperature is often based on a combination of the NOAA heat index and/or wind chill specifications.
Locations with a temperature of 80F (26.67C) or higher will high humidity will have a feels-like temperature higher than the air temperature. Likewise, locations with a temperature of 40F (4.44C) and lower winds speeds of 3 mph or higher will often have a feels like temperature less than the air temperature.
periods.#.dewpointC (number)
The dew point in Celsius. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.dewpointF (number)
The dew point in Fahrenheit. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.humidity (number)
The relative humidity, from 0 - 100. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.pressureMB (number)
The mean sea level pressure (MSLP) in millibars. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.pressureIN (number)
The mean sea level pressure (MSLP) in inches mercury (inHg). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.spressureMB ()
The surface pressure in millibars. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.spressureIN ()
The surface pressure in inches mercury (inHg). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.altimeterMB ()
The altimeter value in millibars. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.altimeterIN ()
The altimeter value in inches mercury (inHg). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windDir (string)
The wind direction, Null if unavailable:
Not returned with minutely precipitation forecasts (filter=minutelyprecip.
Possible values:
- N - North
- NNE - North northeast
- NE - Northeast
- ENE - East northeast
- E - East
- ESE - East southeast
- SE - Southeast
- SSE - South southeast
- S - South
- SSW - South southwest
- SW - Southwest
- WSW - West southwest
- W - West
- WNW - West northwest
- NW - Northwest
- NNW - North northwest
periods.#.windDirDEG (number)
The wind speed in degrees (from 0 to 360). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windSpeedKTS (number)
The wind speed in knots. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windSpeedKPH (number)
The wind speed in kilometers per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windSpeedMPH (number)
The wind speed in miles per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windSpeedMPS (number)
The wind speed in meters per second. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustKTS (number)
The wind gusts in knots. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustKPH (number)
The wind gusts in kilometers per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustMPH (number)
The wind gusts in miles per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustMPS (number)
The wind gusts in meters per second. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.precipMM (number)
The estimated precipitation over the selected period and is fluid based on the value passed into the filter parameter.
The default is mm/hour for hourly and point in time requests.
However, if making a sub-hourly request, the value will be the amount over the minutely interval selected. For example, 1-minute intervals will be for 1 minute. If filter=15min is utilized, then it will be the total over each 15-minute interval in the response.
Null if unavailable.
periods.#.precipIN (number)
The estimated precipitation over the selected period and is fluid based on the value passed into the filter parameter.
The default is in/hour for hourly and point in time requests.
However, if making a sub-hourly request, the value will be the amount over the minutely interval selected. For example, 1-minute intervals will be for 1 minute. If filter=15min is utilized, then it will be the total over each 15-minute interval in the response.
Null if unavailable
periods.#.precipRateMM (number)
The precipitation rate in mm/hour at the point in time of the period.
Null if unavailable.
periods.#.precipRateIN (number)
The precipitation rate in inches/hour at the point in time of the period.
Null if unavailable.
periods.#.snowCM (number)
The estimated snowfall over the selected period and is fluid based on the value passed into the filter parameter.
The default is cm/hour for hourly and point in time requests.
However, if making a sub-hourly request, the value will be the amount over the minutely interval selected. For example, 1-minute intervals will be for 1 minute. If filter=15min is utilized, then it will be the total over each 15-minute interval in the response.
Null if unavailable.
periods.#.snowIN (number)
The estimated snowfall over the selected period and is fluid based on the value passed into the filter parameter.
The default is in/hour for hourly and point in time requests.
However, if making a sub-hourly request, the value will be the amount over the minutely interval selected. For example, 1-minute intervals will be for 1 minute. If filter=15min is utilized, then it will be the total over each 15-minute interval in the response.
Null if unavailable
periods.#.snowRateCM (number)
The snowfall rate in cm/hour at the point in time of the period.
Null if unavailable.
periods.#.snowRateIN (number)
The snowfall rate in inches/hour at the point in time of the period.
Null if unavailable.
periods.#.snowDepthCM (number)
The estimated snow depth in cm at the point in time of the period. Historical data for snow depth is available after September, 7th 2023.
Null if unavailable.
periods.#.snowDepthIN (number)
The estimated snow depth in inches at the point in time of the period. Historical data for snow depth is available after September, 7th 2023.
Null if unavailable.
periods.#.pop (number)
Probability of precipitation. A percentage from 0 - 100%. Available for requests for the current time and forecast requests. Null for archive requests or if unavailable.
periods.#.visibilityKM (number)
The visibility in kilometers. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.visibilityMI (number)
The visibility in miles. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.sky (number)
The percentage of the clouds in the sky. From 0 - 100. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.cloudsCoded (string)
Coded version of cloud conditions. See the Coded Weather documentation for code options. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.weather (string)
Phrase of weather conditions. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.weatherCoded (string)
Coded version of weather conditions. See the Coded Weather documentation for code options. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.weatherPrimary (string)
hrase of the primary weather conditions. Null if unavailable.
periods.#.weatherPrimaryCoded (string)
Coded version of the primary weather conditions. See the Coded Weather documentation for code options. Null if unavailable.
periods.#.icon (string)
Icon name corresponding to the primary weather conditions.
periods.#.solradWM2 (number)
(Deprecated) Estimated 1-hour global solar radiation in watts/meter squared.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
Note: Utilize periods.#.solrad.ghiWM2
periods.#.uvi (number)
Ultraviolet Index (from 1 to 12). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.isDay (boolean)
Signifies if the observation occurred during daily hours. True if between sunrise and sunset, false otherwise.
periods.#.solrad.azimuthDEG (number)
The solar azimuth angle.
periods.#.solrad.zenithDEG (number)
The solar zenith angle.
periods.#.solrad.ghiWM2 (number)
Estimated 1-hour Global Horizontal Irradiance (global solar radiation) in watts/meter squared.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.solrad.dniWM2 (number)
Estimated 1-hour Direct Normal Irradiation in watts/meter squared.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.solrad.dhiWM2 (number)
Estimated 1-hour Diffused Horizontal Irradiance in watts/meter squared.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
profile.tz (string)
Timezone name of the location.
profile.tzname (string)
The timezone abbreviation for the location.
profile.tzoffset (number)
The timezone offset for the location in seconds.
profile.isDST (boolean)
True if the location is currently observing Daylight Savings Time (DST), otherwise false.
profile.elevFT ()
The elevation of the location in feet.
profile.elevM ()
The elevation of the location in meters.
[
{
"loc": {
"lat": 47.38908,
"long": -122.4594
},
"place": {
"name": "burton",
"state": "wa",
"country": "us"
},
"periods": [
{
"timestamp": 1702503660,
"dateTimeISO": "2023-12-13T13:41:00-08:00",
"tempC": 10.09,
"tempF": 50.16,
"feelslikeC": 10.09,
"feelslikeF": 50.16,
"dewpointC": 7.19,
"dewpointF": 44.94,
"humidity": 82,
"pressureMB": 1016,
"pressureIN": 30,
"windDir": "S",
"windDirDEG": 185,
"windSpeedKTS": 1.32,
"windSpeedKPH": 2.45,
"windSpeedMPH": 1.52,
"windSpeedMPS": 0.68,
"windGustKTS": 1.87,
"windGustKPH": 3.46,
"windGustMPH": 2.15,
"windGustMPS": 0.96,
"precipMM": 0,
"precipIN": 0,
"precipRateMM": 0,
"precipRateIN": 0,
"snowCM": 0,
"snowIN": 0,
"snowRateCM": 0,
"snowRateIN": 0,
"snowDepthCM": 0,
"snowDepthIN": 0,
"pop": 0,
"visibilityKM": 16,
"visibilityMI": 9.942,
"sky": 81,
"cloudsCoded": "BK",
"weather": "Mostly Cloudy",
"weatherCoded": "::BK",
"weatherPrimary": "Mostly Cloudy",
"weatherPrimaryCoded": "::BK",
"icon": "mcloudy.png",
"solradWM2": 156,
"uvi": 0,
"isDay": true,
"spressureMB": null,
"spressureIN": null,
"altimeterMB": null,
"altimeterIN": null,
"solrad": {
"azimuthDEG": 203.0745,
"zenithDEG": 73.8207,
"ghiWM2": 155.7844,
"dniWM2": 188.4811,
"dhiWM2": 103.2653
}
}
],
"profile": {
"tz": "America/Los_Angeles",
"tzname": "PST",
"tzoffset": -28800,
"isDST": false,
"elevFT": null,
"elevM": null
}
}
]