Forecast Weather

Use this API to return today's forecast plus the forecast for up to 7 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.
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

Parameter Description Valid 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 7 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 7 days from today). Dates formatted as YYYY-MM-DD

Query String Parameters

Query Parameter Name Description Valid Values
limit The number of results to include in each response. Used in conjunction with offset to paginate. Because at most 8 days are available, pagination has limited value in this API.

Applies only when requesting more than one day.
An integer number up to 7
offset The 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.
sort This 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
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 temperatures you will get min, max, and units.

Applies to all endpoints.
conditionsCode
conditionsText
temperatures
precipitation
sky
solar
relativeHumidity
wind
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
blockSize By 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.
1, 2, 3, 4, 6, 8, 12, 24
conditionsType The 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
useLocalTime By 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 parameter
  • Useful for easily obtaining Forecast data based on localized time of the requested field location
true or false
utcOffset When 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 offset
A 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":{ 
            "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}" 
            }, 
         "dewPoint": { 
             "amount":{dewPoint}, 
             "units":"{dewPointUnits}" 
            }
          
        },{
            ... 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

Name Description
date The date for which the forecast applies. Each day in the requested range is an object in the top-level forecasts array.
location The location the weather is for, including the geolocation and repeating the supplied Field ID.
forecast array The 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 endTime The 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.
temperatures The expected high and low temperature 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.
precipitation The 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."
sky These properties identify the percentage of sky that is occluded by clouds during this time window (and inversely, how much of the sky is clear).
solar The 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).
wind The 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.
relativeHumidity The expected high, low, and average relative humidity during this time block. The units are always in percent.
dewPoint The expected dew point during this time block. You can change the units with the units query string parameter.
{dailySelfLink} The URI you can use to retrieve a specific day's forecast (useful for caching a response).
awhere:field The 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 (default is 8 and only one page). 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 (default is 8 and only one page). 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

Digit Textual Description Constraints / Qualifications
Cloud Conditions (First Digit)
1 Clear Cloud cover is 0%–12.5%.
2 Partly Cloudy Cloud cover is 12.6%–87.5%.
3 Cloudy Cloud cover is 87.6%–100%.
Rain Conditions (Second Digit)
1 No Rain No trace of rain/precipitation.
2 Light Rain Trace amounts up to 2.54mm/hour.
3 Moderate Rain 2.55mm/hour to 7.62mm/hour of rainfall.
4 Heavy Rain More than 7.62mm/hour of rainfall.
Wind Conditions (Third Digit)
1 Light Wind / Calm 0–8 km/hr
2 Moderate Wind 8.01–32 km/hr
3 Windy 32.01–48 km/hr
4 Very Windy 48.01–64 km/hr
5 Strong Winds 64.01–88 km/hr
6 Hurricane Force More than 88 km/hr

"Standard" Condition Codes

Digit Textual Description Constraints / Qualifications
Cloud Conditions (First Digit)
1 Sunny Day Cloud cover 0%–12.5%. This code is only used for daytime hours.
2 Mostly Sunny Day Cloud covers 12.6%–37.5% of the sky. This code is only used for daytime hours.
3 Partly Sunny Day Cloud covers 37.6%–62.5% of the sky. This code is only used for daytime hours.
4 Mostly Cloudy Day Cloud covers 62.6%–87.5% of the sky. This code is only used for daytime hours.
5 Cloudy Day Cloud covers 87.6%–100% of the sky. This code is only used for daytime hours.
6 Clear Night Cloud cover is 0%–12.5%. This code is only used for nighttime hours.
7 Mostly Clear Night Cloud cover 12.6%–37.5%. This code is only used for nighttime hours.
8 Partly Cloudy Night Cloud cover 37.6%–62.5%. This code is only used for nighttime hours.
9 Mostly Cloudy Night Cloud cover 62.6%–87.5%. This code is only used for nighttime hours.
A Cloudy Night Cloud cover 87.6%–100%. This code is only used for nighttime hours.
B Clear Cloud cover is 0%–12.5%. This code is used when a summary period might bridge daytime and nighttime hours.
C Mostly Clear Cloud cover 12.6%–37.5%. This code is used when a summary period might bridge daytime and nighttime hours.
D Partly Cloudy Cloud cover 37.6%–62.5%. This code is used when a summary period might bridge daytime and nighttime hours.
E Mostly Cloudy Cloud cover 62.6%–87.5%. This code is used when a summary period might bridge daytime and nighttime hours.
F Cloudy Cloud cover 87.6%–100%. This code is used when a summary period might bridge daytime and nighttime hours.
Rain Conditions (Second Digit)
1 No Rain No trace of rain/precipitation.
2 Light Rain Trace amounts up to 2.54mm/hour.
3 Moderate Rain 2.55mm/hour to 7.62mm/hour of rainfall.
4 Heavy Rain More than 7.62mm/hour of rainfall.
Wind Conditions (Third Digit)
1 Light Wind / Calm 0–8 km/hr
2 Moderate Wind 8.01–32 km/hr
3 Windy 32.01–48 km/hr
4 Very Windy 48.01–64 km/hr
5 Strong Winds 64.01–88 km/hr
6 Hurricane Force More than 88 km/hr