IBM Cleaned Historical APIs

The method which may be used to access the global data sets programmatically is via a REST web services data request. First, establish an account where a unique key will be created and provided. You may have multiple accounts. Each key is configured to allow up to X number of calls per year which was discussed and agreed upon in conversations with your account manager. The definition of a call is noted below.

HTTP Headers and Data Lifetime - Machine and Expiration

Note: An API call is defined as 7 days or less of data. For example, if you request 14 days of data it is counted as 2 calls against your annual call allowance.
For details on appropriate header values as well as caching and expiration definitions, see The API Common Usage Guide.

Available Weather Variables

Name Description
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)
dateHrGmt Greenwich Mean Time (GMT) date-time (also known as Universal Time)

Response Messages

Table 1. Response messages
HTTP Status Code Reason
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too many requests
Disclaimer: There is a max of 1 year of historical data allowed per request. If you require more than 1 year of data, it is highly recommended that you split into multiple calls with a max of 1 year at a time to reduce latency.
Table 2. Lat/long example to retrieve parameters
Sample {Lat/Long} URL request (All Input Parameters Specified):
https://cleanedobservations.weather.com/v2/wsi/metar/[42.303,-99.062]?startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&time=lwt&station=metar&fields=surfaceTemperatureFahrenheit,realtaiveHumidityPercent,windSpeedMph,downwardSolarRadiationWsqm&userKey=99999999999999999999999999999999
Table 3. Zip code example with required parameters
Sample {Zipcode} URL request (Only Required Parameters Specified):
https://cleanedobservations.weather.com/v2/wsi/metar/%5B42.303,-99.062%5D?startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&userKey=99999999999999999999999999999999
Table 4. Zip code example with all parameters
Sample {Zipcode} URL request (All Input Parameters Specified):  
https://cleanedobservations.weather.com/v2/wsi/metar/zipcode/01810?startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&time=lwt&station=metar&fields=surfaceTemperatureFahrenheit,realtaiveHumidityPercent,windSpeedMph,downwardSolarRadiationWsqm&userKey=99999999999999999999999999999999  
Table 5. Sample {METAR Code} URL request with all parameters
Sample {METAR Code} URL request (All Input Parameters Specified):
https://cleanedobservations.weather.com/v2/wsi/metar/station/KBOS?startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&time=lwt&station=metar&fields=surfaceTemperatureFahrenheit,realtaiveHumidityPercent,windSpeedMph,downwardSolarRadiationWsqm&userKey=99999999999999999999999999999999
Table 6. Sample {Grid Cell ID} URL request with all input parameters
Sample {Grid Cell ID} URL request (All Input Parameters Specified):
https://cleanedobservations.weather.com/v2/wsi/metar/station/2268975643?startDate=05/01/2015&endDate=05/02/2015&interval=hourly&units=imperial&format=json&time=lwt&station=metar&fields=surfaceTemperatureFahrenheit,realtaiveHumidityPercent,windSpeedMph,downwardSolarRadiationWsqm&userKey=99999999999999999999999999999999

Degree Day 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.

  • userKey (required) — this is a unique client identifier.
  • lat/long (required) – latitude/longitude for which data is being requested for
  • 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.)
  • 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
  • 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

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.

Table 7. Example of Growing/Killing Days for Corn
Calculate Growing/Killing Degree Days for Corn with a basetemp of 55F:
https://cleanedobservations.weather.com/v2/wsi/metar/degreeday/[42.134,-78.132]?startDate=05/01/2015&endDate=05/02/2015&units=imperial&crop=corn&basetemp=55&format=json&userKey=[userKey]