The Forecast API allows you to look up the weather anywhere on the globe, returning (where available):

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

There are two types of API calls. A forecast request returns the current forecast (for the next week):,LONGITUDE

A time-machine request returns the observed weather at a given time (for many places, up to 60 years in the past):,LONGITUDE,TIME


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, and Alex Handy has provided a CodeEnvy IDE for a Java API wrapper of our 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,LONGITUDE

APIKEY should be your Dark Sky API key. LATITUDE and LONGITUDE should be the geographic coordinates of a location in decimal degrees.

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.

The Time Machine Call

It is also possible to request a forecast for an arbitrary date in the past or future:,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 hours or minutes). 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.)

A time-machine request is identical in structure to a forecast request, except for the following differences:

Note that we only store the best data we have for a given location and time: in the past, this will usually be observations from weather stations (though we may fall back to forecasted data if we don't have any observations); in the future, this will be numerical forecast models for the next week and seasonal averages beyond that.

Data Points

A data point object contains various properties, each representing a particular weather phenomenon occurring at a specific point in time. 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.

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 (unless otherwise noted) the average weather conditions that will occur over the entire day.

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.

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). Alerts are only supported for forecast requests: no alert objects are returned for time machine requests. Alert 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:


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:


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).