Forecasts
https://data.api.xweather.com/forecasts/The forecasts endpoint/data set provides up to 15-day forecasts for US and international locations. Forecast information is available in daily, day/night, and custom (such as 3-hour or 1-hour) intervals.
Requests
Every request to the endpoint must include one of the supported actions in the url.
https://data.api.xweather.com/forecasts/{action}?client_id={client_id}&client_secret={client_secret}&{params}Supported Actions
The following actions are supported with the /forecasts 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 (object)
The location of the record.
loc.long (number)
The place or nearest place to the record.
loc.lat (number)
The latitude coordinate of the record.
interval (string)
The interval of the forecast periods.
place (object)
Object containing information about 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 (array)
Array of forecast periods.
periods.#.timestamp (number)
The UNIX timestamp of the forecast valid time.
periods.#.validTime (string)
(Deprecated) Use dateTimeISO instead.
periods.#.dateTimeISO (string)
The ISO-8601 date and time string of the forecast valid time.
periods.#.maxTempC (number)
The maximum temperature in degrees Celsius. When using `filter=daynight`, this value will be NULL for nighttime periods.
periods.#.maxTempF (number)
The maximum temperature in degrees Fahrenheit. When using `filter=daynight`, this value will be NULL for nighttime periods.
periods.#.minTempC (number)
The minimum temperature in degrees Celsius. When using `filter=daynight`, this value will be NULL for daytime periods.
periods.#.minTempF (number)
The minimum temperature in degrees Fahrenheit. When using `filter=daynight`, this value will be NULL for daytime periods.
periods.#.avgTempC (number)
The average temperature for the period in degrees Celsius.
periods.#.avgTempF (number)
The average temperature for the period in degrees Fahrenheit.
periods.#.tempC (number)
The temperature in degrees Celsius for the valid time. When using `filter=day`, `filter=mdnt2mdnt`, or `filter=daynight`, this value will be NULL.
periods.#.tempF (number)
The temperature in degrees Fahrenheit for the valid time. When using `filter=day`, `filter=mdnt2mdnt`, or `filter=daynight`, this value will be NULL.
periods.#.maxFeelslikeC (number)
The maximum feels like temperature for the periods in degrees Celsius.
periods.#.maxFeelslikeF (number)
The maximum feels like temperature for the period in degrees Fahrenheit.
periods.#.minFeelslikeC (number)
The minimum feels like temperature for the period in degrees Celsius.
periods.#.minFeelslikeF (number)
The minimum feels like temperature for the period in degrees Fahrenheit.
periods.#.avgFeelslikeC (number)
The average feels like temperature for the period in degrees Celsius.
periods.#.avgFeelslikeF (number)
The average feels like temperature for the period in degrees Fahrenheit.
periods.#.feelslikeC (number)
The feels like temperature for the valid time in degrees Celsius.
periods.#.feelslikeF (number)
The feels like temperature for the valid time in degrees Fahrenheit.
periods.#.maxDewpointC (number)
The maximum dew point for the period in degrees Celsius.
periods.#.maxDewpointF (number)
The maximum dew point for the period in degrees Fahrenheit.
periods.#.minDewpointC (number)
The minimum dew point for the period in degrees Celsius.
periods.#.minDewpointF (number)
The minimum dew point for the period in degrees Fahrenheit.
periods.#.avgDewpointC (number)
The average dew point for the period in degrees Celsius.
periods.#.avgDewpointF (number)
The average dew point for the period in degrees Fahrenheit.
periods.#.dewpointC (number)
The dew point for the valid time in degrees Celsius.
periods.#.dewpointF (number)
The dew point for the valid time in degrees Fahrenheit.
periods.#.maxHumidity (number)
The maximum relative humidity for the period in percent, 0-100.
periods.#.minHumidity (number)
The minimum relative humidity for the period in percent, 0-100.
periods.#.humidity (number)
The relative humidity for the valid time in percent, 0-100.
periods.#.pop (number)
The probability of precipitation for the period in percent, 0-100.
periods.#.precipMM (number)
The amount of precipitation expected for the period in millimeters. The total liquid equivalent of all precipitation.
periods.#.precipIN (number)
The amount of precipitation expected for the period in inches. The total liquid equivalent of all precipitation.
periods.#.iceaccum (number)
(DEPRECATED) Use iceaccumMM and iceaccumIN instead.
periods.#.iceaccumMM (number)
The amount of ice accretion/accumulation expected for the period in millimeters. Available for the US only out 48 hours.
periods.#.iceaccumIN (number)
The amount of ice accretion/accumulation expected for the period in inches. Available for the US only out 48 hours.
periods.#.snowCM (number)
The amount of accumulated snow fall expected for the period in centimeters.
periods.#.snowIN (number)
The amount of accumulated snow fall expected for the period in inches.
periods.#.pressureMB (number)
The mean sea level pressure for the period in millibars.
periods.#.pressureIN (number)
The mean sea level pressure for the period in inches.
periods.#.windDir (string)
The wind direction for the valid time in cardinal notation. N, S, SE, NNW, etc.
periods.#.windDirDEG (number)
The wind direction for the valid time in degrees. 0-359, where 0 is north and 180 is south.
periods.#.windSpeedKTS (number)
The wind speed for the valid time in knots.
periods.#.windSpeedKPH (number)
The wind speed for the valid time in kilometers per hour.
periods.#.windSpeedMPH (number)
The wind speed for the valid time in miles per hour.
periods.#.windSpeedMPS (number)
The wind speed for the valid time in meters per second.
periods.#.windGustKTS (number)
periods.#.windGustKPH (number)
The wind gust for the valid time in kilometers per hour.
periods.#.windGustMPH (number)
The wind gust for the valid time in miles per hour.
periods.#.windGustMPS (number)
The wind gust for the valid time in meters per second.
periods.#.windDirMax (string)
The wind direction at the time of the maximum wind speed for the period in cardinal notation. N, S, SE, NNW, etc.
periods.#.windDirMaxDEG (number)
The wind direction at the time of the maximum wind speed for the period in degrees. 0-359, where 0 is north and 180 is south.
periods.#.windSpeedMaxKTS (number)
The maximum wind speed for the period in knots.
periods.#.windSpeedMaxKPH (number)
The maximum wind speed for the period in kilometers per hour.
periods.#.windSpeedMaxMPH (number)
The maximum wind speed for the period in miles per hour.
periods.#.windSpeedMaxMPS (number)
The maximum wind speed for the period in meters per second.
periods.#.windDirMin (string)
The wind direction at the time of the minimum wind speed for the period in cardinal notation. N, S, SE, NNW, etc.
periods.#.windDirMinDEG (number)
The wind direction at the time of the minimum wind speed for the period in degrees. 0-359, where 0 is north and 180 is south.
periods.#.windSpeedMinKTS (number)
The minimum wind speed for the period in knots.
periods.#.windSpeedMinKPH (number)
The minimum wind speed for the period in kilometers per hour.
periods.#.windSpeedMinMPH (number)
The minimum wind speed for the period in miles per hour.
periods.#.windSpeedMinMPS (number)
The minimum wind speed for the period in meters per second.
periods.#.windDir80m (string)
The wind direction at 80 meters for the valid time in cardinal notation. N, S, SE, NNW, etc.
periods.#.windDir80mDEG (number)
The wind direction at 80 meters for the valid time in degrees. 0-359, where 0 is north and 180 is south.
periods.#.windSpeed80mKTS (number)
The wind speed at 80 meters for the valid time in knots.
periods.#.windSpeed80mKPH (number)
The wind speed at 80 meters for the valid time in kilometers per hour.
periods.#.windSpeed80mMPH (number)
The wind speed at 80 meters for the valid time in miles per hour.
periods.#.windSpeed80mMPS (number)
The wind speed at 80 meters for the valid time in meters per second.
periods.#.windGust80mKTS (number)
The wind gust at 80 meters for the valid time in knots.
periods.#.windGust80mKPH (number)
The wind gust at 80 meters for the valid time in kilometers per hour.
periods.#.windGust80mMPH (number)
The wind gust at 80 meters for the valid time in miles per hour.
periods.#.windGust80mMPS (number)
The wind gust at 80 meters for the valid time in meters per second.
periods.#.windDirMax80m (string)
The wind direction at 80 meters at the time of the maximum wind speed for the period in cardinal notation. N, S, SE, NNW, etc.
periods.#.windDirMax80mDEG (number)
The wind direction at 80 meters at the time of the maximum wind speed for the period in degrees. 0-359, where 0 is north and 180 is south.
periods.#.windSpeedMax80mKTS (number)
The maximum wind speed at 80 meters for the period in knots.
periods.#.windSpeedMax80mKPH (number)
The maximum wind speed at 80 meters for the period in kilometers per hour.
periods.#.windSpeedMax80mMPH (number)
The maximum wind speed at 80 meters for the period in miles per hour.
periods.#.windSpeedMax80mMPS (number)
The maximum wind speed at 80 meters for the period in meters per second.
periods.#.windDirMin80m (string)
The wind direction at 80 meters at the time of the minimum wind speed for the period in cardinal notation. N, S, SE, NNW, etc.
periods.#.windDirMin80mDEG (number)
The wind direction at 80 meters at the time of the minimum wind speed for the period in degrees. 0-359, where 0 is north and 180 is south.
periods.#.windSpeedMin80mKTS (number)
The minimum wind speed at 80 meters for the period in knots.
periods.#.windSpeedMin80mKPH (number)
The minimum wind speed at 80 meters for the period in kilometers per hour.
periods.#.windSpeedMin80mMPH (number)
The minimum wind speed at 80 meters for the period in miles per hour.
periods.#.windSpeedMin80mMPS (number)
The minimum wind speed at 80 meters for the period in meters per second.
periods.#.sky (number)
The sky/cloud cover for the valid time in percent, 0-100.
periods.#.cloudsCoded (string)
The sky/cloud cover for the valid time in coded notation.
periods.#.weather (string)
Full weather phrase for the forecast period.
periods.#.weatherCoded (array)
Array of periods containing different weather types; can be used to determine when a particular type of weather is expected to begin/end. Refer to the Coded Weather documentation for additional information on the types of weather codes.
periods.#.weatherCoded.#.timestamp (number)
The UNIX timestamp for the beginning of this forecast periods for the specific weather.
periods.#.weatherCoded.#.wx (string)
The coded weather type. Refer to the Coded Weather documentation for additional information on the types of weather codes.
periods.#.weatherPrimary (string)
The primary weather phrase for the forecast period.
periods.#.weatherPrimaryCoded (string)
The primary coded weather type. Refer to the Coded Weather documentation for additional information on the types of weather codes.
periods.#.icon (string)
The URL to the weather icon for the forecast period.
periods.#.visibilityKM (number)
The visibility for the valid time in kilometers.
periods.#.visibilityMI (number)
The visibility for the valid time in miles.
periods.#.uvi (number)
The UV index for the valid time.
periods.#.solradWM2 (number)
The estimated forecast solar radiation. Normally used with filter=1hr. If interval > 1 hour will be the accumulated hourly solar radiation values over the interval.
periods.#.solradMinWM2 (number)
The minimum estimated forecast solar radiation over a forecast interval.
periods.#.solradMaxWM2 (number)
The maximum estimated forecast solar radiation over a forecast interval.
periods.#.isDay (boolean)
True if the period is during the day, otherwise false.
periods.#.solradClearSkyWM2 (number)
The estimated forecast solar radiation under clear sky conditions. Normally used with filter=1hr. If interval > 1 hour will be the accumulated hourly solar radiation values over the interval.
periods.#.solradClearSkySource (string)
The source of the clear sky solar radiation data.
periods.#.maxCoverage (string)
Deprecated
periods.#.sunrise (number)
Sunrise time as a UNIX timestamp. Provided when using filter=day (default) or filter=daynight. Not currently available for hourly forecasts. NOTE: If no sunrise (Midnight sun / polar night) a boolean false will be returned
periods.#.sunriseISO (string)
The sunrise time as an ISO-8601 string. Provided when using filter=day (default) or filter=daynight. Not currently available for hourly forecasts. NOTE: If no sunrise (Midnight sun / polar night) a boolean false will be returned
periods.#.sunset (number)
The sunset time as a UNIX timestamp. Provided when using filter=day (default) or filter=daynight. Not currently available for hourly forecasts. NOTE: If no sunset (Midnight sun / polar night) a boolean false will be returned
periods.#.sunsetISO (string)
The sunset time as an ISO-8601 string. Provided when using filter=day (default) or filter=daynight. Not currently available for hourly forecasts. NOTE: If no sunset (Midnight sun / polar night) a boolean false will be returned
profile (object)
Object containing information about the location or event.
profile.tz (string)
Timezone name of the location.
profile.elevFT (number)
The elevation of the location in feet.
profile.elevM (number)
The elevation of the location in meters.
[
{
"loc": {
"long": -93.264,
"lat": 44.98
},
"interval": "day",
"place": {
"name": "minneapolis",
"state": "mn",
"country": "us"
},
"periods": [
{
"timestamp": 1702558800,
"validTime": "2023-12-14T07:00:00-06:00",
"dateTimeISO": "2023-12-14T07:00:00-06:00",
"maxTempC": 8,
"maxTempF": 47,
"minTempC": 2,
"minTempF": 36,
"avgTempC": 5,
"avgTempF": 41,
"tempC": null,
"tempF": null,
"maxFeelslikeC": 6,
"maxFeelslikeF": 43,
"minFeelslikeC": -7,
"minFeelslikeF": 20,
"avgFeelslikeC": 0,
"avgFeelslikeF": 31,
"feelslikeC": -7,
"feelslikeF": 20,
"maxDewpointC": -1,
"maxDewpointF": 30,
"minDewpointC": -7,
"minDewpointF": 19,
"avgDewpointC": -3,
"avgDewpointF": 26,
"dewpointC": -7,
"dewpointF": 19,
"maxHumidity": 71,
"minHumidity": 54,
"humidity": 69,
"pop": 0,
"precipMM": 0.1,
"precipIN": 0,
"iceaccum": 0,
"iceaccumMM": 0,
"iceaccumIN": 0,
"snowCM": 0,
"snowIN": 0,
"pressureMB": 1032,
"pressureIN": 30.47,
"windDir": "SW",
"windDirDEG": 218,
"windSpeedKTS": 8,
"windSpeedKPH": 14,
"windSpeedMPH": 9,
"windSpeedMPS": 4,
"windGustKTS": 17,
"windGustKPH": 31,
"windGustMPH": 19,
"windGustMPS": 9,
"windDirMax": "SW",
"windDirMaxDEG": 218,
"windSpeedMaxKTS": 8,
"windSpeedMaxKPH": 14,
"windSpeedMaxMPH": 9,
"windSpeedMaxMPS": 4,
"windDirMin": "SSW",
"windDirMinDEG": 210,
"windSpeedMinKTS": 6,
"windSpeedMinKPH": 11,
"windSpeedMinMPH": 7,
"windSpeedMinMPS": 3,
"windDir80m": "SW",
"windDir80mDEG": 227,
"windSpeed80mKTS": 15,
"windSpeed80mKPH": 27,
"windSpeed80mMPH": 17,
"windSpeed80mMPS": 8,
"windGust80mKTS": 16,
"windGust80mKPH": 30,
"windGust80mMPH": 18,
"windGust80mMPS": 8,
"windDirMax80m": "SSW",
"windDirMax80mDEG": 213,
"windSpeedMax80mKTS": 16,
"windSpeedMax80mKPH": 30,
"windSpeedMax80mMPH": 18,
"windSpeedMax80mMPS": 8,
"windDirMin80m": "SSW",
"windDirMin80mDEG": 210,
"windSpeedMin80mKTS": 12,
"windSpeedMin80mKPH": 22,
"windSpeedMin80mMPH": 13,
"windSpeedMin80mMPS": 6,
"sky": 1,
"cloudsCoded": "CL",
"weather": "Sunny",
"weatherCoded": [],
"weatherPrimary": "Sunny",
"weatherPrimaryCoded": "::CL",
"icon": "sunny.png",
"visibilityKM": 16,
"visibilityMI": 9.94,
"uvi": 1,
"solradWM2": 1805.5452,
"solradMinWM2": 0,
"solradMaxWM2": 337.5488,
"isDay": true,
"solradClearSkyWM2": 1805.5456,
"solradClearSkySource": "v1",
"maxCoverage": "",
"sunrise": 1702561408,
"sunset": 1702593115,
"sunriseISO": "2023-12-14T07:43:28-06:00",
"sunsetISO": "2023-12-14T16:31:55-06:00"
}
],
"profile": {
"tz": "America/Chicago",
"elevM": 253,
"elevFT": 830
}
}
]