With the Dark Sky API shutting down in a few months, now is the ideal time to convert your weather application to use a more stable provider. The Visual Crossing Timeline Weather API provides the direct replacement that you need to minimize your conversion effort and ensure that you 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 to not 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 simplify specifying a locations and an 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 distance 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 several useful upgrades. Not only can you seamlessly request historical, standard forecast, and statistical forecasts via the same API, 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 measures it contains are designed to make replacing the weather API in Dark Sky-based apps east. 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 are 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 Washington, DC. Since forecast and current conditions are the default results, all we need to do is to 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 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, seem like a very appropriate choice. In order to do this, all we need to do is to add the date onto 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 as I am writing this, the Timeline Weather API will return a statistics based forecast based on the climate patterns over the last decades at the request location. As the 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 an 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 measures 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 moth 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 date time 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. An 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 can offer a valuable savings 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. 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.