Estimated reading time: 10 minutes
Since the Dark Sky API was officially discontinued in 2023, many developers have been searching for a reliable replacement. The Visual Crossing Timeline Weather API provides the direct replacement that you need to minimize your conversion effort and ensure that your data costs remain stable.
Both the code-level API and the pricing model directly mirror what was available to users of the Dark Sky API. Just like Dark Sky, you can get started with a free account and a generous daily free query allowance. So there is no reason not to get started with your Dark Sky weather API conversion now.
Replacing the Dark Sky API functionality
The Dark Sky Time Machine API was popular because it made the process of looking up past, present, and future weather data as simple as a single API call.
By simply specifying a location and a historical date within the past 50 years, the Time Machine API would provide historical weather records for that location and date. When you requested a near-term date, the API would provide data based on the standard. model-based forecast.
A more distant future data would provide a statistics-based forecast using typical weather pattern data based on observations of the past decades. Easiest of all, you could get the current conditions and standard forecast by providing no date at all.
The Visual Crossing Timeline Weather API works in exactly the same way and includes many useful upgrades. Not only can you seamlessly request historical, standard forecast, and statistical forecasts via the same API, but the Timeline API allows you to specify a date range instead of just a single date.
This range can cover any period, including a combination of past, present, and future dates. You can even use dynamic date shortcuts such as yesterday, last 7 days, and last year.
Both the Timeline result data format and the weather elements it contains are designed to make replacing the weather API in Dark Sky-based apps easy. Like the Dark Sky API, the Visual Crossing Timeline result format is a standard JSON that can be parsed directly in any modern coding language, scripting tool, or business application.
Coding examples are available for popular languages such as Python and Java, as well as business environments such as Excel and an Outlook add-in.
Replacing the Dark Sky API in code
Making Timeline Weather API queries is as easy as submitting a URL request, just like you are used to in the Dark Sky API. Let’s consider a few examples.
Forecast and current conditions
In our first example, we are going to request the standard weather forecast and the current conditions for the location of Washington, DC. Since forecast and current conditions are the default results, all we need to do is pass the location and an API Key as parameters to the query. The query URL looks like this:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Washington,DC?key=<YOUR_API_KEY>
The result of this query will be a JSON containing three primary pieces of data and some additional metadata details. The first major data piece is an array of “days” containing 15-day records, one for each day in the standard forecast.
Inside each day element are the weather measures describing the forecast summary for the given day, as well as a child array of “hours.” Each hour record contains the specific weather forecast measures for that hour.
Another major data component in this result is the “currentConditions” record that gives the weather measures currently being seen at the requested location. The final major piece is the “alert” array.
This contains a list of weather alerts currently applicable to the requested location. Note that this array will be empty when no weather alerts currently apply to the location, but there may also be multiple alerts during times of weather turmoil. Understanding this basic format for both queries and results will allow you to easily construct any Timeline Weather API query.
Weather on a specific date – past or future
As a slightly more complex example, we’ll request the weather on a specific date for Washington, DC. July 4th seems like a very appropriate choice. In order to do this, all we need to do is add the date to our query URL as a second parameter.
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Washington,DC/2023-07-04?key=<YOUR_API_KEY>
Since July 4th, 2023, is multiple months in the future at the time of writing, the Timeline Weather API will return a statistics-based forecast based on the climate patterns over the last decades at the requested location.
As a result, we will get a JSON in the same format described above, only this time containing a single day record in the days array. This day record contains the typical weather measures that can be expected on that day.
However, you may be reading this article on a date when July 4th, 2023, is a historical date. If you run this example query, then the query results will contain a single entry in the “days” array.
This entry will contain the weather measures actually observed on that day in the requested location. Just like the forecast example above, the day record contains an “hours” array with an entry for each hour in the day.
If you run this query during the exact date window when July 4th, 2023, is in the 15-day forecast period (for example, on July 1st, 2023), you will get a single day’s data pulled from the standard forecast.
The result format will look just like the historical results, with a single day’s summary weather measures in the “days” array and an array of “hours” with the detailed weather elements for each hour.
Beyond Dark Sky – querying a date range
There are various additional features that the Timeline Weather API permits that were not possible in Dark Sky. One of the most useful examples is the ability to provide a date range instead of just a single date. A query that fetches the weather for the entire month of July 2021 would look like this.
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Washington,DC/2022-7-1/2022-7-31?key=<YOUR_API_KEY>
Note that this URL provides two dates, a start and an end. The result of running this query will be the same format as above. The “days” array will contain 31 entries, one for each day in July 2022, and inside each day will be an array of the hourly details.
It is worth noting that the time range for a single query can span historical data, standard forecast data, and statistical forecast data. The weather engine will determine the best sources to get each record to fill your request. So your application can remain entirely unaware if the data being requested is from the past or the future.
Dark Sky API parameter conversion to Timeline Weather API
The following table shows how existing Dark Sky API parameters match to the parameters found in the Timeline Weather API. For more information on the parameters, see the Timeline Weather API Documentation.
| Dark Sky API | Timeline Weather API | Notes |
| apparentTemperature | feelslike | |
| apparentTemperatureHigh | feelslikeMax | |
| apparentTemperatureLow | feelslikeMin | |
| cloudCover | cloudcover | |
| dewPoint | dew | |
| humidity | humidity | |
| icon | icon | |
| moonPhase | moonphase | |
| precipIntensity | precip & snow | Hourly precip and snow fields provide a precipitation rate per hour. |
| precipProbability | precipprob | |
| pressure | pressure | |
| summary | description and conditions | description for natural language text and conditions for a list of weather conditions. |
| sunriseTime | sunrise & sunriseEpoch | Epoch times provide exact conversion |
| sunsetTime | sunset & sunsetEpoch | Epoch times provide exact conversion |
| temperature | temp | |
| temperatureMax | tempmax | |
| temperatureMin | tempmin | |
| time | datetime & datetimeEpoch | |
| timezone | timezone & tzoffset | Epoch times provide exact conversion |
| uvIndex | uvindex | |
| visibility | visibility | |
| windBearing | winddir | |
| windGust | windgust | |
| windSpeed | windspeed | |
| – | precipcover | Not available in Dark Sky API |
| – | severerisk | Not available in Dark Sky API |
| – | solarradiation | Not available in Dark Sky API |
Units and UnitGroups
The Timeline Weather API uses the unitGroup parameter to specify the units that should be used for the parameters. By default, the API is set to ‘us’ units. unitGroup=metric changes the result to metric.
Maximum and minimum value time
We do not include direct properties for the time of the maximum and minimum values (temperatureMinTime, temperatureMaxTime, apparentTemperatureMinTime, apparentTemperatureMaxTime, precipIntensityMaxTime).
If you require these timings, you may access them by identifying the appropriate hour in the hours data and reading the datetime properties associated with that hour.
Replacing the Dark Sky API pricing model
The pricing model of the Timeline Weather API is also designed to be completely familiar to Dark Sky API users. Every account gets 1000 free records every day. Usage beyond that is billed at $0.0001 per record.
A full forecast counts as a single record, as does each row of history or statistical forecast data. In this way, the pricing behaves exactly like a Dark Sky user would expect since Dark Sky allowed only a single date per query.
However, if you take advantage of the date range functionality discussed above, each record of historical and ultra-long-range statistical forecast data will count as a single record for billing purposes.
Beyond Dark Sky pricing, Visual Crossing Weather also offers monthly plans that provide large quantities of data at a fixed monthly cost. Monthly plans offer a valuable savings opportunity for high-volume users, especially those who need a lot of historical data.
Visual Crossing Weather’s flexible options allow you to choose an optimal plan to fit any use case.
Summary
The Visual Crossing Weather Timeline API is the perfect replacement for the Dark Sky API. The queries are done via a URL API that is instantly familiar and easy to use. The results are returned as standard JSON that can be parsed in any coding or scripting language, as well as various business and data science applications.
CSV output is also an option if you prefer. Finally, the payment model is exactly what a Dark Sky user would expect. Your free account gets 1000 records for free each day, so there is no reason not to get started on your conversion now.
If you need more information on using the Timeline Weather API or on our weather data in general, you can reach our weather experts. They will be happy to help you convert your Dark Sky API app to use Visual Crossing Timeline Weather API or with any other weather topic.
FAQs: How to Replace the Dark Sky API with Visual Crossing
Why is the Dark Sky API being discontinued?
Apple acquired Dark Sky and announced it would shut down the API. Developers who previously relied on Dark Sky for accessing weather data now need to migrate to another provider. The Visual Crossing Timeline Weather API can be used to replace Dark Sky’s functionality with minimal changes to code or cost.
What makes the Visual Crossing Timeline Weather API a good replacement for Dark Sky?
The Timeline API mirrors Dark Sky in both structure and usage. It uses RESTful calls, returns JSON format, and supports queries for current weather data, weather forecast, and historical weather data—all in a single, unified endpoint.
Does Visual Crossing support historical, current, and forecast weather data like Dark Sky?
Yes. You can access historical weather data, real-time conditions, and weather forecast data in one query. You can also request statistical weather forecasts for long-range planning using observed climate patterns.
How do I convert Dark Sky API parameters to Visual Crossing equivalents?
Visual Crossing provides a direct mapping for Dark Sky fields, such as temperature to temp, precipProbability to precipprob, and apparentTemperatureHigh to feelslikeMax. A complete comparison is included in the documentation to simplify migration.
Is the Visual Crossing API compatible with Dark Sky’s JSON format?
Yes. The weather data is returned in standard JSON format, making it easy for developers to parse using existing Dark Sky-compatible code in languages like Python, Java, or even Excel-based tools.
How does Visual Crossing’s pricing compare to Dark Sky’s pricing model?
Visual Crossing offers a free plan with 1,000 records per day and a pay-as-you-go model beyond that at $0.0001 per record. This mirrors the Dark Sky approach while also offering monthly plans for higher-volume weather data use cases.
Can I get hourly and daily weather data using Visual Crossing’s Timeline API?
Yes. Each day record includes a nested array of hourly forecasts, including key metrics such as temperature, wind speed, and weather conditions. Both daily summaries and detailed hourly data are returned in the same response.
How do I request weather data for a date range instead of a single day?
Simply specify a start and end date in your query. The Timeline API supports full date ranges, allowing you to fetch historical weather or future forecast data for multiple days in one call—something Dark Sky didn’t offer.