Daily Forecast (3 Day, 5 Day, 7 Day, 10, 15 Day)

Overview

  • Domain Portfolio: Forecast
  • Domain: Forecasts
  • Usage Classification: Standard
  • Geography: Global
  • Attribution Required: NO
  • p
  • Attribution Requirements: N/A

The Daily Forecast API is sourced from the The Weather Company Forecast system. This TWC API returns weather forecasts starting on the current day. Your content licensing agreement with TWC determines the number of days returned in the API response and is constrained by the API Key that is provided to your company. Please refer to the Data Elements section later in this document for more details.

Note: All wind values are calculated based on wind status 10 meters above ground.

HTTP Headers and Data Lifetime - Caching and Expiration

For details on appropriate header values as well as caching and expiration definitions, see The Weather Company Data | API Common Usage Guide.

Forecast Composition

The TWC daily forecast product can contain multiple days of daily forecasts for each location. Each day of a forecast can contain up to (2) "temporal segments" and one daily summary forecast, resulting in up to three separate forecasts. For any given forecast day we offer day (7am - 7pm), night (7pm - 7am), and a 24-hour forecast (daily summary). Implementing our forecasts requires your applications to perform basic processing in order to properly ingest the forecast data feeds.

Forecast Implementation

The data values in this API are correctly populated into day and/or night temporal segments and one daily summary forecast. The 24-hour temporal segment is represented by the top-level object. The day and night segments are interlaced within the daypart object.

PLEASE NOTE: The "0th index" of all the fields within the daypart object (i.e. daypart[0].{field}[0]) as well as the temperatureMax field in the top-level object will appear as null in the API after 3:00pm Local Apparent Time. The temperatureMax for the 24-hour temporal segment typically has already occurred at this point in the day and would no longer be a valid forecast. If needed, further details can still be obtained using the Hourly Forecast - (2 Day, 15 Day)product. The “calendarDayTemperatureMax” field in the top-level object will continue to display in the API throughout the day.

Translated Fields:

This TWC API handles the translation of phrases for values of the following data. When formatting a request URL a valid language must be passed along (see the language code table for the supported codes).

  • dayOfWeek

  • daypartName

  • moonPhase

  • narrative

  • qualifierPhrase

  • uvDescription

  • windDirectionCardinal

  • windPhrase

  • wxPhraseLong
Atomic Endpoints Aggregate Product Names
v3/wx/forecast/daily/3day v3-wx-forecast-daily-3day
v3/wx/forecast/daily/5day v3-wx-forecast-daily-5day
v3/wx/forecast/daily/7day v3-wx-forecast-daily-7day
v3/wx/forecast/daily/10day v3-wx-forecast-daily-10day
v3/wx/forecast/daily/15day v3-wx-forecast-daily-15day

URL Construction

Request by Geocode: Required Parameters: geocode, units, language, format, apiKey

https://api.weather.com/v3/wx/forecast/daily/7day?geocode=33.74,-84.39&format=json&units=e&language=en-US&apiKey=yourApiKey

https://api.weather.com/v3/wx/forecast/daily/15day?geocode=33.74,-84.39&format=json&units=e&language=en-US&apiKey=yourApiKey
Request by IATA Code: Required Parameters: iataCode, units, language, format, apiKey

https://api.weather.com/v3/wx/forecast/daily/7day?iataCode=DEN&units=e&language=en-US&&format=json&apiKey=yourApiKey

https://api.weather.com/v3/wx/forecast/daily/15day?iataCode=DEN&units=e&language=en-US&&format=json&apiKey=yourApiKey

Request by ICAO Code: Required Parameters: icaoCode, units, language, format, apiKey

https://api.weather.com/v3/wx/forecast/daily/7day?icaoCode=KDEN&units=e&language=en-US&format=json&apiKey=yourApiKey

https://api.weather.com/v3/wx/forecast/daily/15day?icaoCode=KDEN&units=e&language=en-US&format=json&apiKey=yourApiKey

Request by Place ID: Required Parameters: placeid, units, language, format, apiKey

https://api.weather.com/v3/wx/forecast/daily/7day?placeid=327145917e06d09373dd2760425a88622a62d248fd97550eb4883737d8d1173b&units=e&language=en-US&format=json&apiKey=yourApiKey

https://api.weather.com/v3/wx/forecast/daily/15day?placeid=327145917e06d09373dd2760425a88622a62d248fd97550eb4883737d8d1173b&units=e&language=en-US&format=json&apiKey=yourApiKey

Request by Postal Key: Required Parameters: postalKey, units, language, format, apiKey

https://api.weather.com/v3/wx/forecast/daily/7day?postalKey=81657:US&units=e&language=en-US&format=json&apiKey=yourApiKey

