Site-Based Time-Series Observations

Current® Condition & Time-Series Data

The Time-Series Observations returns the previous 24 hour period from the previous day up to the last reported current condition today. Current® Conditions are sourced from physical site-based observation stations. This API returns the latest weather observation for the location supplied to include current temperatures, winds, pressure and other observed weather information. Weather observations are reported from physical devices deployed worldwide (weather data collected from METAR, SYNOP, BUOY, CMAN devices).

Access to retained site-based weather observations will be distributed on-demand in Current Conditions and Time Series data feeds. Observations per station within a 24 hour period varies due to station operation requirements (i.e. modified operating hours, number of observations recorded per hour, maintenance issues, etc).

The recent observations data will be continuously updated and replaced with a first-in / first-out methodology, (rotating data with newest observation and moving the oldest observations to the archive storage) based on date/time stamping of the observations. The amount of data retained and available from any given station may be more than a single observation or more than 24 individual observation reports for any given station id. The number of observations is determined by the type of observation reported i.e. NWS, etc.

  • It is not to be assumed that data returned will be equal to the hours of past observations requested. Example: 3 hours of past observations may not return just 3 observations.
  • Some reporting stations report observations more than once an hour.

Overview

  • Domain Portfolio: Observations
  • Domain: Current Conditions
  • Geography: Global
  • Attribution Required: No
  • Attribution Requirements: N/A

HTTP Headers and Data Lifetime - Caching and Expiration

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

Translated Fields:

This TWC® API handles the translation of phrases. However, when formatting a request URL a valid language must be passed along (see the language code table for the supported codes).
  • pressure_desc
  • uv_desc
  • wx_phrase

Unit of Measure Requirement

The unit of measure for the response. The following values are supported:
  • e = English units
  • m = Metric units
  • h = Hybrid units (UK)

URL Construction

Aggregate Product Name: v2obstimes

Atomic API URL Examples:Request by Geocode (Latitude & Longitude): Required Parameters: geocode, language, format, units, hours, apiKey=yourApiKey

https://api.weather.com/v1/geocode/34.063/-84.217/observations/timeseries.json?language=en-US&units=e&hours=1&apiKey=yourApiKey

Request by Postal Code: Required Parameters: language, format, units, hours, postal code apiKey=yourApiKey

The Postal Code has a TWC proprietary location type (4) with the following format: location/<postal code>:<location type>:<country code>

https://api.weather.com/v1/location/30075:4:US/observations/timeseries.json?language=en-US&units=e&hours=1&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.

