cleaned observation api documentation - the weather companycleanedobservations.wsi.com/documents/wsi...

CLEANED OBSERVATION

API DOCUMENTATION

UPDATED: APR 13, 2018

TWC GLOBAL DATA SETS

Page 1 | The Weather Company business.weather.com

TWC Global Data Sets

The method which may be used to access the WSI global data sets programmatically is via a REST web

services data request. First, establish an account with WS where in which an account with a unique ID

will be created and provided. You may have multiple accounts. Each key is configured to allow up to X

number of calls per month which was discussed and agreed upon in conversations with your TWC

account manager. The definition of a call is noted below.

An API call is defined as 7 days or less of data. For example, if you request 14

days of data it would be counted as 2 calls against your monthly call allowance.

1.) Standard/Premium Weather Variables

2.) Degree Day Variables

3.) Hi-Resolution Precipitation

1. STANDARD/PREMIUM WEATHER VARIABLES

Certain parameters are required to initiate a weather request. As is standard in URIs, all parameters are

separated using the ampersand (&) character. The list of parameters and their possible values are

enumerated below.

Each API key is provisioned to provide data for a specific set of Standard Weather Variables. In addition,

your key can be provisioned for access to a special set of 6 Premium Weather Variables. The specific set

of Standard and Premium Variables can be found in tables listed below.

• userKey (required) — this unique client identifier is assigned by WSI

• lat/long or zipcode (required) – Data can be requested either by latitude/longitude or zip code.

Currently searching by zip code is only supported for US zip codes.

• startDate (required) — “mm/dd/yyyy” Indicates the starting date for weather request (Start date

is first hour of requested date)



• endDate (required) — “mm/dd/yyyy” indicates the ending date for weather request (End date is

first hour of date requested, Data will be returned between the first hour of start date and first

hour of end date. Make end date an extra day if you would like data for that day.)

• interval (required) — The desired temporal resolution of the data being retrieved. Accepted

values are:

• hourly

• daily

• monthly

• units (required) — The desired units in which to express the data being retrieved. Accepted

values are:

• imperial

• metric

• format (required) — The desired format in which to return the data being retrieved. Accepted

values are:

• json

• xml

• csv

• version – The specific version of the API to be utilized. Currently accepted values are:

• 2

station – The specific data source to use for the requested location.

o cfsr – Use the closest virtual grid point to the requested location. You are guaranteed to have data returned for the entire time frame requested when using this value - Default

o metar – Will conduct a nearest neighbor search and chooses a METAR station if it is 17.5 km or less from the requested location. If a METAR station is used, you are not guaranteed to have data returned for the entire time frame requested. METAR data is only returned for the period of the requested time period in which it is available. Premium Weather Variables are not available when using this option.

fields – Specify the specific set of variables to return in the data being retrieved. Accepted

values are in the table provided below. You can specify more than one variable by separating

each value by a comma, i.e. fields=windSpeedMph,surfaceTemperatureFahrenheit. If no

fields are specified, all parameters will be returned.

time – Specify the time unit the requested data is returned in. Accepted values are:

• lwt (local wall time)

• gmt (Greenwich mean time) - Default

delivery – Specify how the data is returned. Accepted values are:

stream – Data is delivered directly to the browser or the application that makes the

API call

file – Data is delivered in a file that is downloaded to your system – Default



Available Standard Weather Variables Name Description SiteId Site / location identifier (either Virtual Grid Square ID or

METAR ID)

dateHrGmt Greenwich Mean Time (GMT) date-time (also known as Universal Time)

dateHrLwt Valid local date-time (Local wall time {includes daylight savings time})

surfaceTemperatureFahrenheit Surface air (dry bulb) temperature at 2 meters

surfaceDewpointTemperatureFahrenheit Atmospheric humidity metric (temperature at which dew will form)

surfaceWetBulbTemperatureFahrenheit Atmospheric humidity metric (evaporative cooling potential of moist surface)

relativeHumidityPercent Percent of water vapor in the air relative to its saturation point

apparentTemperatureFahrenheit Air temperature that includes impact of wind and humidity

windChillTemperatureFahrenheit Air temperature that includes impact of wind

heatIndexFahrenheit Air temperature that includes the impact of humidity

precipitationPreviousHourInches Liquid equivalent for types: warm rain, freezing rain, sleet, snow

snowfallInches Total Snowfall

surfaceAirPressureMillibars Atmospheric pressure at the Surface

mslPressureMillibars Mean Sea Level Pressure

cloudCoveragePercent Percentage of the sky covered by clouds