https://api.weather.com/v3/wx/forecast/daily/15day?postalKey=81657:US&units=e&language=en-US&format=json&apiKey=yourApiKey

Data Elements & Definitions

Note: Field names are sorted alphabetically in the table below for presentation purposes. The table below does not represent the sort order of the API response.

OBJECT: daypart NOTE: For the purposes of this product day(D) = 7am to 7pm and night(N) = 7pm to 7am

Field Name Description Type Range Sample Nulls Allowed
dayOfWeek Day of week [string] Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday Thursday N
expirationTimeUtc Expiration time in UNIX seconds [epoch]   1369252800 N
moonPhase Description phrase for the current lunar phase [string]   Waning Gibbous N
moonPhaseCode 3 character short code for lunar phases [string] WNG, WXC, FQ, WNC, LQ, F, WXG, N WNG N
moonPhaseDay Day number within monthly lunar cycle [integer] 0 through 29 4 N
moonriseTimeLocal First moonrise in local time. It reflects daylight savings time conventions. [ISO] YYYY-MM-DDTHH:MM:SS-NNNN; NNNN=GMT offset 2014-08-20T10:47:59-0500 Y
moonriseTimeUtc Moonrise time in UNIX epoch value [epoch]   1369252800 Y
moonsetTimeLocal First Moonset in local time. It reflects daylight savings time conventions. [ISO] YYYY-MM-DDTHH:MM:SS-NNNN; NNNN=GMT offset 2014-08-20T10:47:59-0500 Y
moonsetTimeUtc Moonset time in UNIX epoch value [epoch]   1369252800 Y
narrative The narrative forecast for the 24-hour period. When the max or min temperature is over 100°F or below 0°F, this field will revert to different wording. See the sample section for examples. When the specific temperature is provided rather than a range, the temperature will show along with the unit (°F) . [string]  

A few thunderstorms possible. Lows overnight in the low 60s.

"Mostly sunny. Highs 106 to 110F and lows in the upper 80s."

“Some afternoon snow showers, windy. Highs in the low 20s and lows in the low single digits."

 N
qpf The forecasted measurable precipitation (liquid or liquid equivalent) during the 12 or 24 hour period. Units - Expressed in inches when units=e, expressed in millimeters when units=m [decimal]   0.06 N
qpfSnow

The forecasted measurable precipitation as snow during the 12 or 24 hour forecast period.

Units - Expressed in inches when units=e, expressed in centimeters when units=m

 [decimal]   1.3 N
sunriseTimeLocal The local time of the sunrise. It reflects any local daylight savings conventions. For a few Arctic and Antarctic regions, the Sunrise and Sunset data values may be the same (each with a value of 12:01am) to reflect conditions where a sunrise or sunset does not occur. [ISO] YYYY-MM-DDTHH:MM:SS-NNNN; NNNN=GMT offset 2014-08-20T10:47:59-0500 Y
sunriseTimeUtc Sunrise time in UNIX epoch value [epoch]   1369252800 Y
sunsetTimeLocal The local time of the sunset. It reflects any local daylight savings conventions. For a few Arctic and Antarctic regions, the Sunrise and Sunset data values may be the same (each with a value of 12:01am) to reflect conditions where a sunrise or sunset does not occur. [ISO] YYYY-MM-DDTHH:MM:SS-NNNN; NNNN=GMT offset 2014-08-20T10:47:59-0500 Y
sunsetTimeUtc Sunset time in UNIX epoch value [epoch]   1369252800 Y
temperatureMax Daily maximum temperature. This temperature is equivalent to the day daypart temperature. [integer]   82 Y
temperatureMin Daily minimum temperature. This temperature is equivalent to the night daypart temperature. [integer]   59 N
validTimeUtc Time forecast is valid in UNIX seconds [epoch]   1369306800 N
validTimeLocal Time forecast is valid in local apparent time. [ISO] YYYY-MM-DDTHH:MM:SS-NNNN; NNNN=GMT offset 2014-08-20T10:47:59-0500

