Endpoint: conditions

The conditions endpoint provides interpolated global current, forecast, and historical weather conditions, as well as, up to 60 minutes of minutely precipitation forecast. Data is generated for the location and time requested leveraging a proprietary blend of data, including weather station observations, radar & satellite information, global & regional models, and other proprietary sources.

Passing no parameter modifiers provides the conditions for the current time.  Utilizing just the for parameter provides conditions at a specific point in time and utilizing both the from/to parameters provides hourly increments. Please note that up to 24 hours maximum may be returned in a single API request.

Minutely precipitation forecasts are available in one-minute intervals for the next 60 minutes for locations in the US and Canada by utilizing filter=minutelyprecip.

Access to historical data may be limited by your API subscription.

Please note that up to 24 hours maximum may be returned in a single API request.

View our engineers’ walk-through of the conditions endpoint in the release blog.

 

Supported Actions

The following actions are supported with the conditions endpoint:

:id Requesting data by using the :id action is used for returning data for a particular item that has an ID associated with it. This is the primary method for requesting general weather information for a single location (observations, forecasts, advisories, etc.) as the location's name or a zip code serves as the id. Other endpoints may expect a certain value for the ID, such as storm cells whose ID value is a combination of the radar site identifier and unique identifier assigned to every storm cell. Refer to an enpoint's detailed documentation for specific information regarding how to use the :id action.
route The route action returns data for points along a given route. This can be useful to obtain weather information along a transportation route, trails and more. The route is a series of locations, usually latitude/longitudes provided via the p query parameter or for longer routes via GeoJSON within a POST request. The route will return an array of GeoJSON points with the requested data for each point.

Supported Parameters

The following parameters are optional unless otherwise noted:

p p=:place Defines the location to query data for. Refer to the list of supported place value formats.
for for=:string Returns the results starting for the time frame specified. The for parameter is an alias of the from, but useful to indicate a specific time versus a time range

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
from=tomorrow
from=friday
from=1302883980
from=MM/DD/YYYY
from=YYYY/MM/DD
from=+2hours
from=2017-02-27 5:00 PM

from from=:string Returns the results starting from the value specified. For best practices we recommend using the to parameter as well to define a specific time frame.

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
from=tomorrow
from=friday
from=1302883980
from=MM/DD/YYYY
from=YYYY/MM/DD
from=+2hours
from=2017-02-27 5:00 PM

to to=:string Returns the results between now and the value specified. For best practices we recommend using the from parameter as well to define a specific time frame. When used in conjunction with the from parameter, the value of to will be relative to the value of from, not relative to the current time.

Supports a UNIX timestamp or a specific date string. Alternatively, common date formats supported by the PHP strtotime() function will be accepted; however, commas are not accepted.

Examples:
to=+6hours
to=+5days
to=1302883980
to=MM/DD/YYYY
to=YYYY/MM/DD
to=2017-02-27 5:00 PM

plimit plimit=:total Applied only on the periods property, the total number of periods to return as an integer. The maximum plimit for this endpoint is 24.
pskip pskip=:number Applied only on the periods property, used to skip over a specific number of periods in the data set.
psort psort=:string Applied only on the periods property, used to sort results based on certain fields contained within the periods.
filter filter=:string Predefined filters for limiting the results. The filter value can be a single, comma-delimited or a semicolon delimited string of filter names.

Supported Filters

The following filters can be passed to the filter parameter to reduce the results that are returned:

minutelyprecip Returns the next hour of minutely precipitation forecast. Available for US locations. Filter will only return precip related fields and timestamps.
#min Returns conditions in # minute intervals for up to a 60 minute period. # must be an integer from 1 to 60.
For example:
filter=1min : 1 minute intervals
filter=5min : 5 minute intervals
filter=15min : 15 minute intervals.

This filter should be used in combination with the from and to parameters
#hr Returns the conditions in # hour intervals for up to a 24 hour period. # must be an integer from 1 to 24.
For example:
filter=1hr : 1 hour intervals (Default)
filter=3hr : 3 hour intervals
filter=6hr : 6 hour intervals.

This filter should be used in combination with the from and to parameters

Sortable Fields

Default Sort: dt:-1

You can use the following fields to sort data. Review the sorting docs page for more information on the sort functionality.

dt Used with the psort parameter. Sort based on the conditions date/time

Examples

The /[:endpoint]/[:action]? portion within the query template below can be exchanged with any of the examples. Also, please note you will need to input your client credentials in the [ID] and [SECRET] fields which can be found under the Apps section of the members area.

https://api.aerisapi.com/[:endpoint]/[:action]?client_id=[ID]&client_secret=[SECRET]

Returns current conditions for zip code 55403
/conditions/55403?

Returns current conditions for the specified latitude/longitude
/conditions/45.25,-95.25

Returns the current conditions for Minneapolis, MN. NOTE: from=now is the same as providing no for parameter
/conditions/minneapolis,mn?for=now

Returns the weather conditions for Minneapolis, MN for 4 hours ago.
/conditions/minneapolis,mn?for=-4hours

