Response Format

API responses consist of a UTF-8-encoded, JSON-formatted object with the following properties:

  • latitude required
    The requested latitude.
  • longitude required
    The requested longitude.
  • timezone (e.g. America/New_York) required
    The IANA timezone name for the requested location. This is used for text summaries and for determining when hourly and daily data block objects begin.
  • offset deprecated
    The current timezone offset in hours. (Use of this property will almost certainly result in Daylight Saving Time bugs. Please use timezone, instead.)
  • currently optional
    A data point containing the current weather conditions at the requested location.
  • minutely optional
    A data block containing the weather conditions minute-by-minute for the next hour.
  • hourly optional
    A data block containing the weather conditions hour-by-hour for the next two days.
  • daily optional
    A data block containing the weather conditions day-by-day for the next week.
  • alerts optional
    An alerts array, which, if present, contains any severe weather alerts pertinent to the requested location.
  • flags optional
    A flags object containing miscellaneous metadata about the request.

Data Point Object

A data point object contains various properties, each representing the average (unless otherwise specified) of a particular weather phenomenon occurring during a period of time: an instant in the case of currently, a minute for minutely, an hour for hourly, and a day for daily. These properties are:

  • apparentTemperature optional, not on daily
    The apparent (or “feels like”) temperature in degrees Fahrenheit.
  • apparentTemperatureMax optional, only on daily
    The maximum value of apparentTemperature during a given day.
  • apparentTemperatureMaxTime optional, only on daily
    The UNIX time of when apparentTemperatureMax occurs during a given day.
  • apparentTemperatureMin optional, only on daily
    The minimum value of apparentTemperature during a given day.
  • apparentTemperatureMinTime optional, only on daily
    The UNIX time of when apparentTemperatureMin occurs during a given day.
  • cloudCover optional
    The percentage of sky occluded by clouds, between 0 and 1, inclusive.
  • dewPoint optional
    The dew point in degrees Fahrenheit.
  • humidity optional
    The relative humidity, between 0 and 1, inclusive.
  • icon optional
    A machine-readable text summary of this data point, suitable for selecting an icon for display. If defined, this property will have one of the following values: clear-day, clear-night, rain, snow, sleet, wind, fog, cloudy, partly-cloudy-day, or partly-cloudy-night. (Developers should ensure that a sensible default is defined, as additional values, such as hail, thunderstorm, or tornado, may be defined in the future.)
  • moonPhase optional, only on daily
    The fractional part of the lunation number during the given day: a value of 0 corresponds to a new moon, 0.25 to a first quarter moon, 0.5 to a full moon, and 0.75 to a last quarter moon. (The ranges in between these represent waxing crescent, waxing gibbous, waning gibbous, and waning crescent moons, respectively.)
  • nearestStormBearing optional, only on currently
    The approximate direction of the nearest storm in degrees, with true north at 0° and progressing clockwise. (If nearestStormDistance is zero, then this value will not be defined.)
  • nearestStormDistance optional, only on currently
    The approximate distance to the nearest storm in miles. (A storm distance of 0 doesn’t necessarily refer to a storm at the requested location, but rather a storm in the vicinity of that location.)
  • ozone optional
    The columnar density of total atmospheric ozone at the given time in Dobson units.
  • precipAccumulation optional, only on hourly and daily
    The amount of snowfall accumulation expected to occur, in inches. (If no snowfall is expected, this property will not be defined.)
  • precipIntensity optional
    The intensity (in inches of liquid water per hour) of precipitation occurring at the given time. This value is conditional on probability (that is, assuming any precipitation occurs at all) for minutely data points, and unconditional otherwise.
  • precipIntensityMax optional, only on daily
    The maximum value of precipIntensity during a given day.
  • precipIntensityMaxTime optional, only on daily
    The UNIX time of when precipIntensityMax occurs during a given day.
  • precipProbability optional
    The probability of precipitation occurring, between 0 and 1, inclusive.
  • precipType optional
    The type of precipitation occurring at the given time. If defined, this property will have one of the following values: "rain", "snow", or "sleet" (which refers to each of freezing rain, ice pellets, and “wintery mix”). (If precipIntensity is zero, then this property will not be defined.)
  • pressure optional
    The sea-level air pressure in millibars.
  • summary optional
    A human-readable text summary of this data point. (This property has millions of possible values, so don’t use it for automated purposes: use the icon property, instead!)
  • sunriseTime optional, only on daily
    The UNIX time of when the sun will rise during a given day.
  • sunsetTime optional, only on daily
    The UNIX time of when the sun will set during a given day.
  • temperature optional, not on minutely
    The air temperature in degrees Fahrenheit.
  • temperatureMax optional, only on daily
    The maximum value of temperature during a given day.
  • temperatureMaxTime optional, only on daily
    The UNIX time of when temperatureMax occurs during a given day.
  • temperatureMin optional, only on daily
    The minimum value of temperature during a given day.
  • temperatureMinTime optional, only on daily
    The UNIX time of when temperatureMin occurs during a given day.
  • time required
    The UNIX time at which this data point begins. minutely data point are always aligned to the top of the minute, hourly data point objects to the top of the hour, and daily data point objects to midnight of the day, all according to the local time zone.
  • visibility optional
    The average visibility in miles, capped at 10 miles.
  • windBearing optional
    The direction that the wind is coming from in degrees, with true north at 0° and progressing clockwise. (If windSpeed is zero, then this value will not be defined.)
  • windSpeed optional
    The wind speed in miles per hour.

