Endpoint: roadweather

Introducing AerisWeather’s new roadweather endpoint, powered by the advanced and precise Vaisala Xweather road weather forecasts. This innovative endpoint delivers essential information on road conditions through a summary index (green, yellow, or red), enabling users to gauge driving safety at a glance. With the Road Weather Conditions add-on, the API further details the road surface condition (dry, wet, snow, ice) and road surface temperature. For comprehensive road weather insights, including water, snow, and ice thickness, hydroplane and turnover probabilities, visibility, and fog probabilities, the RoadWeather Analytics add-on is available. Enhance your application’s capabilities with this cutting-edge road weather endpoint to help users make better-informed decisions and promote safer driving experiences.

Supported Actions

The following actions are supported with the roadweather 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 endpoint'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:
for=tomorrow
for=friday
for=1302883980
for=MM/DD/YYYY
for=YYYY/MM/DD
for=+2hours
for=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 250.
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.

Supported Filters

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

primary Returns road weather information for primary roads. NOTE: the location must be near a primary road.
secondary Returns road weather information for secondary roads. NOTE: the location must be near a secondary road.
bridge Returns road weather information for bridges. NOTE: the location must be near a bridge.
noroadcheck By default the API ensures the requested location is within 100 meters of a supported road. With this filter, this check is bypassed and the API will return information on the closest supported road within 20km.

Sortable Fields

Default Sort: dt:1 (Date time ascending)

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 the periods based on the forecast date/time
summary Used with the psort parameter. Sort the periods on the road condition summary. GREEN, YELLOW, RED.
summaryindex Used with the psort parameter. Sort the periods on the road conditions summaryIndex value (0, 1, 2).
condition Used with the psort parameter. Sort the periods based on the road condition (DRY, MOIST, WET, SLUSH, SNOW, ICE).
temp Used with the psort parameter. Sort the periods based on the road surface temperature
truckrollover Used with the psort parameter. Sort the periods based on the probability of a potential truck roll over due to high winds
hydroplane Used with the psort parameter. Sort the periods based on the probability of a potential hydroplane incident.
lowvisfog Used with the psort parameter. Sort the periods based on the probability of low visibility due to fog.
lowvisblowingsnow Used with the psort parameter. Sort the periods based on the probability of low visibility due to blowing snow.

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 the road weather information for a road within 100meters of the specified latitude/longitude. Since no filter is provided, the API will return data for the nearby primary road if one is nearby, alternatively it will fall back to a secondary road if there is one nearby.
/roadweather/44.9648,-93.2682

Returns the road weather information for a primary road within 100 meters of the specified latitude/longitude.
/roadweather/44.9648,-93.2682?filter=primary

Returns the road weather information for a secondary road within 100 meters of the specified latitude/longitude.
/roadweather/44.9648,-93.2682?filter=secondary

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

{
  "id": "79wefx4",
  "dataSource": "vaisala-road-wx",
  "road": {
    "type": "primary",
    "name": "Washington Avenue South"
  },
  "loc": {
    "long": -93.253452,
    "lat": 44.968276
  },
  "place": {
    "name": "minneapolis",
    "state": "mn",
    "country": "us"
  },
  "periods": [
    {
      "timestamp": 1685628900,
      "dateTimeISO": "2023-06-01T09:15:00-05:00",
      "summary": "GREEN",
      "summaryIndex": 0,
      "roadSurface": {
        "condition": "DRY",
        "tempC": 35.2,
        "tempF": 95.36,
        "waterFilmThicknessMM": 0,
        "waterFilmThicknessIN": 0,
        "snowThicknessCM": 0,
        "snowThicknessIN": 0,
        "iceThicknessMM": 0,
        "iceThicknessIN": 0,
        "conditionProbability": {
          "dry": 100,
          "wet": 0,
          "snow": 0,
          "ice": 0
        }
      },
      "riskProbability": {
        "truckRollover": 0,
        "hydroplane": 0,
        "lowVisFog": 0,
        "lowVisBlowingSnow": 0
      }
    }
  ],
  "profile": {
    "elevM": 242,
    "elevFT": 793.96,
    "tz": "America/Chicago"
  }
}
								

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "79wefx4",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -93.253452,
          44.968276
        ]
      },
      "properties": {
        "id": "79wefx4",
        "dataSource": "vaisala-road-wx",
        "road": {
          "type": "primary",
          "name": "Washington Avenue South"
        },
        "loc": {
          "long": -93.253452,
          "lat": 44.968276
        },
        "place": {
          "name": "minneapolis",
          "state": "mn",
          "country": "us"
        },
        "periods": [
          {
            "timestamp": 1685639700,
            "dateTimeISO": "2023-06-01T12:15:00-05:00",
            "summary": "GREEN",
            "summaryIndex": 0,
            "roadSurface": {
              "condition": "DRY",
              "tempC": 49.2,
              "tempF": 120.56,
              "waterFilmThicknessMM": 0,
              "waterFilmThicknessIN": 0,
              "snowThicknessCM": 0,
              "snowThicknessIN": 0,
              "iceThicknessMM": 0,
              "iceThicknessIN": 0,
              "conditionProbability": {
                "dry": 100,
                "wet": 0,
                "snow": 0,
                "ice": 0
              }
            },
            "riskProbability": {
              "truckRollover": 0,
              "hydroplane": 0,
              "lowVisFog": 0,
              "lowVisBlowingSnow": 0
            }
          }
        ],
        "profile": {
          "elevM": 242,
          "elevFT": 793.96,
          "tz": "America/Chicago"
        }
      }
    }
  ]
}
								

