Forecast Weather

You are here:
< All Topics
image_pdfDownload as PDF

Use this API to return today’s forecast plus the forecast for up to 15 more days. Forecasts are available in many sizes of hourly blocks, from hourly to daily.

Important: By default this API returns forecast data in UTC. For forecast data reflective of your field location’s time zone or a custom time offset please utilize either the useLocalTime or utcOffset parameter.

API Request

API Endpoints

▶ HTTP VERBS AND URIS

GET /v2/weather/fields/{fieldId}/forecasts
  • The default forecasts endpoint will return today’s forecast plus the next 7 days of data for the selected field location.  Days 9-16 can be requested by utilizing the limit and offset query string parameters (e.g. GET /v2/weather/fields/{fieldId}/forecasts?offset=9&limit=8).
GET /v2/weather/fields/{fieldId}/forecasts/{singleDate}
GET /v2/weather/fields/{fieldId}/forecasts/{startDate},{endDate}
  • Use either a single date or a start and end date to return any number of days of data.

▶ PARAMETERS

PARAMETERDESCRIPTIONVALID VALUES
{fieldId}The ID of the field location for which you want weather.A string
{singleDate}A single date, for which the API will return just one day’s forecast for the field location. The date must be today or a future date (up to 15 days from today).A date formatted as YYYY-MM-DD
{startDate}
and
{endDate}
Two dates separated by a comma, implying the start and end date of a range. The API will return data for all the days between those dates (inclusive). The dates must be today or a future date (up to 15 days from today).Dates formatted as YYYY-MM-DD

Query String Parameters

QUERY PARAMETER NAMEDESCRIPTIONVALID VALUES
limitThe number of results to include in each response. Used in conjunction with offset to paginate. Applies only when requesting more than one day.Defaults to 8 for requests that don’t specify a start and end date.An integer up to 16.
offsetThe number of objects to skip before returning objects. Used in conjunction with offset to paginate. For example, if limit=3 and offset=3, then the API will be returning the second page of results.Applies only when requesting more than one day.An integer up to the total number of results.
sortThis API can sort its results by date, descending or ascending, when this parameter is used and set to date. See Sorting Conventions for more information.Applies only when requesting more than one day.date
propertiesOnly include these properties in the daily data.  If not specified, then all properties are included by default.  All child properties of a selection are included.  For example if you specify temperatures you will get value, min, max, and units.Separate multiple choices with a comma (e.g. /v2/weather/fields/{fieldId}/forecasts?properties=temperatures,solar).  conditionsCode
conditionsText
temperatures
precipitation
sky
solar
relativeHumidity
wind
unitsBy 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
blockSizeBy default, the API will return hourly forecasts for each day in the range. This parameter allows you to roll the forecast up into larger blocks of hours. For example, if you set this to 4, you will get 6 forecast blocks, each covering a span of 4 hours.This parameter applies to all endpoints.  When the blockSize is set to a value greater than 1, only the min and max will be returned for the temperatures attributes in the response.  When the blockSize is set to 1 (hourly), the following will display null for min and max: relativeHumidity, wind, soilTemperatures, soilMoisture.1234681224
conditionsTypeThe API response includes a human-friendly summary of the forecast conditions (e.g., “Sunny Skies, Light Wind, No Rain”). The Standard set of summaries have many more gradations regarding cloud cover and distinguish between day and night hours. The Basic has a limited set of cloud cover summaries, and is useful when you have limited icons or don’t need granularity. (See Conditions Codes and Text, below.)basic
standard
useLocalTimeBy default, the API will use UTC offset +00:00 for the start and end timestamp of each forecast block. When this parameter is set to true, the API returns results localized to the requested field’s time zone.When set to true, the API will ignore the utcOffset parameterUseful for easily obtaining Forecast data based on localized time of the requested field locationtrue or false
utcOffsetWhen this is set, the start and end timestamps for each forecast block will be adjusted by this many hours.Use this option to obtain forecast data based on a custom time offsetA time offset that would be used in ISO-8901 time stamps, for example: -04:00 or +12:30

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. Additionally, when requesting multiple days of data, the API returns a Content-Range header which is another way to know how many results are being shown and the total number of results. It looks like this:

Content-Range: {start}-{end}/{total} fields

Response Body

▶ FORMAT

The forecast is provided in hourly blocks (which can be rolled up into multiple-hours-per-block with a query string parameter). Each block has a start and end timestamp, and the attributes in each block apply to those times; for example, the response could be interpreted as “The expected high temp between 9:00 and 9:59 is 59°F.”