Data Block Object

A data block object represents the various weather phenomena occurring over a period of time. Such objects contain the following properties:

  • data required
    An array of data points, ordered by time, which together describe the weather conditions at the requested location over time.
  • summary optional
    A human-readable summary of this data block.
  • icon optional
    A machine-readable text summary of this data block. (May take on the same values as the iconproperty of data points.)

Alerts Array

The alerts array contains objects representing the severe weather warnings issued for the requested location by a governmental authority (please see our data sources page for a list of sources). Objects in the alerts array contain the following properties:

  • description required
    A detailed description of the alert.
  • expires required
    The UNIX time at which the alert will expire.
  • title required
    A brief description of the alert.
  • uri required
    An HTTP(S) URI that one may refer to for detailed information about the alert.

Flags Object

The flags object contains various metadata information related to the request. This object may optionally contain any of the following properties:

  • darksky-unavailable optional
    The presence of this property indicates that the Dark Sky data source supports the given location, but a temporary error (such as a radar station being down for maintenance) has made the data unavailable.
  • metno-license optional
    The presence of this property indicates that data from api.met.no was utilized in order to facilitate this request (as per their license agreement).
  • sources required
    This property contains an array of IDs for each data source utilized in servicing this request.
  • units required
    Indicates the units which were used for the data in this request.

Response Headers

The API will set the following HTTP response headers to values useful to developers:

  • Cache-Control optional
    Set to a conservative value for data caching purposes based on the data present in the response body.
  • Expires deprecated
    Set to a conservative value for data caching purposes based on the data present in the response body.
  • X-Forecast-API-Calls optional
    The number of API requests made by the given API key for today.
  • X-Response-Time optional
    The server-side response time of the request.

Notes

  • Never make any assumptions about the presence of data or lengths of arrays. For example, a lack of data in our data sources may cause data to be missing; or Daylight Savings Time may cause a day to consist of 23 or 25 hours (instead of the usual 24); or, at high latitudes, a given day may not have a sunrise or sunset. Always check for the presence of data before trying to use it.
  • Summaries on the hourly data block actually only cover up to a maximum of 24 hours, rather than the full time period in the data block. We found that covering the full 48 hours could be, in a number of circumstances, far too wordy to be practical.
  • Summaries and icons on daily data point objects actually cover the period from 4AM to 4AM, rather than the stated time period of midnight to midnight. We found that the summaries so generated were less awkward.
  • The Forecast Data API supports HTTP compression. We heartily recommend using it, as it will make responses much smaller over the wire. To enable it, simply add an Accept-Encoding: gzip header to your request. (Most HTTP client libraries wrap this functionality for you, please consult your library’s documentation for details.)