windSpeedMph Unobstructed wind speed at 10 meters

windDirectionDegrees Upwind direction (e.g., wind from east = 90, from south = 180, etc.) at 10 meters

surfaceWindGustsMph Unobstructed wind gusts at 10 meters

diffuseHorizontalRadiationWsqm Diffuse (indirect) solar radiation flux on a plane parallel to the Earth's surface

directNormalIrradianceWsqm Direct solar radiation flux on a surface 90 deg to the sun

downwardSolarRadiationWsqm Total solar radiation flux on a plane parallel to the Earth's surface

surfaceTemperatureCelsius Surface air (dry bulb) temperature at 2 meters

surfaceDewpointTemperatureCelsius Atmospheric humidity metric (temperature at which dew will form)

surfaceWetBulbTemperatureCelsius Atmospheric humidity metric (evaporative cooling potential of moist surface)

apparentTemperatureCelsius Air temperature that includes impact of wind and humidity

windChillTemperatureCelsius Air temperature that includes impact of wind



heatIndexCelsius Air temperature that includes the impact of humidity

snowfallCentimeters Total Snowfall

precipitationPreviousHourCentimeters Liquid equivalent for types: warm rain, freezing rain, sleet, snow

surfaceAirPressureKilopascals Atmospheric pressure

mslPressureKilopascals Mean Sea Level Pressure

surfaceWindGustsKph Unobstructed wind gusts at 10 meters

windSpeedKph Unobstructed wind speed at 10 meters

referenceEvapotranspiration Reference Evapotranspiration (inches/hour)

Available Premium Weather Variables

Name Description potentialEvapotranspirationMicrometersPerHour

Maximum evaporation rate possible (sum of evaporation and plant transpiration)

surfaceWaterRunOffMillimeters Precipitation in previous hour expected to run off (not be absorbed)

zeroToTenLiquidSoilMoisturePercent Layer-average by volume

zeroToTenSoilTemperatureFahrenheit Layer-average

zeroToTenSoilTemperatureCelsius Layer-average

tenToFortyLiquidSoilMoisturePercent Layer-average by volume

fortyToOneHundredLiquidSoilMoisturePercent Layer-average by volume

tenToFortySoilTemperatureFahrenheit Layer-average

tenToFortySoilTemperatureCelsius Layer-average

fortyToOneHundredSoilTemperatureFahrenheit Layer-average

fortyToOneHundredSoilTemperatureCelsius Layer-average

Response Messages HTTP Status Code Reason

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too many requests



Date Range Restriction: There is a max of 1 year of historical data allowed per request. If you

request more than 1 year of data your end date will be shortened. You would receive data from

your start date to 1 year out.

Examples to Retrieve Standard Parameters

Sample {Lat/Long} URL request (Required Parameters)

http://cleanedobservations.wsi.com/CleanedObs.svc/GetObs?version=2&lat=42.134&long=-

78.132&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userK

ey=99999999999999999999999999999999

Sample {Lat/Long} URL request (All Parameters)

http://cleanedobservations.wsi.com/CleanedObs.svc/GetObs?

version=2&lat=42.303&long=99.062&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units

=imperial&format=json&fields=surfaceTemperatureFahrenheit,relativeHumidity,windSpeedMph,downward

SolarRadiation&delivery=file&userKey=99999999999999999999999999999999

Sample {Zipcode} URL request (Required Parameters)


version=2&zipcode=01810&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial

&format=json&userKey=99999999999999999999999999999999

Sample {Zipcode} URL request (All Parameters)



&format=json&fields=surfaceTemperatureFahrenheit,relativeHumidity,windSpeedMph,downwardSolarRad

iation&delivery=stream&userKey=99999999999999999999999999999999

Examples to Retrieve Standard & Premium Parameters

Sample {Lat/Long} URL request (Required Parameters)

http://cleanedobservations.wsi.com/CleanedObs.svc/premium?version=2&lat=42.134&long=-

78.132&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userK

ey=99999999999999999999999999999999

Sample {Lat/Long} URL request (All Parameters)

http://cleanedobservations.wsi.com/CleanedObs.svc/GetObs?version=2&lat=42.134&long=-78.132&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userKey=99999999999999999999999999999999



http://cleanedobservations.wsi.com/CleanedObs.svc/GetObs?%20version=2&lat=42.303&long=99.062&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&fields=surfaceTemperatureFahrenheit,relativeHumidity,windSpeedMph,downwardSolarRadiation&delivery=file&userKey=99999999999999999999999999999999