N
calendarDayTemperatureMax The midnight to midnight daily maximum temperature for the given day. See appendix for more details. [integer] n/a 82 Y
calendarDayTemperatureMin The midnight to midnight daily minimum temperature for the given day. See appendix for more details [integer] n/a 65 Y
cloudCover Daytime average cloud cover expressed as a percentage. [integer] 0 - 100 82 Y
dayOrNight Day or night indicator [string] D, N D Y
daypartName The name of a 12 hour daypart not including day names in the first 48 hours. [string] Today, Tonight Today Y
iconCode This number is the key to the weather icon lookup. The data field shows the icon number that is matched to represent the observed weather conditions. [integer]   26 Y
iconCodeExtend Code representing full set sensible weather [integer]   3200 Y
narrative The narrative forecast for the daytime period. [string]   A few thunderstorms possible. Lows overnight in the low 60s. Y
precipChance Maximum probability of precipitation. [integer]   20 Y
precipType Type of precipitation to display with the probability of precipitation (pop) data element. [string] rain, snow, precip rain Y
qpf The forecasted measurable precipitation (liquid or liquid equivalent) during the 12 hour forecast period. [decimal]   0.04 Y
qpfSnow The forecasted measurable precipitation as snow during the 12 hour forecast period. [decimal]   5.3 Y
qualifierPhrase A phrase associated to the qualifier code describing special weather criteria. [string]   Winds could occasionally gust over 70 mph. Y
relativeHumidity The relative humidity of the air, which is defined as the ratio of the amount of water vapor in the air to the amount of vapor required to bring the air to saturation at a constant temperature. Relative humidity is always expressed as a percentage. [integer] 0 - 100 83 Y
snowRange Snow accumulation amount for the 12 hour forecast period. [string] <1 - 30+ 3-5 Y
temperature The maximum temperature between 7am and 7pm for daytime temperature and the minimum temperature between 7pm and 7am for nighttime temperature. Minimum temperature also incorporates hourly forecasts up to and including 8am the next morning, to better capture morning lows. [integer]   81 N
temperatureHeatIndex

An apparent temperature. It represents what the air temperature “feels like” on exposed human skin due to the combined effect of warm temperatures and high humidity.

Units - Expressed in fahrenheit when units=e, expressed in celsius when units=m, s, or h.

 [integer]   84 N
temperatureWindChill

An apparent temperature. It represents what the air temperature “feels like” on exposed human skin due to the combined effect of the cold temperatures and wind speed.

Units - Expressed in fahrenheit when units=e, expressed in celsius when units=m, s, or h.

 [integer]   68 N
thunderCategory

The description of probability thunderstorm activity in an area for 12 hour daypart.

0 = "No thunder"; 1 = "Thunder possible"; 2 = "Thunder expected"; 3 = "Severe thunderstorms possible"; 4 = "Severe thunderstorms likely"; 5 = "High risk of severe thunderstorms"

 [string]

0 = "No thunder";

1 = "Thunder possible";

2 = "Thunder expected";

3 = "Severe thunderstorms possible";

4 = "Severe thunderstorms likely";

5 = "High risk of severe thunderstorms"

 Severe thunderstorms possible Y
thunderIndex The enumeration of thunderstorm probability within an area for a 12 hour daypart. [integer] 0 - 5 3 Y
uvDescription

The UV Index Description which complements the UV Index value by providing an associated level of risk of skin damage due to exposure.

-2 = Not Available, -1 = No Report, 0 to 2 = Low, 3 to 5 = Moderate, 6 to 7 = High, 8 to 10 = Very High, 11 to 16 = Extreme

 [string] Not Available, No Report, Low, Moderate, High, Very High, Extreme Low Y
uvIndex Maximum UV index for the 12 hour forecast period. [integer]   2 Y
windDirection Average wind direction in magnetic notation. [integer] 0 - 359 148 Y
windDirectionCardinal Average wind direction in cardinal notation. [string] N , NNE , NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW SE Y
windPhrase The phrase that describes the wind direction and speed for a 12 hour daypart. [string]   Winds SSE at 5 to 10 mph. Y
windSpeed

The forecast of the maximum sustained wind speed over the 12 hour forecast period.

The wind is treated as a vector; hence, winds must have direction and magnitude (speed). The wind information reported in the forecast corresponds to a 10-minute average called the sustained wind speed. Sudden or brief variations in the wind speed are known as “wind gusts” and are reported in a separate data field. Wind directions are always expressed as "from whence the wind blows" meaning that a North wind blows from North to South. If you face North in a North wind the wind is at your face. Face southward and the North wind is at your back.

 [integer]   7 Y
wxPhraseLong Sensible weather phrase [string]

Hourly sensible weather phrase up to 32 characters.

Note: The character limit applies to English phrases only. For other languages this phrase may exceed 32 characters.

 Heavy Rain/Wind Y
wxPhraseShort Sensible weather phrase [string] Hourly sensible weather phrase up to 12 characters. Windy Y

JSON Sample