Returns the weather conditions for Minneapolis, MN for May 9th, 2020 at 1:46pm local time. NOTE: The historical addon maybe required to access dates in the past.
/conditions/minneapolis,mn?for=2020-05-09 13:46:00

Returns hourly conditions for the past 12 hours for Paris, France
/conditions/paris,france?from=-12hours&to=now&plimit=12

Returns the next hour of precipitation rate in 1 minute intervals.
/conditions/minneapolis,mn?filter=minutelyprecip

Returns the next 30 minutes of precipitation rate in 1 minute intervals.
/conditions/minneapolis,mn?filter=minutelyprecip&limit=30

Returns the next hour of precipitation rate in 5 minute intervals (vs the default 1 minute)
/conditions/minneapolis,mn?filter=minutelyprecip,5min

Returns the next hour of conditions in 1 minute intervals.
/conditions/paris,france?from=now&to=+1hour&filter=1min

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Default
GeoJSON

{
   "loc":{
      "lat":44.9778,
      "long":-93.265
   },
   "place":{
      "name":"minneapolis",
      "state":"mn",
      "country":"us"
   },
   "periods":[
      {
         "timestamp":1589570542,
         "dateTimeISO":"2020-05-15T14:22:22-05:00",
         "tempC":19.92,
         "tempF":67.85,
         "feelslikeC":20,
         "feelslikeF":68,
         "dewpointC":5.81,
         "dewpointF":42.46,
         "humidity":40,
         "pressureMB":1019.3,
         "pressureIN":30.1,
         "windDir":"N",
         "windDirDEG":350,
         "windSpeedKTS":7,
         "windSpeedKPH":12.96,
         "windSpeedMPH":8.06,
         "windGustKTS":11,
         "windGustKPH":20.37,
         "windGustMPH":12.66,
         "precipMM":null,
         "precipIN":null,
         "snowCM":0,
         "snowIN":0,
         "visibilityKM":24.135,
         "visibilityMI":14.997,
         "sky":10,
         "cloudsCoded":"FW",
         "weather":"Mostly Sunny",
         "weatherCoded":"::FW",
         "weatherPrimary":"Mostly Sunny",
         "weatherPrimaryCoded":"::FW",
         "icon":"pcloudy.png",
         "solradWM2":804,
         "uvi":6,
         "isDay":true
      }
   ],
   "profile":{
      "tz":"America/Chicago",
      "tzname":"CDT",
      "tzoffset":-18000,
      "isDST":true,
      "elevFT":null,
      "elevM":null
   }
}
								

{
   "type":"FeatureCollection",
   "features":[
      {
         "type":"Feature",
         "geometry":{
            "type":"Point",
            "coordinates":[
               -93.265,
               44.9778
            ]
         },
         "properties":{
            "loc":{
               "lat":44.9778,
               "long":-93.265
            },
            "place":{
               "name":"minneapolis",
               "state":"mn",
               "country":"us"
            },
            "periods":[
               {
                  "timestamp":1589570607,
                  "dateTimeISO":"2020-05-15T14:23:27-05:00",
                  "tempC":19.92,
                  "tempF":67.86,
                  "feelslikeC":20,
                  "feelslikeF":68,
                  "dewpointC":5.8,
                  "dewpointF":42.44,
                  "humidity":40,
                  "pressureMB":1019.2,
                  "pressureIN":30.1,
                  "windDir":"N",
                  "windDirDEG":350,
                  "windSpeedKTS":7,
                  "windSpeedKPH":12.96,
                  "windSpeedMPH":8.06,
                  "windGustKTS":11,
                  "windGustKPH":20.37,
                  "windGustMPH":12.66,
                  "precipMM":null,
                  "precipIN":null,
                  "snowCM":0,
                  "snowIN":0,
                  "visibilityKM":24.135,
                  "visibilityMI":14.997,
                  "sky":11,
                  "cloudsCoded":"FW",
                  "weather":"Mostly Sunny",
                  "weatherCoded":"::FW",
                  "weatherPrimary":"Mostly Sunny",
                  "weatherPrimaryCoded":"::FW",
                  "icon":"pcloudy.png",
                  "solradWM2":802,
                  "uvi":6,
                  "isDay":true
               }
            ],
            "profile":{
               "tz":"America\/Chicago",
               "tzname":"CDT",
               "tzoffset":-18000,
               "isDST":true,
               "elevFT":null,
               "elevM":null
            }
         }
      }
   ]
}
								

Response Properties

The following properties will be provided in every response object:

periods (array) Array of conditions, Empty if not requesting conditions across a period.
periods.#.timestamp (number) The unix timestamp of the time of the conditions
periods.#.dateTimeISO (string) The ISO 8601 date/time of the conditions
periods.#.tempC (number) The temperature in Celsius. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.tempF (number) The temperature in Fahrenheit. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.feelslikeC (number) The feels-like / apparent temperature in Celsius. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).

The feels-like temperature is often based on a combination of the NOAA heat index and/or wind chill specifications.

