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):,LONGITUDE

The second lets one query for a specific time, past or future (for many places, 60 years in the past to 10 years in the future):,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. (Please note that the base domain for this API request is, not

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

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 (in local time), are provided. Please 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, data will be more accurate the closer to the present moment you request.


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