Time Machine Request


A Time Machine Request returns the observed (in the past) or forecasted (in the future) hour-by-hour weather and daily weather conditions for a particular date. A Time Machine request is identical in structure to a Forecast Request, except:

  • The currently data point will refer to the time provided, rather than the current time.
  • The minutely data block will be omitted, unless you are requesting a time within an hour of the present.
  • The hourly data block will contain data points starting at midnight (local time) of the day requested, and continuing until midnight (local time) of the following day.
  • The daily data block will contain a single data point referring to the requested date.
  • The alerts data block will be omitted.

Example Request

GET https://api.darksky.net/forecast/0123456789abcdef9876543210fedcba/42.3601,-71.0589,409467600?exclude=currently,flags

  "latitude": 42.3601,
  "longitude": -71.0589,
  "timezone": "America/New_York",
  "hourly": {
    "summary": "Snow (3–6 in.) and dangerously windy starting in the afternoon.",
    "icon": "snow",
    "data": [
        "time": 255589200,
        "summary": "Mostly Cloudy",
        "icon": "partly-cloudy-night",
        "precipIntensity": 0,
        "precipProbability": 0,
        "temperature": 23.47,
        "apparentTemperature": 17.05,
        "dewPoint": 16.42,
        "humidity": 0.74,
        "windSpeed": 5,
        "windGust": 11.31,
        "windBearing": 350,
        "visibility": 9.6,
        "cloudCover": 0.78,
        "pressure": 1026.79
  "daily": {
    "data": [
        "time": 255589200,
        "summary": "Mixed precipitation (3–6 in. of snow) and windy starting in the afternoon.",
        "icon": "snow",
        "sunriseTime": 255613996,
        "sunsetTime": 255650764,
        "moonPhase": 0.97,
        "precipIntensity": 0.0338,
        "precipIntensityMax": 0.17,
        "precipIntensityMaxTime": 255657600,
        "precipProbability": 0.87,
        "precipType": "snow",
        "precipAccumulation": 6.485,
        "temperatureMin": 23.33,
        "temperatureMinTime": 255600000,
        "temperatureMax": 34,
        "temperatureMaxTime": 255632400,
        "apparentTemperatureMin": 11.87,
        "apparentTemperatureMinTime": 255650400,
        "apparentTemperatureMax": 21.44,
        "apparentTemperatureMaxTime": 255632400,
        "dewPoint": 26.15,
        "humidity": 0.86,
        "windSpeed": 24.52,
        "windGust": 29.11,
        "windBearing": 57,
        "visibility": 4.69,
        "cloudCover": 0.96,
        "pressure": 1016.49

Request Parameters

Required parameters slot directly into the request URL. Optional parameters should be specified as HTTP query parameters.

  • key required
    Your Dark Sky secret key. (Your secret key must be kept secret; in particular, do not embed it in JavaScript source code that you transmit to clients.)
  • latitude required
    The latitude of a location (in decimal degrees). Positive is north, negative is south.
  • longitude required
    The longitude of a location (in decimal degrees). Positive is east, negative is west.
  • time required
    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][timezone]. timezone should either be omitted (to refer to local time for the location being requested), Z (referring to GMT time), or +[HH][MM] or -[HH][MM] for an offset from GMT in hours and minutes. The timezone is only used for determining the time of the request; the response will always be relative to the local time zone.
  • exclude=[blocks] optional

    Exclude some number of data blocks from the API response. This is useful for reducing latency and saving cache space. The value blocks should be a comma-delimeted list (without spaces) of any of the following:

    • currently
    • minutely
    • hourly
    • daily
    • alerts
    • flags
  • lang=[language] optional

    Return summary properties in the desired language. (Note that units in the summary will be set according to the units parameter, so be sure to set both parameters appropriately.) language may be:

    • ar: Arabic
    • az: Azerbaijani
    • be: Belarusian
    • bg: Bulgarian
    • bs: Bosnian
    • ca: Catalan
    • cs: Czech
    • de: German
    • el: Greek
    • en: English (which is the default)
    • es: Spanish
    • et: Estonian
    • fr: French
    • hr: Croatian
    • hu: Hungarian
    • id: Indonesian
    • it: Italian
    • is: Icelandic
    • ja: Japanese
    • ka: Georgian
    • kw: Cornish
    • nb: Norwegian Bokmål
    • nl: Dutch
    • pl: Polish
    • pt: Portuguese
    • ru: Russian
    • sk: Slovak
    • sl: Slovenian
    • sr: Serbian
    • sv: Swedish
    • tet: Tetum
    • tr: Turkish
    • uk: Ukrainian
    • x-pig-latin: Igpay Atinlay
    • zh: simplified Chinese
    • zh-tw: traditional Chinese

    If you require a language not listed here, please consider contributing to our API translation module on Github.

  • units=[units] optional

    Return weather conditions in the requested units. [units] should be one of the following:

    • auto: automatically select units based on geographic location
    • ca: same as si, except that windSpeed and windGust are in kilometers per hour
    • uk2: same as si, except that nearestStormDistance and visibility are in miles, and windSpeed and windGust are in miles per hour
    • us: Imperial units (the default)
    • si: SI units

    SI units are as follows:

    • summary: Any summaries containing temperature or snow accumulation units will have their values in degrees Celsius or in centimeters (respectively).
    • nearestStormDistance: Kilometers.
    • precipIntensity: Millimeters per hour.
    • precipIntensityMax: Millimeters per hour.
    • precipAccumulation: Centimeters.
    • temperature: Degrees Celsius.
    • temperatureMin: Degrees Celsius.
    • temperatureMax: Degrees Celsius.
    • apparentTemperature: Degrees Celsius.
    • dewPoint: Degrees Celsius.
    • windSpeed: Meters per second.
    • windGust: Meters per second.
    • pressure: Hectopascals.
    • visibility: Kilometers.

Response Format

Details of how the response is formatted may be found here.