{
 "forecasts":[{
  "date":"{date}",
  "location":{
    "latitude":{latitude},
    "longitude":{longitude},
    "fieldId":"{fieldId}"
    },
  "forecast":[{
    "startTime":"{startTime}",
    "endTime":"{endTime}",
    "conditionsCode":"{conditionsCode}",
    "conditionsText":"{conditionsText}",
    "temperatures":{
      "value":{temp},
      "max":{maxTemp},
      "min":{minTemp},
      "units":"{tempUnits}"
      },
    "precipitation":{
      "amount":{precipitation},
      "units":"{precipUnits}",
      "chance":{chanceOfRain}
      },
    "sky":{
      "cloudCover":{skyCover},
      "sunshine":{skyClear},
      },
    "solar":{
      "amount":{solar},
      "units":"{solarUnits}"
      },
    "relativeHumidity":{
      "average":{humidity},
      "max": {maxHumidity},
      "min":{minHumidity}
      },
    "wind":{
      "average":{averageWind},
      "max": {maxWind},
      "min":{minWind},
      "units":"{windUnits}",
      "bearing":"{windBearing}",
      "direction":"{windDirection}"
      },
    "dewPoint": {
      "amount":{dewPoint},
      "units":"{dewPointUnits}"
      },
    "soilTemperatures": [{
      "depth": "{depth}",
      "average": {averageSoilTemperature},
      "max": {maxSoilTemperature},
      "min": {minSoilTemperature},
      "units": "{units}"
      },
      {
        ... repeated for multiple height levels ...
      }
    ],
    "soilMoisture": [{
      "depth": "{depth}",
      "average": {averageSoilMoisture},
      "max": {maxSoilMoisture},
      "min": {minSoilMoisture}
      },
      {
        ... repeated for multiple height levels ...
      }
    ],
    {
      ... repeat for each block ...
    }
  ],
  "_links":{
    "self":{"href":"{dailySelfLink}"},
    "curies":[{
      "name":"awhere",
      "href":"http://awhere.com/rels/{rel}",
      "templated":true
      }],
    "awhere:field":{"href":"{fieldLink}"}
    }
  },
  {
    ... repeat for each day ...
  }
 ],
 "_links":{
  "self":{"href":"{list_self}"},
  "next":{"href":"{next_page}"},
  "prev":{"href":"{previous_page}"},
  "curies":[{
    "name":"awhere",
    "href":"http://awhere.com/rels/{rel}",
    "templated":true
    }],
  "awhere:field":{"href":"{fieldLink}"}
 }
}

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 forecasts array.

▶ PROPERTY DESCRIPTIONS

NAMEDESCRIPTION
dateThe date for which the forecast applies. Each day in the requested range is an object in the top-level forecasts array.
locationThe location the weather is for, including the geolocation and repeating the supplied Field ID.
forecast arrayThe forecast blocks are returned in this child array. You can change the size and number of hours in each block using query string parameters.
startTime and endTimeThe beginning and end of the respective time window. You can add more hours to each window using the blockSize query string parameter.
conditionsCode 
and conditionsText
Human-friendly summaries of the forecast conditions. The conditionsCode is a three-digit code that provides a standard way of selecting an icon (for example), and are explained in the Conditions Codes and Text section below.
temperaturesThe expected high, low, and temperature value during this time window, 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. When the blockSize is greater than 1, only the expected high and low will be returned.
precipitationThe chance of rain and the expected amount rain during this time window, with the units (either “mm” or millimeters or “in” for inches). You can change the units with the units query string parameter. Combined, a way to interpret these values would be, “there is a 50% chance of rain, and if it rains, 10mm is expected.”
skyThese properties identify the percentage of sky that is occluded by clouds during this time window (and inversely, how much of the sky is clear).
solarThe solar energy expected during this time window. There is a units child property, but its value will always be in Watt hours per square meter (Wh/m^2).
windThe expected average wind speed and most likely highest and lowest gust during this time window, 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.  At ?blockSize=1 (hourly), min and max will be null.Meteorological wind direction (the direction the wind is coming from) is also included.  Direction is represented as both bearing in degrees, and a human-friendly direction string based on a 16 point compass.
relativeHumidityThe expected high, low, and average relative humidity during this time block. The units are always in percent.  At ?blockSize=1 (hourly), min and max will be null.
dewPointThe expected dew point during this time block. You can change the units with the units query string parameter.
soilTemperaturesThe expected soil temperature during the time block, at four different soil depths.  The value is an array of four objects.  You can change the units with the units query string parameter.  At ?blockSize=1 (hourly), min and max will be null.
soilMoistureThe expected soil moisture content as a percentage, at four different soil depths.  The value is an array of four objects.  At ?blockSize=1 (hourly), min and max will be null.
{dailySelfLink}The URI you can use to retrieve a specific day’s forecast (useful for caching a response).
awhere:fieldThe URI you can use to retrieve the field location information.
{list_self}The URI used to generate the list, which includes any current pagination parameters
{next_page}The URI used to get the next page of results, using the same limit used for this request. If there are no more results this property is not included.
{previous_page}The URI used to get the previous page of results, using the same limit used for this request. If you’re at the beginning of the list this property is not included.

Conditions Codes and Text

Conditions are the easy-to-understand summarized forecast for each block of time, rendered in the conditionsCode and conditionsText response properties. Specifically, the condition code is a three-digit code where each digit represents a different category of the forecast. The first digit is for cloud conditions, the second digit for rainfall conditions, and the third digit represents wind forecast.

This API has two types of summations available, standard and basic, where basic has fewer categories and so encompasses more scenarios for each digit. Select your preferred level of detail with the conditionsType query string parameter.

Note: When describing cloud cover, the clouds must be opaque (not transparent) to qualify as cover.

“Basic” Condition Codes

DIGITTEXTUAL DESCRIPTIONCONSTRAINTS / QUALIFICATIONS
Cloud Conditions (First Digit)
1ClearCloud cover is 0%–12.5%.
2Partly CloudyCloud cover is 12.6%–87.5%.
3CloudyCloud cover is 87.6%–100%.
Rain Conditions (Second Digit)
1No RainNo trace of rain/precipitation.
2Light Rain0.26 mm/hour (above trace) to 2.54mm/hour.
3Moderate Rain2.55mm/hour to 7.62mm/hour of rainfall.
4Heavy RainMore than 7.62mm/hour of rainfall.
5Trace Amount of RainTrace amount of rainfall, up to .25mm/hour.
Wind Conditions (Third Digit)
1Light Wind / Calm0–8 km/hr
2Moderate Wind8.01–32 km/hr
3Windy32.01–48 km/hr
4Very Windy48.01–64 km/hr
5Strong Winds64.01–88 km/hr
6Hurricane ForceMore than 88 km/hr

“Standard” Condition Codes

DIGITTEXTUAL DESCRIPTIONCONSTRAINTS / QUALIFICATIONS
Cloud Conditions (First Digit)
1Sunny DayCloud cover 0%–12.5%. This code is only used for daytime hours.
2Mostly Sunny DayCloud covers 12.6%–37.5% of the sky. This code is only used for daytime hours.
3Partly Sunny DayCloud covers 37.6%–62.5% of the sky. This code is only used for daytime hours.
4Mostly Cloudy DayCloud covers 62.6%–87.5% of the sky. This code is only used for daytime hours.
5Cloudy DayCloud covers 87.6%–100% of the sky. This code is only used for daytime hours.
6Clear NightCloud cover is 0%–12.5%. This code is only used for nighttime hours.
7Mostly Clear NightCloud cover 12.6%–37.5%. This code is only used for nighttime hours.
8Partly Cloudy NightCloud cover 37.6%–62.5%. This code is only used for nighttime hours.
9Mostly Cloudy NightCloud cover 62.6%–87.5%. This code is only used for nighttime hours.
ACloudy NightCloud cover 87.6%–100%. This code is only used for nighttime hours.
BClearCloud cover is 0%–12.5%. This code is used when a summary period might bridge daytime and nighttime hours.
CMostly ClearCloud cover 12.6%–37.5%. This code is used when a summary period might bridge daytime and nighttime hours.
DPartly CloudyCloud cover 37.6%–62.5%. This code is used when a summary period might bridge daytime and nighttime hours.
EMostly CloudyCloud cover 62.6%–87.5%. This code is used when a summary period might bridge daytime and nighttime hours.
FCloudyCloud cover 87.6%–100%. This code is used when a summary period might bridge daytime and nighttime hours.
Rain Conditions (Second Digit)
1No RainNo trace of rain/precipitation.
2Light Rain0.26 mm/hour (above trace) to 2.54mm/hour.
3Moderate Rain2.55mm/hour to 7.62mm/hour of rainfall.
4Heavy RainMore than 7.62mm/hour of rainfall.
5Trace Amount of RainTrace amount of rainfall, up to .25mm/hour.
Wind Conditions (Third Digit)
1Light Wind / Calm0–8 km/hr
2Moderate Wind8.01–32 km/hr
3Windy32.01–48 km/hr
4Very Windy48.01–64 km/hr
5Strong Winds64.01–88 km/hr
6Hurricane ForceMore than 88 km/hr
Was this article helpful?
2.8 out Of 5 Stars
5 Stars 0%
4 Stars 0%
3 Stars 50%
2 Stars 50%
1 Stars 0%
How can we improve this article?
Table of Contents