Dark Sky Time Machine API

openapi: 3.0.3
info:
  title: Dark Sky Forecast Time Machine API
  description: 'The Dark Sky Forecast API (now shut down; replaced by Apple WeatherKit) provided hyperlocal weather data for any latitude/longitude worldwide, including current conditions, minute-by-minute precipitation for the next 60 minutes, hour-by-hour forecasts for the next 48 hours, and day-by-day summaries for the next 7 days. It also supported Time Machine requests to retrieve observed or forecast weather for arbitrary points in the past or future.

    New developer sign-ups closed in March 2020 when Apple acquired Dark Sky. The API was permanently shut down on March 31, 2023.

    '
  version: 1.0.0
  contact:
    name: Dark Sky (Apple)
    url: https://darksky.net/dev
  license:
    name: Proprietary
servers:
- url: https://api.darksky.net
  description: Dark Sky API (historical, now shut down)
security:
- ApiKeyPath: []
tags:
- name: Time Machine
  description: Historical or future weather data for a specific point in time
paths:
  /forecast/{key}/{latitude},{longitude},{time}:
    get:
      operationId: getTimeMachine
      summary: Time Machine — historical or future weather data
      description: 'Returns the observed (or forecast) weather conditions for a specific point in time. The time parameter may be a Unix timestamp (seconds since epoch) or an ISO 8601 datetime string. Historical requests return data based on station observations; future requests return forecast data.

        '
      tags:
      - Time Machine
      parameters:
      - $ref: '#/components/parameters/key'
      - $ref: '#/components/parameters/latitude'
      - $ref: '#/components/parameters/longitude'
      - name: time
        in: path
        required: true
        description: 'Either a Unix timestamp (integer seconds since the Unix epoch) or an ISO 8601 datetime string such as [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS][timezone]. The timezone is optional; if not provided, local time for the specified location is assumed.

          '
        schema:
          type: string
      - $ref: '#/components/parameters/exclude'
      - $ref: '#/components/parameters/lang'
      - $ref: '#/components/parameters/units'
      responses:
        '200':
          description: Successful time machine response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForecastResponse'
        '400':
          description: Bad request — invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DataPoint:
      type: object
      description: 'A data point object contains various properties, each representing the average (or maximum, or minimum) of a particular weather phenomenon occurring during a period of time. All properties of a data point object are optional; it is possible, with some units, for a precipitation type property to be omitted.

        '
      properties:
        time:
          type: integer
          format: int64
          description: Unix timestamp (seconds since epoch) of the data point.
        summary:
          type: string
          description: Human-readable text summary of the data point.
        icon:
          $ref: '#/components/schemas/Icon'
        sunriseTime:
          type: integer
          format: int64
          description: Sunrise time as a Unix timestamp (daily data points only).
        sunsetTime:
          type: integer
          format: int64
          description: Sunset time as a Unix timestamp (daily data points only).
        moonPhase:
          type: number
          description: 'Fractional part of the lunation number for the given day (daily only). 0 = new moon, 0.25 = first quarter, 0.5 = full moon, 0.75 = last quarter.

            '
          minimum: 0
          maximum: 1
        nearestStormBearing:
          type: integer
          description: 'Direction (in degrees, 0–360, measured clockwise from north) of the nearest storm (currently data points only).

            '
        nearestStormDistance:
          type: number
          description: Distance to the nearest storm in the requested units (currently only).
        precipIntensity:
          type: number
          description: 'Intensity of precipitation in the requested units (inches/hour for us/uk2/ca; mm/hour for si/auto). 0 means no precipitation.

            '
        precipIntensityMax:
          type: number
          description: Maximum precipitation intensity during the period (daily only).
        precipIntensityMaxTime:
          type: integer
          format: int64
          description: Time of maximum precipitation intensity as Unix timestamp (daily only).
        precipProbability:
          type: number
          description: Probability of precipitation between 0 and 1.
          minimum: 0
          maximum: 1
        precipAccumulation:
          type: number
          description: Accumulated snowfall in inches (or cm for si) during the period (hourly/daily).
        precipType:
          type: string
          enum:
          - rain
          - snow
          - sleet
          description: Type of precipitation. Only defined if precipIntensity > 0.
        temperature:
          type: number
          description: Air temperature (Fahrenheit for us; Celsius for si/ca/uk2).
        apparentTemperature:
          type: number
          description: Apparent ("feels like") temperature in the requested units.
        temperatureHigh:
          type: number
          description: Daytime high temperature (daily only).
        temperatureHighTime:
          type: integer
          format: int64
          description: Unix timestamp of daytime high temperature (daily only).
        temperatureLow:
          type: number
          description: Overnight low temperature (daily only).
        temperatureLowTime:
          type: integer
          format: int64
          description: Unix timestamp of overnight low temperature (daily only).
        temperatureMin:
          type: number
          description: Daily minimum temperature (daily only).
        temperatureMinTime:
          type: integer
          format: int64
          description: Unix timestamp of daily minimum temperature (daily only).
        temperatureMax:
          type: number
          description: Daily maximum temperature (daily only).
        temperatureMaxTime:
          type: integer
          format: int64
          description: Unix timestamp of daily maximum temperature (daily only).
        apparentTemperatureHigh:
          type: number
          description: Daytime high apparent temperature (daily only).
        apparentTemperatureHighTime:
          type: integer
          format: int64
          description: Unix timestamp of daytime high apparent temperature (daily only).
        apparentTemperatureLow:
          type: number
          description: Overnight low apparent temperature (daily only).
        apparentTemperatureLowTime:
          type: integer
          format: int64
          description: Unix timestamp of overnight low apparent temperature (daily only).
        dewPoint:
          type: number
          description: Dew point temperature in the requested units.
        humidity:
          type: number
          description: Relative humidity, between 0 and 1.
          minimum: 0
          maximum: 1
        pressure:
          type: number
          description: Sea-level air pressure in millibars.
        windSpeed:
          type: number
          description: Wind speed in the requested units.
        windGust:
          type: number
          description: Wind gust speed in the requested units.
        windGustTime:
          type: integer
          format: int64
          description: Unix timestamp of maximum wind gust (daily only).
        windBearing:
          type: integer
          description: Direction of wind in degrees, measured clockwise from north. 0 = north.
          minimum: 0
          maximum: 360
        cloudCover:
          type: number
          description: Fraction of sky covered by clouds, between 0 and 1.
          minimum: 0
          maximum: 1
        uvIndex:
          type: integer
          description: UV index.
        uvIndexTime:
          type: integer
          format: int64
          description: Unix timestamp of maximum UV index (daily only).
        visibility:
          type: number
          description: 'Average visibility in miles (us/uk2) or kilometers (si/ca), capped at 10 miles.

            '
          maximum: 10
        ozone:
          type: number
          description: Columnar density of total atmospheric ozone in Dobson units.
    ErrorResponse:
      type: object
      required:
      - code
      - error
      properties:
        code:
          type: integer
          description: HTTP status code.
        error:
          type: string
          description: Human-readable description of the error.
    ForecastResponse:
      type: object
      description: Top-level response from a forecast or time machine request.
      required:
      - latitude
      - longitude
      - timezone
      properties:
        latitude:
          type: number
          format: double
          description: Latitude of the request location.
        longitude:
          type: number
          format: double
          description: Longitude of the request location.
        timezone:
          type: string
          description: IANA timezone name for the requested location (e.g. "America/New_York").
        offset:
          type: number
          description: Current timezone offset in hours from UTC.
        currently:
          $ref: '#/components/schemas/DataPoint'
        minutely:
          $ref: '#/components/schemas/DataBlock'
        hourly:
          $ref: '#/components/schemas/DataBlock'
        daily:
          $ref: '#/components/schemas/DataBlock'
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
          description: Array of severe weather alerts for the requested location.
        flags:
          $ref: '#/components/schemas/Flags'
    Flags:
      type: object
      description: Metadata about the request, including data sources used.
      properties:
        sources:
          type: array
          items:
            type: string
          description: Machine-readable identifiers of weather data sources used.
        nearest-station:
          type: number
          description: Distance to the nearest weather station in requested units.
        units:
          type: string
          enum:
          - auto
          - ca
          - si
          - uk2
          - us
          description: Units used in the response.
    Alert:
      type: object
      description: Severe weather alert issued by a governmental weather authority.
      required:
      - title
      - time
      - expires
      - description
      - uri
      properties:
        title:
          type: string
          description: Short text summary of the alert.
        regions:
          type: array
          items:
            type: string
          description: Names of regions covered by the alert.
        severity:
          type: string
          enum:
          - advisory
          - watch
          - warning
          description: Severity of the alert.
        time:
          type: integer
          format: int64
          description: Unix timestamp of the alert's onset.
        expires:
          type: integer
          format: int64
          description: Unix timestamp when the alert expires.
        description:
          type: string
          description: Detailed text description of the alert from the issuing authority.
        uri:
          type: string
          format: uri
          description: HTTP URI linking to the full text of the alert.
    DataBlock:
      type: object
      description: 'A data block contains a human-readable summary and a data array of DataPoint objects.

        '
      properties:
        summary:
          type: string
          description: Human-readable text summary of the data block.
        icon:
          $ref: '#/components/schemas/Icon'
        data:
          type: array
          items:
            $ref: '#/components/schemas/DataPoint'
          description: Array of data points for the block (one per minute, hour, or day).
    Icon:
      type: string
      enum:
      - clear-day
      - clear-night
      - rain
      - snow
      - sleet
      - wind
      - fog
      - cloudy
      - partly-cloudy-day
      - partly-cloudy-night
      description: 'Machine-readable icon name representing the weather conditions. Suitable for selecting an icon to display.

        '
  parameters:
    longitude:
      name: longitude
      in: path
      required: true
      description: Longitude of the location, in decimal degrees (positive is east).
      schema:
        type: number
        format: double
        minimum: -180
        maximum: 180
    latitude:
      name: latitude
      in: path
      required: true
      description: Latitude of the location, in decimal degrees (positive is north).
      schema:
        type: number
        format: double
        minimum: -90
        maximum: 90
    key:
      name: key
      in: path
      required: true
      description: Your Dark Sky API secret key.
      schema:
        type: string
    exclude:
      name: exclude
      in: query
      required: false
      description: 'Comma-separated list of data blocks to exclude from the response. Excluding unneeded blocks reduces latency and conserves bandwidth.

        '
      schema:
        type: string
        example: minutely,alerts
      examples:
        excludeMinutely:
          value: minutely
          summary: Exclude minutely block
        excludeMultiple:
          value: minutely,hourly
          summary: Exclude minutely and hourly blocks
    units:
      name: units
      in: query
      required: false
      description: 'Returns weather conditions in the requested units. Defaults to "auto". - auto: Automatically selects units based on geographic location. - ca: SI units, but with km/h for wind speed. - si: SI units (m/s for wind speed, Celsius for temperature). - uk2: SI units, but with miles for visibility and mph for wind speed. - us: Imperial units (the default for the United States).

        '
      schema:
        type: string
        enum:
        - auto
        - ca
        - si
        - uk2
        - us
        default: auto
    lang:
      name: lang
      in: query
      required: false
      description: 'Returns text summaries in the given language. Defaults to "en" (English).

        '
      schema:
        type: string
        enum:
        - ar
        - az
        - be
        - bg
        - bn
        - bs
        - ca
        - cs
        - cy
        - da
        - de
        - el
        - en
        - eo
        - es
        - et
        - fa
        - fi
        - fr
        - ga
        - gl
        - gu
        - he
        - hi
        - hr
        - hu
        - id
        - is
        - it
        - ja
        - ka
        - kn
        - ko
        - kw
        - lv
        - ml
        - mr
        - ms
        - nl
        - false
        - pa
        - pl
        - pt
        - ro
        - ru
        - sk
        - sl
        - sr
        - sv
        - ta
        - te
        - tet
        - tr
        - uk
        - ur
        - vi
        - x-pig-latin
        - zh
        - zh-tw
        default: en
  securitySchemes:
    ApiKeyPath:
      type: apiKey
      in: path
      name: key
      description: 'Dark Sky API key included as the first path segment after /forecast/. Obtain your key from https://darksky.net/dev.

        '
externalDocs:
  description: Dark Sky API Documentation (archived)
  url: https://darksky.net/dev/docs