The Forecast API lets you query for most locations on the globe, and returns:

  • Current conditions
  • Minute-by-minute forecasts out to 1 hour (where available)
  • Hour-by-hour forecasts out to 48 hours
  • Day-by-day forecasts out to 7 days

There are two main API calls. The first returns the current forecast (for the next week):

https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE

The second lets query for a specific time, past or future (for many places, 60 years in the past to 10 years in the future):

https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE,TIME

Note to Dark Sky API users: The old docs can be found here.
Details on migrating to the new API can be found at the bottom of the page.

Changelog

API Libraries

Looking to include Forecast in your app? These wrapper libraries should make it quick and easy to do so:

Additionally, Gerard Davison has provided a JSON Schema of the API.

Finally, please note that all of the above API wrappers (except for the official Ruby wrapper) are unofficial: we cannot provide support for them! If you have any questions about them, please contact the library's author.

The Forecast Call

https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE

APIKEY should be your Dark Sky API key. LATITUDE and LONGITUDE should be the geographic coordinates of a location in decimal degrees. (Please note that the base domain for this API request is api.forecast.io, not api.darkskyapp.com.)

The response will be a JSON-formatted object with the following properties defined:

In general, to determine the weather at a given point in time, one should examine the highest-precision data block defined (minutely, hourly, and daily respectively), taking any data available from from it and falling back to the next-highest precision data block for any properties that are missing for the point in time desired.

Data Points

A data point object represents the various weather phenomena occurring at a specific instant of time, and has many varied properties. All of these properties (except time) are optional, and will only be set if we have that type of information for that location and time. Please note that minutely data points are always aligned to the nearest minute boundary, hourly points to the top of the hour, and daily points to midnight of that day.

Data points in the daily data block (see below) are special: instead of representing the weather phenomena at a given instant of time, they are an aggregate point representing the weather phenomena that will occur over the entire day. For precipitation fields, this aggregate is a maximum; for other fields, it is an average.

Data point objects may contain the following properties:

All of the above numeric, non-time fields may, optionally, have an associated Error value defined (with the property precipIntensityError, windSpeedError, pressureError, etc.), representing our system’s confidence in its prediction. Such properties represent standard deviations of the value of their associated property; small error values therefore represent a strong confidence, while large error values represent a weak confidence. These properties are omitted where the confidence is not precisely known (though generally considered to be adequate).

Data Blocks

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

Ideally, the minutely data block will contain data for the next hour, the hourly data block for the next two days, and the daily data block for the next week; however, if we are lacking data for a given time period, the data point sequence may contain gaps or terminate early. Furthermore, if no data points for a time period are known, then the data block will be omitted from the response in its entirety. Developers are strongly encouraged, therefore, to check for the presence of data before attempting to read it.

Alert Objects

An alert object represents a severe weather warning issued for the requested location by a governmental authority (for a list of which authorities we currently support, please see data sources, below). Such objects contain the following properties:

Flags Objects

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

Forecast at a Given Time

It is also possible to request a forecast for an arbitrary point in time:

https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE,TIME

TIME should either be a UNIX time (that is, seconds since midnight GMT on 1 Jan 1970) or a string formatted as follows: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS] (with an optional time zone formatted as Z for GMT time or {+,-}[HH][MM] for an offset in minutes or seconds). For the latter format, if no timezone is present, local time (at the provided latitude and longitude) is assumed. (This string format is a subset of ISO 8601 time. An as example, 2013-05-06T12:00:00-0400.)

If a time is provided in this way, only the conditions for the day on which that time occurred (or will occur), midnight-to-midnight, are provided; in all other ways, making such a request is equivalent to getting in a time machine, going back or forward in time to the given moment, and making a normal forecast request. (In fact, this is how it is implemented behind-the-scenes.) Generally speaking, forecasted data is more accurate the nearer you query to the present moment. (That is, the present moment if you don’t have a time machine.)

Options

The API request may optionally be modified through the use of query parameters. It will respond to the following:

Response Headers

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

Notes

Data Sources