http://cleanedobservations.wsi.com/CleanedObs.svc/GetObs?%20version=2&zipcode=01810&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userKey=99999999999999999999999999999999



http://cleanedobservations.wsi.com/CleanedObs.svc/GetObs?%20version=2&zipcode=01810&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&fields=surfaceTemperatureFahrenheit,relativeHumidity,windSpeedMph,downwardSolarRadiation&delivery=stream&userKey=99999999999999999999999999999999




http://cleanedobservations.wsi.com/CleanedObs.svc/premium?version=2&lat=42.134&long=-78.132&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userKey=99999999999999999999999999999999





http://cleanedobservations.wsi.com/CleanedObs.svc/premium?

version=2&lat=42.303&long=99.062&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units

=imperial&format=json&fields=TenToFortyLiquidSoilMoisture&delivery=file&userKey=9999999999999999

9999999999999999

Sample {Zipcode} URL request (Required Parameters)



&format=json&userKey=99999999999999999999999999999999

Sample {Zipcode} URL request (All Parameters)



&format=json&fields=TenToFortyLiquidSoilMoisture&delivery=file&userKey=99999999999999999999999

999999999

2. DEGREE DAY VARIABLES



enumerated below.


• lat/long (required) – latitude/longitude for which data is being requested for







values are:

• imperial

• metric


values are:

http://cleanedobservations.wsi.com/CleanedObs.svc/premium?%20version=2&lat=42.303&long=99.062&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&fields=TenToFortyLiquidSoilMoisture&delivery=file&userKey=99999999999999999999999999999999




http://cleanedobservations.wsi.com/CleanedObs.svc/premium?%20version=2&zipcode=01810&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userKey=99999999999999999999999999999999



http://cleanedobservations.wsi.com/CleanedObs.svc/premium?%20version=2&zipcode=01810&startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&fields=TenToFortyLiquidSoilMoisture&delivery=file&userKey=99999999999999999999999999999999






• json

• xml

• csv



API call

file – Data is delivered in a file that is downloaded to your system – Default


• 2

• crop – Specific to Growing Degree Days and Killing Degree Days. Currently accepted values

are:

• Corn - Default

• Wheat

• Potato

• Cotton

• Peanut

• basetemp – The base temperature to be used in the Growing/Killing Degree Day calculation.

The value can be provided in either Fahrenheit or Celsius but needs to be consistent with the

value used for the “units” parameter.

If both the “crop” and “basetemp” parameters are not provided a Default value of 50F is

used. Otherwise, the default basetemp for the entered crop will be used which are listed below

within the Definitions section.

Definitions:

Cooling Degree Days - Difference of average daily temperature and 65 F / 18 C. If positive,

equals the difference. Else is 0.

Heating Degree Days - Difference of 65 F / 18 C and average daily temperature. If positive,

equals the difference. Else is 0.

Growing/Killing Degree Days - Difference from average daily temperature from base

temperature of a crop (base temperature is defined by crop). Equals 0 if average daily

temperature is below 32 F / 0 C or above 86 F / 30 C.

Default basetemp based on crop:



Corn: 50 F / 10 C

Wheat: 40 F / 4 C

Cotton: 60 F / 16 C

Peanut: 56 F / 13 C

Potato: 45 F / 7 C

Response Messages HTTP Status Code Reason

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too many requests

Date Range Restriction: There is a max of 1 year of historical data allowed per request. If you

request more than 1 year of data your end date will be shortened. You would receive data from

your start date to 1 year out.

Examples

Calculate Growing/Killing Degree Days for Corn with a basetemp of 55F

http://cleanedobservations.wsi.com//CleanedObs.svc/GetDegreeDay?lat=42.134&long=-

78.132&startDate=05/01/2015&endDate=05/02/2015&station=metar&units=imperial&crop=corn&basetem

p=55&format=xml&userKey=999999999999999999999999999&delivery=stream

Calculate Growing/Killing Degree Days for Wheat with a basetemp of 10C

http://cleanedobservations.wsi.com//CleanedObs.svc/GetDegreeDay?lat=42.134&long=-

78.132&startDate=05/01/2015&endDate=05/02/2015&station=metar&units=metric&crop=wheat&basetem

p=10&format=xml&userKey=9999999999999999999999999999&delivery=stream

3. Hi-Resolution Precipitation

Our standard datasets provide precipitation data at 30km resolution but we now provide access to a

higher resolution suite of precipitation data. Data can be retrieved for locations in the Continental United