// Response Collapsed for Presentation Purposes
{
       "calendarDayTemperatureMax": [88,88 ],
       "calendarDayTemperatureMin": [70,62 ],
       "dayOfWeek": ["Saturday","Sunday"],
       "expirationTimeUtc": [1474132620,1474132620],
       "moonPhase": ["Waning Gibbous","Waning Gibbous"],
       "moonPhaseCode": ["WXG","WXG"],
       "moonPhaseDay": ["10","11"],
       "moonriseTimeLocal": ["2016-09-17T20:30:02-0400","2016-09-18T21:12:36-0400"],
       "moonriseTimeUtc": [1474158602,1474247556 ],
       "moonsetTimeLocal": ["2016-09-17T08:08:29-0400","2016-09-18T09:16:30-0400 ],
       "moonsetTimeUtc": [1474114109,1474204590 ],
       "narrative": ["Mix of sun and clouds. Highs in the upper 80s and lows in the low 70s.","Showers and thunderstorms late. Highs in the upper 80s."],
       "qpf": [0,0.2],
       "qpfSnow": [0,0 ],
       "sunriseTimeLocal": ["2016-09-17T07:21:26-0400","2016-09-18T07:22:05-0400"],
       "sunriseTimeUtc": [1474111286,1474197725 ],
       "sunsetTimeLocal": ["2016-09-17T19:39:03-0400","2016-09-18T19:37:41-0400" ],
       "sunsetTimeUtc": [1474155543,1474241861 ],
       "temperatureMax": [88,88 ],
       "temperatureMin": [70,71 ],
       "validTimeLocal": ["2016-09-17T07:00:00-0400","2016-09-18T07:00:00-0400" ],
       "validTimeUtc": [1474110000,1474196400],
       "daypart": [
         {
           "cloudCover": [44,63 ],
           "dayOrNight": ["D","N" ],
           "daypartName": [ "Today","Tonight" ],
           "iconCode": [30,29 ],
           "iconCodeExtend": [3000,2900 ],
           "narrative": ["A mix of clouds and sun. High 88F. Winds SE at 5 to 10 mph.","Partly cloudy this evening with more clouds for overnight." ],
           "precipChance": [0,20 ],
           "precipType": [rain,precip ],
           "qpf": [0,0 ],
           "qpfSnow": [0,0 ],
           "qualifierPhrase": [null,"Slight chance of a rain shower." ],
           "relativeHumidity": [48,79 ],
           "snowRange": ["","" ],    
           "temperature": [88,70 ],
           "temperatureHeatIndex": [90,86 ],
           "temperatureWindChill": [84,71 ],
           "thunderCategory": ["No thunder","No thunder" ],
           "thunderIndex": [0,0 ],
           "uvDescription": ["Very High","Low" ],
           "uvIndex": [8,0 ],
           "windDirection": [136,159 ],
           "windDirectionCardinal": ["SE","SSE" ],
           "windPhrase": ["Winds SE at 5 to 10 mph.","Winds light and variable." ],
           "windSpeed": [7,3 ],
           "wxPhraseLong": ["Partly Cloudy","Partly Cloudy" ],
           "wxPhraseShort": ["P Cloudy","P Cloudy"]
         }

Appendix

Daily Forecast Temperature Max and Min

The daily summary object contains two pairs of temperature maximum and minimum values. They represent the high and low temperatures for the given day in different temporal resolutions.

Field Description Temporal Representation
temperatureMax The daily maximum temperature. This temperature is equivalent to the day daypart temperature. 7:00 AM Local - 7:00 PM Local (12 Hours)
temperatureMin The daily minimum temperature. This temperature is equivalent to the night daypart temperature. 7:00 PM Local - 7:00 AM Local (12 Hours)
calendarDayTemperatureMax The midnight to midnight daily maximum temperature for the given day. 12:00 AM Local - 12:00 AM Local (24 Hours)
calendarDayTemperatureMin The midnight to midnight daily minimum temperature for the given day. 12:00 AM Local - 12:00 AM Local (24 Hours)

Suggested Use

temperatureMax / temperatureMin

When using or displaying the temperature maximum and minimum for a given day, the recommended fields are temperatureMax and temperatureMin. These fields align directly with the day and night daypart objects, including narratives and iconCodes, which will ensure consistency throughout the data elements.

These temperature values are always forward-looking as a forecast. The temperatureMax field represents the daytime high, and the temperatureMin field represents the nighttime low. As such, the temperatureMax and temperatureMin fields are best used to display forecasted maximum and minimum temperatures over multiple days (i.e today’s daytime high, tonight’s nighttime low, tomorrow’s daytime high, tomorrow’s nighttime low etc).

calendarDayTemperatureMax / calendarDayTemperatureMin

The calendarDayTemperatureMax and calendarDayTemperatureMin fields encapsulate the absolute high and low temperatures within a calendar day defined by a midnight to midnight time period. These values can provide a high or low temperature that occurred in the past within the provided day. These fields do have limitations. They are unique in that they are the only fields that follow a midnight to midnight definition, rather than the 7-to-7 definition. This does result in some ambiguity as to when the minimum and maximum temperatures will occur within the day, which does not exist with the temperatureMax and temperatureMin fields.

The distinct field pairs should not be used interchangeably as they represent unique values.

Daily Forecast Visual

image