This API is backed by a wide range of data sources, which are aggregated together statistically to provide the most accurate forecast possible for a given location. Any data sources used to service a given request will be noted in the flags section of a forecast response. These sources include:

  1. Dark Sky’s own hyperlocal precipitation forecasting system (id darksky), backed by radar data from the following systems:
    • The USA NOAA’s NEXRAD system (USA).
    • The UK Met Office’s NIMROD system (UK, Ireland).
    • (More coming soon.)
  2. The USA NOAA’s LAMP system (USA, id lamp).
  3. The UK Met Office’s Datapoint API (UK, id datapoint).
  4. The Norwegian Meteorological Institute’s meteorological forecast API (global, id metno).
  5. The USA NOAA’s Global Forecast System (global, id gfs).
  6. The USA NOAA’s Integrated Surface Database (global, id isd).
  7. The USA NOAA’s Public Alert system (USA, id nwspa).
  8. The UK Met Office’s Severe Weather Warning system (UK, id metwarn).
  9. Environment Canada’s Canadian Meteorological Center ensemble model (global, id cmc).
  10. The US Navy’s Fleet Numerical Meteorology and Oceanography Ensemble Forecast System (global, id fnmoc).
  11. The USA NOAA and Environment Canada’s North American Ensemble Forecast System (global, id naefs).
  12. The USA NOAA’s North American Mesoscale Model (North America, id nam).
  13. The USA NOAA’s Rapid Refresh Model (North America, id rap).
  14. The Norwegian Meteorological Institute’s GRIB file forecast for Central Europe (Europe, id metno_ce).
  15. The Norwegian Meteorological Institute’s GRIB file forecast for Northern Europe (Europe, id metno_ne).
  16. Worldwide METAR weather reports (global, id metar).
  17. The USA NOAA/NCEP’s Short-Range Ensemble Forecast (North America, id sref).
  18. The USA NOAA/NCEP’s Real-Time Mesoscale Analysis model (North America, id rtma).
  19. The USA NOAA/ESRL’s Meteorological Assimilation Data Ingest System (global, id madis).

v1-to-v2 Migration Guide

The v2 Forecast API is designed to be as close to a pure superset of the v1 Forecast API as possible, allowing for a straightforward upgrade path if you’re currently using the v1 API and wish to upgrade. Below is a mapping of all v1 response properties and how they map to v2 properties.

v1 Property v2 Property Notes
timezone timezone and offset In v1, timezone was a string containing the IANA timezone name, the timezone abbrevation, and the timezone offset in hours. In v2, timezone contains the IANA timezone name, while offset contains the timezone offset in hours. The timezone abbreviation has no analogue in v2.
currentSummary currently.summary
currentIntensity currently.precipIntensity In v1, currentIntensity was in dBZ. In v2, precipIntensity is in inches of liquid water per hour. An equation for converting between the two is available from the Wikipedia page for dBZ.
currentTemp currently.temperature
hourSummary minutely.summary
hourPrecipitation minutely.data In v2, minutely may be omitted entirely given a lack of data.
hourPrecipitation[x].time minutely.data[x].time
hourPrecipitation[x].probability minutely.data[x].precipProbability
hourPrecipitation[x].intensity minutely.data[x].precipIntensity In v1, intensity was in dBZ. In v2, precipIntensity is in inches of liquid water per hour. An equation for converting between the two is available from the Wikipedia page for dBZ.
hourPrecipitation[x].error minutely.data[x].precipIntensityError Note the change in precipIntensity units outlined above. Additionally, in v2, this value is a one-sigma value rather than a three-sigma value, and if precipIntensity is zero, then this property will be omitted entirely.
hourPrecipitation[x].type minutely.data[x].precipType In v2, there is an additional type of precipitation: hail. Additionally, in v2, if precipIntensity is zero, then this property will be omitted.
daySummary hourly.summary
dayPrecipitation hourly.data In v2, hourly may be omitted entirely given a lack of data.
dayPrecipitation[x].time hourly.data[x].time
dayPrecipitation[x].probability hourly.data[x].precipProbability In v2, precipProbability will be omitted if precipIntensity is zero. It is also very uncommonly provided by our data sources; developers are encouraged to use rely on precipIntensity whenever possible.
dayPrecipitation[x].type hourly.data[x].precipType In v2, there is an additional type of precipitation: hail. Additionally, in v2, if precipIntensity is zero, then this property will be omitted.
dayPrecipitation[x].temp hourly.data[x].temperature
dayPrecipitation[x].cloudCover hourly.data[x].cloudCover
dayPrecipitation[x].relHumidity hourly.data[x].humidity
radarStation flags["darksky-stations"] In v2, this property will be omitted if we do not have radar coverage of the given location. Additionally, v2 makes use of multiple radar sources, so this property contains an array of station IDs, rather than a single ID. Finally, in v1, radar stations were lower case and would have their first letter omitted if they began with a "K". In v2, radar station IDs are always four letters long and upper case.
isPrecipitating not present In v2, simply check if currently.precipIntensity is nonzero.
minutesUntilChange not present In v2, iterate over minutely.data and hourly.data in order, finding the first data point for which currently.precipIntensity !== 0 does not equal datapoint.precipIntensity !== 0. Once that data point is found, minutesUntilChange may be calculated as follows: (datapoint.time - currently.time) / 60.
checkTimeout not present Use either the Cache-Control or Expires HTTP response headers.