Response Properties

The following properties will be provided in every response object:

id (string) The ID of the requested location.
dataSource (string) An ID string of the data source provider utilized for the data set
road (object) An object containing the nearby road information. Null if unavailable.
road.type (string) The type of road. Can be:
- primary
- secondary
- tertiary
- bridge
road.name (string) The road name. Null if unavailable.
periods (array) An array of the road weather forecast periods
periods.#.timestamp (number) The unix timestamp in seconds of the valid date/time of the forecast
periods.#.dateTimeISO (string) The ISO8601 valid date/time of the forecast period
periods.#.summary (string) A summary of road conditions broken down as:
- GREEN = dry roads with no issues
- YELLOW = Potential for wet roads, extend caution
- RED = Potential adverse road conditions.

Available to all Flex Subscribers.
periods.#.summaryIndex (number) A numerical version of the road conditions summary:
- 0 = GREEN
- 1 = YELLOW
- 2 = RED

Available to all Flex Subscribers.
periods.#.roadSurface (object) An object containing advanced road surface information.

Requires the Road Weather Conditions or Analytics Addon. Not returned for standard Flex Subscribers.
periods.#.roadSurface.condition (string) The condition of the road surface. Will be one of the following:
- DRY
- MOIST
- WET
- SLUSH
- SNOW
- ICE

Available with a Road Weather Addon.
periods.#.roadSurface.tempC (number) The estimated road surface temperature in Celsius
periods.#.roadSurface.tempF (number) The estimated road surface temperature in Fahrenheit
periods.#.roadSurface.waterFilmThicknessMM (number) The estimated water film thickness on the road surface in millimeters.

Available with the Road Weather Analytics Addon.
periods.#.roadSurface.waterFilmThicknessIN (number) The estimated water film thickness on the road surface in inches.

Available with the Road Weather Analytics Addon.
periods.#.roadSurface.snowThicknessCM (number) The estimated snow thickness on the road surface in centimeters.

Available with the Road Weather Analytics Addon.
periods.#.roadSurface.snowThicknessIN (number) The estimated snow thickness on the road surface in inches.

Available with the Road Weather Analytics Addon.
periods.#.roadSurface.iceThicknessMM (number) The estimated ice thickness on the road surface in millimeters.

Available with the Road Weather Analytics Addon.
periods.#.roadSurface.iceThicknessIN (number) The estimated ice thickness on the road surface in inches.

Available with the Road Weather Analytics Addon.
periods.#.roadSurface.conditionProbability (object) Object of probabilities of the road surface conditions.

Available with the Road Weather Analytics Addon. Not returned for other requests.
periods.#.roadSurface.conditionProbability.dry (number) The probability the road surface is dry, from 0 to 100.

Note: All conditionProbability values (dry, wet, snow, ice) will sum up to a total value of 100%.
periods.#.roadSurface.conditionProbability.wet (number) The probability the road surface is wet, from 0 to 100.

Note: All conditionProbability values (dry, wet, snow, ice) will sum up to a total value of 100%.
periods.#.roadSurface.conditionProbability.snow (number) The probability the road surface is snow covered, from 0 to 100.

Note: All conditionProbability values (dry, wet, snow, ice) will sum up to a total value of 100%.
periods.#.roadSurface.conditionProbability.ice (number) The probability the road surface has ice, from 0 to 100.

Note: All conditionProbability values (dry, wet, snow, ice) will sum up to a total value of 100%.
periods.#.riskProbability (object) Object of risk probabilities.

Available with the Road Weather Analytics Addon. Not returned for other requests.
periods.#.riskProbability.truckRollover (number) The risk probability of a truck rollover, from 0 to 100.
periods.#.riskProbability.hydroplane (number) The risk probability of hydroplaning, from 0 to 100.
periods.#.riskProbability.lowVisFog (number) The risk probability of low visibility from fog, from 0 to 100.
periods.#.riskProbability.lowVisBlowingSnow (number) The risk probability of low visibility from blowing snow, from 0 to 100.
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: September 14, 2023