Field Name Description Type Range Sample Nulls Allowed
blunt_phrase Weather description qualifier short phrase string Warmer than yesterday. Y
class data identifier string default observation N
clds Cloud cover description code string SKC, CLR, SCT, FEW, BKN, OVC SKC Y
day_ind Daytime or nighttime of the local apparent time of the location string D = Day, N = Night, X = Missing (for extreme northern and southern hemisphere D Y
dewpt The temperature which air must be cooled at constant pressure to reach saturation. The Dew Point is also an indirect measure of the humidity of the air. The Dew Point will never exceed the Temperature. When the Dew Point and Temperature are equal, clouds or fog will typically form. The closer the values of Temperature and Dew Point, the higher the relative humidity. integer

-80 to 100 (°F) or

-62 to 37 (°C)

 60 Y
expire_time_gmt Expiration time in UNIX® seconds epoch 1369252800 N
feels_like An apparent temperature. It represents what the air temperature “feels like” on exposed human skin due to the combined effect of the wind chill or heat index. integer -140 to 140 60 Y
gust

Wind gust speed.

This data field contains information about sudden and temporary variations of the average Wind Speed. The report always shows the maximum wind gust speed recorded during the observation period. It is a required display field if Wind Speed is shown. The speed of the gust can be expressed in miles per hour or kilometers per hour.

 integer 35 Y
heat_index

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.

When the temperature is 70°F or higher, the Feels Like value represents the computed Heat Index.

For temperatures between 40°F and 70°F, the Feels Like value and Temperature are the same, regardless of wind speed and humidity, so use the Temperature value.

 integer 70 Y
icon_extd

The four-digit number to represent the observed weather conditions.

Refer to the Icon Code, Weather Phrases and Images document

 integer 5500 Y
key Primary data field to group or access data string same as observation ID KATL N
max_temp High temperature in the last 24 hours integer -140 to 140 81 Y
min_temp Low temperature in the last 24 hours integer -140 to 140 48 Y
obs_id Observation station ID string KATL N
obs_name Observation station name string Hartsfield-Jackson Airport N
precip_hrly Precipitation for the last hour decimal 0.00 to 99.99 0.5 Y
precip_total Precipitation amount in the last rolling 24 hour period decimal 0.00 to 99.99 0.3 Y
pressure Barometric pressure is the pressure exerted by the atmosphere at the earth's surface, due to the weight of the air. This value is read directly from an instrument called a mercury barometer and its units are expressed in millibars (equivalent to HectoPascals). double 30.06 Y
pressure_desc A phrase describing the change in the barometric pressure reading over the last hour. string

Steady,

Rising,

Rapidly Rising,

Falling,

Rapidly Falling

 Steady Y
pressure_tend The change in the barometric pressure reading over the last hour expressed as an integer. integer

0 = Steady

1 = Rising or Rapidly Rising

2 = Falling or Rapidly Falling

 0 Y
qualifier Weather description qualifier code string QQ0063 Y
qualifier_svrty Weather description qualifier severity string 1 (low) to 6 (high) 1 Y
rh 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 to 100 91 Y
snow_hrly Snow increasing rapidly in inches or centimeters per hour depending on whether or not the snowfall is reported by METAR or TECCI (synthetic observations). METAR snow accumulation for the last hour is in inches and TECCI is in centimeters. decimal 0 to 15 1 Y
temp The temperature of the air, at the time of the observation, measured by a thermometer 1.5 meters (4.5 feet) above the ground that is shaded from the other elements. integer -140 to 140 62 Y
terse_phrase Weather description qualifier terse phrase string Dangerous wind chills. Limit outdoor exposure. Y
uv_desc Ultraviolet index description string Extreme, High, Low, Minimal, Moderate, No Report, Not Available High Y
uv_index Ultraviolet index integer 0 to 11 and 999 7 Y
valid_time_gmt Valid time of observation as a Unix epoch value (seconds since start of 1970, UTC) epoch 1369252800 Y
vis The horizontal visibility at the observation point. Visibilities can be reported as fractional values particularly when visibility is less than 2 miles. Visibilities greater than 10 statute miles(16.1 kilometers) which are considered “unlimited” are reported as “999” in your feed. You can also find visibility values that equal zero. This occurrence is not wrong. Dense fogs and heavy snows can produce values near zero. Fog, smoke, heavy rain and other weather phenomena can reduce visibility to near zero miles or kilometers. double

0 to 999 or null;

For greater than 1 = no decimal.

For less than 1 = 2 (Metric) & 2 (Imperial) decimal places.

10, 0.25 (Metric)

0.25 (Imperial)

 Y
wc

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.

When the temperature is 61°F or lower the Feels Like value represents the computed Wind Chill so display the Wind Chill value.

For temperatures between 61°F and 75°F, the Feels Like value and Temperature are the same, regardless of wind speed and humidity, so display the Temperature value.

 integer Use only if temperature is below 40 degrees Fahrenheit OR below 5 degrees Celsius -25 Y
wdir The direction from which the wind blows expressed in degrees. The magnetic direction varies from 1 to 360 degrees, where 360° indicates the North, 90° the East, 180° the South, 270° the West, and so forth. A ‘null’ value represents no determinable wind direction. integer 1 to 360 45 Y
wdir_cardinal This field contains the cardinal direction from which the wind blows in an abbreviated form. 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. string N , NNE , NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW, CALM, VAR ENE Y
wspd

Wind Speed.

The wind is treated as a vector; hence, winds must have direction and magnitude (speed). The wind information reported in the hourly current conditions 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 15 Y
wx_icon

The two-digit number to represent the observed weather conditions.

Refer to the Icon Code, Weather Phrases and Images document

 integer 0 to 48 47 Y
wx_phrase A text description of the observed weather conditions at the reporting station string 257 phrases Mostly sunny Y
water_temp Water temperature integer 25 to 100 80 Y
primary_wave_period Primary wave period integer 0-99 13 Y
primary_wave_height Primary wave height decimal 0-99.99 3.28 Y
primary_swell_period Primary swell period integer 0-99 13 Y
primary_swell_height Primary swell height decimal 0-99.99 1.64 Y
primary_swell_direction Primary swell direction integer 0 to 359 190 Y
secondary_swell_period Secondary swell period integer 0-99 null Y
secondary_swell_height Secondary swell height decimal 0-99.99 null Y
secondary_swell_direction Secondary swell direction integer 0 to 359 null Y

JSON Sample


{
  "metadata": {
    "language": "en-US",
    "transaction_id": "1473202846859:-356896210", 
    "version": "1",
    "latitude": 34.06,
    "longitude": -84.21,
    "units": "e",
    "hours": 1
    "expire_time_gmt": 1473209100,
    "status_code": 200
},
    "observations": 
  {
    "key": "T72227031",
    "class": "observation",
    "expire_time_gmt": 1473206700,
    "obs_id": "T72227031",
    "obs_name": "Duluth",
    "valid_time_gmt": 1473199500,
    "day_ind": "D",
    "temp": 90,
    "wx_icon": 32,
    "icon_extd": 3200,
    "wx_phrase": "Sunny",
    "pressure_tend": 2,
    "pressure_desc": "Steady",
    "dewPt": 54,
    "heat_index": 88,
    "rh": 29,
    "pressure": 30.18,
    "vis": 10,
    "wc": 90,
    "wdir": 40,
    "wdir_cardinal": "NE",
    "gust": null,
    "wspd": 1,
    "max_temp": 92,
    "min_temp": 63,
    "precip_total": 0,
    "precip_hrly": 0,
    "snow_hrly": 0,
    "uv_desc": "Low",
    "feels_like": 88,
    "uv_index": 1,
    "qualifier": "OQ0047",
    "qualifier_svrty": "1",
    "blunt_phrase": "Hot.",
    "terse_phrase": "Hot.",
    "clds": "SKC",
    "water_temp": null,
    "primary_wave_period": null,
    "primary_wave_height": null,
    "primary_swell_period": null,
    "primary_swell_height": null,
    "primary_swell_direction": null,
    "secondary_swell_period": null,
    "secondary_swell_height": null,
    "secondary_swell_direction": null
  }
}
 // Response Collapsed for Presentation Purposes 
  }
 ]
}