Locations with a temperature of 80F (26.67C) or higher will high humidity will have a feels-like temperature higher than the air temperature. Likewise, locations with a temperature of 40F (4.44C) and lower winds speeds of 3 mph or higher will often have a feels like temperature less than the air temperature.
periods.#.feelslikeF (number) The feels like / apparent temperature in Fahrenheit. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).

The feels-like temperature is often based on a combination of the NOAA heat index and/or wind chill specifications.

Locations with a temperature of 80F (26.67C) or higher will high humidity will have a feels-like temperature higher than the air temperature. Likewise, locations with a temperature of 40F (4.44C) and lower winds speeds of 3 mph or higher will often have a feels like temperature less than the air temperature.
periods.#.dewpointC (number) The dew point in Celsius. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.dewpointF (number) The dew point in Fahrenheit. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.humidity (number) The relative humidity, from 0 - 100. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windDirDEG (number) The wind direction in degrees. 0 - 359, with 0 = North, Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windDir (string) The wind direction, Null if unavailable:
Not returned with minutely precipitation forecasts (filter=minutelyprecip).

Possible values:
- N - North
- NNE - North northeast
- NE - Northeast
- ENE - East northeast
- E - East
- ESE - East southeast
- SE - Southeast
- SSE - South southeast
- S - South
- SSW - South southwest
- SW - Southwest
- WSW - West southwest
- W - West
- WNW - West northwest
- NW - Northwest
- NNW - North northwest
periods.#.windSpeedKTS (number) The wind speed in knots. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windSpeedKPH (number) The wind speed in kilometers per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windSpeedMPH (number) The wind speed in miles per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustKTS (number) The wind gusts in knots. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustKPH (number) The wind gusts in kilometers per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.windGustMPH (number) The wind gusts in miles per hour. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.precipMM (number) For minutely precipitation forecasts, represents the precipitation rate in inches/hour occurring at the specified minute within the forecast.

For a point in time from now through the past 3 hours, represents the estimated precipitation rate in mm/hour occurring at the requested time.

For archive requests prior to the past 3 hours, represents the estimated precipitation received during the previous hour ending at the requested time.

Null if unavailable.
periods.#.precipIN (number) For minutely precipitation forecasts, represents the precipitation rate in inches/hour occurring at the specified minute within the forecast.

For a point in time from now through the past 3 hours, represents the estimated precipitation rate in inches/hour occurring at the requested time.

For archive requests prior to the past 3 hours represents the estimated precipitation received during the previous hour ending at the requested time.

Null if unavailable.
periods.#.snowCM (number) For minutely precipitation forecasts, represents the snowfall rate in cm/hour occurring at the specified minute within the forecast.

For a point in time from now through the past 3 hours, represents the estimated snowfall rate in cm/hour occurring at the requested time.

For archive requests prior to the past 3 hours, represents the estimated snowfall received during the previous hour ending at the requested time.

Null if unavailable.
periods.#.snowIN (number) For minutely precipitation forecasts, represents the snowfall rate in inches/hour occurring at the specified minute within the forecast.

For a point in time from now through the past 3 hours, represents the estimated snowfall rate in inches/hour occurring at the requested time.

For archive requests prior to the past 3 hours, represents the estimated snowfall received during the previous hour ending at the requested time.

Null if unavailable.
periods.#.visibilityKM (number) The visibility in kilometers. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.visibilityMI (number) The visibility in miles. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.pressureMB (number) The mean sea level pressure (MSLP) in millibars. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.pressureIN (number) The mean sea level pressure (MSLP) in inches mercury (inHg). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.sky (number) The percentage of the clouds in the sky. From 0 - 100. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.weather (string) Phrase of weather conditions. Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.weatherCoded (string) Coded version of weather conditions. See the Coded Weather documentation for code options. Null if unavailable.

Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.weatherPrimary (string) Phrase of the primary weather conditions. Null if unavailable.
periods.#.weatherPrimaryCoded (string) Coded version of the primary weather conditions. See the Coded Weather documentation for code options. Null if unavailable.
periods.#.cloudsCoded (string) Coded version of cloud conditions. See the Coded Weather documentation for code options. Null if unavailable.

Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.icon (string) Icon name corresponding to the primary weather conditions.
periods.#.solradWM2 (number) Estimated 1-hour global solar radiation in watts/meter squared.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.uvi (number) Ultraviolet Index (from 1 to 12). Null if unavailable.
Not returned with minutely precipitation forecasts (filter=minutelyprecip).
periods.#.isDay (boolean) Signifies if the observation occurred during daily hours. True if between sunrise and sunset, false otherwise.
loc.long (number) The longitude coordinate of the record.
loc.lat (number) The latitude coordinate of the record.
place.name (string) The place or nearest place to the record.
place.state (string) The state abbreviation in which the record is located. This may be null depending on the country.
place.country (string) The country abbreviation in which the record is located.
profile.tz (string) Timezone name of the location.
profile.tzname (string) The timezone abbreviation for the location.
profile.tzoffset (number) The timezone offset for the location in seconds.
profile.isDST (boolean) True if the location is currently observing Daylight Savings Time (DST), otherwise false.

Last modified: May 03, 2021