Historical Weather Norms by Geolocation

This is a flexible API that allows you to calculate the averages for weather attribute across any range of years for which we have data. Whereas the Daily Observed API only supports up to 30 months of daily data, this API allow you to compare this year and the previous year to the long-term normals (however many years you want to include). Each day's worth of data also includes the standard deviation for the average.

Common Best Practice: Considering the increasing weather variability over the last couple of decades, the most relevant norms to use for comparison are an average of the last 10 years.

Note: This API does not support pagination.

Note: Most aWhere customers reference locations by a registered field ID. At this time, all our supporting resources and code samples are geared for these use cases. If you need assistance using this API please contact your aWhere representative.

[Toc:ul]

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/weather/locations/{latitude},{longitude}/norms/{month-day}
GET /v2/weather/locations/{latitude},{longitude}/norms/{startDay},{endDay}
  • Returns the average of the last 10 years for either a single day or a range of days.
GET /v2/weather/locations/{latitude},{longitude}/norms/{month-day}/years/{startYear},{endYear}
GET /v2/weather/locations/{latitude},{longitude}/norms/{startDay},{endDay}/years/{startYear},{endYear}
  • These the same endpoints as above except you can choose to average over any number of years by specifying the start and end year in the URI.

Parameters

Parameter Description Valid Values
{latitude} The decimal-notation latitude of the location for which you want weather data. A number
{longitude} The decimal-notation longitude of the location for which you want weather data. A number
{month-day} To get the averages for a single day, specify the month and day date here, excluding the year. A month & day date formatted as MM-DD
{startDay}, and {endDay} Two month-day's separated by a comma, implying the start and end days of a range. Like the previous parameter, this is only the month and day portion of a timestamp, excluding the year. The days cannot be more than a year apart. A month & day date formatted as MM-DD
{startYear}
and
{endYear}
Two years separated by a comma, implying the range of years (inclusive) for which you want the averages calculated. You must request at least three years of data. Four-digit years, e.g., YYYY

Query String Parameters

Query Parameter Name Description Valid Values
sort This API can sort its results by day (in calendar order), descending or ascending, when this parameter is used and set to day. See Sorting Conventions for more information. date
properties Only include these properties in the daily data. If not specified, then all properties are included by default. Any properties not specified are always included, and all child properties of a selection are included. Separate multiple choices with a comma. For example if you specify maxTemp you will get the amount, the standard deviation, and units. meanTemp
maxTemp
minTemp
precipitation
solar
maxHumidity
minHumidity
dailyMaxWind
units By default, the API will return metric units (e.g., Celsius, millimeters, etc). When set to usa:

  • temperatures are returned in Fahrenheit
  • precipitation is returned in inches
  • wind speed is returned in miles per hour

The API response includes properties that indicate the units for each temperature attribute. This parameter applies to all endpoints.

usa
metric
excludeYears

You can opt to exclude one or more years from the range, and it's values will not be included in the averages. To exclude multiple years, separate them with a comma.

When used in conjunction with a range of days, the start of the range will be evaluated to determine exclusion.  For example, for the range /norms/11-01,03-31?excludeYears=2015, the data for 2015-11-01 through 2016-03-31 will be excluded from the results.  The previous season, 2014-11-01 through 2015-03-31 will still be included.

Note: You must always have at least three years of data to average, and if using this parameter causes the number to fall lower the API will return an error.

Four-digit years, separated by a comma, e.g. YYYY,YYYY

Request Body

None

HTTP Headers

Remember to always send your OAuth2 Access Token in the Authorization header (see Authentication). This API doesn't require any additional headers.

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. No additional headers are used.

Response Body

Format

Each object in the top-level norms array represents the averages for that date across all the selected years. For example, "the average high temperature for May 1st from 2004-2014 is 60°F." Each weather attribute also includes the standard deviation for the data that when into creating the averaged value.

{
 "norms":[{
	"day":"{month-day}",
	"location":":{
		"latitude":{latitude},
		"longitude":{longitude}
		},
	"meanTemp":{ 
		"average":{meanTemp},
		"stdDev":{meanTempStdDev}, 
		"units":"{meanTempUnits}"
		},
	"maxTemp":{ 
		"average":{maxTemp},
		"stdDev":{maxTempStdDev}, 
		"units":"{meanTempUnits}"
		},
	"minTemp":{ 
		"average":{minTemp},
		"stdDev":{minTempStdDev", 
		"units":"{minTempUnits}"
		},
	"precipitation":{
		"average":{precipitation}, 
		"stdDev":{precipStdDev}, 
		"units":"{precipUnits}"
		},
	"solar":{
		"average":{solar}, 
		"stdDev":{solarStdDev}, 
		"units":"{solarUnits}"
		},
	"minHumidity":{ 
		"average":{minHumidity}, 
		"stdDev":{minHumidityStdDev}, 
		},
	"maxHumidity":{ 
		"average":{maxHumidity}, 
		"stdDev":{maxHumidityStdDev}, 
		},
	"dailyMaxWind":{ 
		"average":{maxWind}, 
		"stdDev":{maxWindStdDev}, 
		"units":"{windUnits}"
		},
        "averageWind": {
               "average":{averageWind},
               "stdDev":{averageWindStdDev},
               "units":"{windUnits}"
               },
	"_links":{ 
		"self":{"href":"{dailySelfLink}"}

		}
	},{ 
		... repeat for each day ...
    }
 ],
 "_links":{
	"self":{"href":"{list_link}"}
 }
}

Note: When requesting just a single day of data, the response is only a single day's object, shown here as the first object in the top-level norms array.

Property Descriptions

Name Description
day The month and day for which the averages apply, for example, if the averages are for May 1st this value would be 05-01. Each day in the requested range is an object in the top-level norms array.
location The location the weather is for, echoing the supplied latitude and longitude.
meanTemp The average mean temperature and standard deviation, plus a property that describes the temperature units (e.g., "F" for Fahrenheit or "C" for Celsius). You can change the units with the units query string parameter.
maxTemp The average high temperature and standard deviation, plus a property that describes the temperature units (e.g., "F" for Fahrenheit or "C" for Celsius). You can change the units with the units query string parameter.
minTemp The average low temperature and standard deviation, plus a property that describes the temperature units (e.g., "F" for Fahrenheit or "C" for Celsius). You can change the units with the units query string parameter.
precipitation The average amount of rain on each day and standard deviation, with the units (either "mm" or millimeters or "in" for inches). You can change the units with the units query string parameter.
solar The average solar energy for each day and standard deviation. There is a units child property, but its value will always be in Watt hours per square meter (Wh/m^2).
minHumidity The average of this day's lowest relative humidity across all the specified years, with standard deviation. The units are always in percent.
maxHumidity The average of this day's highest relative humidity across all the specified years, with standard deviation. The units are always in percent.
dailyMaxWind The average of this day's highest wind speed and standard deviation, with the units (either "m/sec" for meters per second, or "mph" for miles per hour). You can change the units with the units query string parameter.
averageWind The average of this day's average wind speed and standard deviation, with the units (either "m/sec" for meters per second, or "mph" for miles per hour). You can change the units with the units query string parameter.
{dailySelfLink} The URI you can use to retrieve a specific day's norms across the specified years (useful for caching a response).
{list_self} The URI used to regenerate the list.