http://cleanedobservations.wsi.com/CleanedObs.svc/GetDegreeDay?lat=42.134&long=-78.132&startDate=05/01/2015&endDate=05/02/2015&station=metar&units=imperial&crop=corn&basetemp=55&format=xml&userKey=999999999999999999999999999&delivery=stream



http://cleanedobservations.wsi.com/CleanedObs.svc/GetDegreeDay?lat=42.134&long=-78.132&startDate=05/01/2015&endDate=05/02/2015&station=metar&units=metric&crop=wheat&basetemp=10&format=xml&userKey=9999999999999999999999999999&delivery=stream





States at both 1km and 4km resolution. Data is available globally at 8km resolution between 60 degrees

N and 60 degrees S. Temporal availability for each resolution is outlined below.

1km: June 1, 2015 to Present

4km: January 1, 2002 to Present

8km: December 1, 2015 to Present



enumerated below.


• lat/long (required) – latitude/longitude for which data is being requested for



• interval (required) — The desired temporal resolution of the data being retrieved. Accepted

values are:

• hourly

• daily

• monthly





values are:

• imperial

• metric

time – Specify the time unit the requested data is returned in. Accepted values are:

• lwt (local wall time)

• gmt (Greenwich mean time) – Default



• peril (required) — The parameter type desired. Accepted values are:

• precipitation

• rain

• snow

• freezingrain

• resolution (required) – The desired spatial resolution

• 1km (Data only available over the Continental United States)

• 4km (Data only available over the Continental United States)

• 8km (Data available globally between 600N and 600S)


values are:

• json

• xml

• csv



API call

file – Data is delivered in a file that is downloaded to your system – Default Value


• 1 – Default Value

ABOUT THE WEATHER COMPANY


Date Range Restriction:

There is a max of 30 days of historical data allowed per request with one exception. You

can request up to 1 year of data when setting the “peril” parameter to “precipitation”. For the

other 3 “peril” values, if you request more than 30 days of data, your end date will be shortened

and you would receive data from your start date to 30 days out.

Examples

Retrieve 8km hourly rainfall data in a CSV file

http://cleanedobservations.wsi.com//CleanedObs.svc/precip?version=1&lat=42.134&long=-

78.132&startDate=02/11/2017&endDate=02/12/2017&peril=rain&interval=hourly&units=imperial&time=gm

t&format=csv&userKey=999999999999999999999999999&delivery=file&resolution=8km

Retrieve 4km hourly rainfall data in XML format displayed in your browser and streamed directly

to your custom software

http://cleanedobservations.wsi.com//CleanedObs.svc/precip?version=1&lat=42.134&long=-

78.132&startDate=02/11/2017&endDate=02/12/2017&peril=rain&interval=hourly&units=imperial&time=gm

t&format=xml&userKey=999999999999999999999999999&delivery=stream&resolution=4km

About The Weather Company

The Weather Company, an IBM Business, is the world's largest private weather enterprise, helping people

make informed decisions – and take action – in the face of weather. The company offers the most

accurate, personalized and actionable weather data and insights to millions of consumers and thousands

of businesses via Weather’s API, its business solutions division, and its own digital products from The

Weather Channel (weather.com) and Weather Underground (wunderground.com).

The company delivers up to 26 billion forecasts daily. Its products include a top weather app on all major

mobile platforms globally; the world’s largest network of personal weather stations; a top-20 U.S. website;

the seventh most data-rich site in the world; one of the world’s largest IoT data platforms; and industry-

leading business solutions. Weather Means Business™. The world’s biggest brands in aviation, energy,

insurance, media, and government rely on The Weather Company for data, technology platforms and

services to help improve decision-making and respond to weather’s impact on business.

Contact Information

http://cleanedobservations.wsi.com/CleanedObs.svc/precip?version=1&lat=42.134&long=-78.132&startDate=02/11/2017&endDate=02/12/2017&peril=rain&interval=hourly&units=imperial&time=gmt&format=csv&userKey=999999999999999999999999999&delivery=file&resolution=8km



http://cleanedobservations.wsi.com/CleanedObs.svc/precip?version=1&lat=42.134&long=-78.132&startDate=02/11/2017&endDate=02/12/2017&peril=rain&interval=hourly&units=imperial&time=gmt&format=xml&userKey=999999999999999999999999999&delivery=stream&resolution=4km



CONTACT INFORMATION


The Weather Company

400 Minuteman Road Andover, MA 01810

Phone: (978) 983-6300

Website: http://business.weather.com

cleaned observation api documentation - the weather companycleanedobservations.wsi.com/documents/wsi...

Documents