openapi: 3.0.3 info: title: Dark Sky Forecast 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: [] paths: /forecast/{key}/{latitude},{longitude}: get: operationId: getForecast summary: Current and forecast weather data description: > Returns the current weather conditions and forecast for the given latitude and longitude. The response always contains a currently data point, and may contain minutely, hourly, daily, alerts, and flags data blocks depending on the exclude parameter and data availability. tags: - Forecast parameters: - $ref: '#/components/parameters/key' - $ref: '#/components/parameters/latitude' - $ref: '#/components/parameters/longitude' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/extend' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/units' responses: '200': description: Successful forecast response headers: X-Forecast-API-Calls: description: Number of API calls made by this account today schema: type: integer X-Response-Time: description: Server-side response time in milliseconds schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForecastResponse' example: latitude: 37.8267 longitude: -122.4233 timezone: America/Los_Angeles offset: -8 currently: time: 1609459200 summary: Partly Cloudy icon: partly-cloudy-day temperature: 55.6 apparentTemperature: 53.1 humidity: 0.78 windSpeed: 9.3 windBearing: 245 precipProbability: 0.12 precipIntensity: 0.0045 '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' /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: 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. parameters: key: name: key in: path required: true description: Your Dark Sky API secret key. schema: type: string 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 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 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 extend: name: extend in: query required: false description: > When set to "hourly", returns hourly data for the next 168 hours (7 days) rather than the default 48 hours. schema: type: string enum: - hourly 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 - no - pa - pl - pt - ro - ru - sk - sl - sr - sv - ta - te - tet - tr - uk - ur - vi - x-pig-latin - zh - zh-tw default: en 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 schemas: 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' 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). 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. 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. 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. 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. ErrorResponse: type: object required: - code - error properties: code: type: integer description: HTTP status code. error: type: string description: Human-readable description of the error. tags: - name: Forecast description: Current and forecast weather data for a given location - name: Time Machine description: Historical or future weather data for a specific point in time externalDocs: description: Dark Sky API Documentation (archived) url: https://darksky.net/dev/docs