How to replace the Dark Sky API with Visual Crossing Weather API

Dark Sky have recently announced the termination of their Dark Sky Weather API. In this article, we describe the steps to convert an existing application from the Dark Sky API to the Visual Crossing Weather API.

Pricing for the Visual Crossing Weather API starts at $0.0001/result after 1000 per day for free. See the plan details.

API Differences

Both the Dark Sky API and the Visual Crossing Weather API offer weather data APIs however there are differences in approach and the type of data that is available. Most of the differences are quite simple to change in an existing application.

Weather API endpoints

Dark sky API endpoints

Dark Sky offered two API endpoints- the Forecast Request and the Time Machine Request.

The Forecast Request offered the ability to retrieve the weather forecast and current conditions for a single location. The forecast was offered at the minute, hourly and daily level depending on the length of time into the future.

The Time machine request offered the ability to retrieve the weather data for a single location for a given date, whether that date was in the past or future. If the date given is in the past, the results are the historical weather observations for nearby weather stations.

If the time machine request was in the future, then the result is a weather forecast for that location based.

Visual Crossing API endpoints

We offer the Timeline Weather API to provide a seamless upgrade path to the forecast and time machine requests. The Timeline API provides historical observations, current weather forecast and future statistical forecasts all from a single weather api request.

To see a full comparison of Dark Sky API parameters and other features, see How to replace the Dark Sky API with the Timeline Weather API .

Location lookup

The Dark Sky API requires that all requests are submitted using the latitude and longitude of the query location.

The Visual Crossing API support latitude, longitude locations plus also locations based on address or partial address such as city and state, city and country etc.

Authentication and security

Both Dark Sky and the Visual Crossing Weather API support HTTPS secure transition. In addition, both APIs use API Keys to authenticate requests.

The Visual Crossing Weather API does support CORS requests from client so it is possible to call the Visual Crossing Weather API directly from the browser rather than having to proxy via a server.

Quick steps to migrate a Dark Sky API Forecast request

Here are the main steps to convert an existing Dark Sky API application to the Visual Crossing Weather API:

1. Sign up for an free account of the Visual Crossing Weather API. For more information on signing up for an account, please see our help.

2. Construct the API request to request the forecast and current conditions. If you are using the Dark Sky Timeline API, you can also include weather data for any historical, forecast or future date (or a range of dates).

3. Retrieve the data and incorporate the results into your application. Dark Sky only supported a JSON output structure. Visual Crossing API supports both JSON in the Timeline API. If you are looking for CSV data, we offer it through some of our other end points.

4. Consider optional optimizations such as removing any unnecessary address lookup requests that your application may currently need to make. If you are making multiple Dark Sky API requests for different dates, you can combine them into a single call in in our Timeline API.

Also as the Visual Crossing Weather supports CORS requests, you can considering removing any code that you have added to support the Dark Sky API request.

Detailed steps to migrate a Dark Sky API Forecast request

We will focus on users of Dark Sky’s ‘ Forecast Request ‘ and the ‘ Time Machine Request ‘.

Step 1 – Sign up for a free account

The Visual Crossing Weather API offers multiple Weather API tiers to fit any requirement. Prices start at free for up to 1000 result rows per day and then you can either pay the same cost as Dark Sky ($0.0001/result) or choose a fixed price plan. For more information on our pricing, visit our pricing and editions page.

To sign up for a free account, visit our Weather Data Services .

Step 2 – Construct the Timeline Weather API request

Replacing a Dark Sky API Forecast Request

A typical Dark Sky weather forecast request has the following form:

https://api.darksky.net/forecast/[key]/[latitude],[longitude] 

For example: 
https://api.darksky.net/forecast/0123456789abcdef9876543210fedcba/38.96972,-77.38519

The equivalent of this weather forecast request in the Visual Crossing Timeline Weather API is:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.96972,-77.38519?key=YOUR_KEY

This will request the 15-day weather forecast and current weather conditions for the supplied location. The result will include both daily and hourly records for each day.

Request the location as an address, not latitude,longitude

It is not necessary to send the location as a latitude,longitude value. You can specify an address or partial address such as:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/New York City,NY,USA?key=YOUR_KEY

Request weather data in metric units

The default output units are the US units such Fahrenheit, Miles, Feet etc. If you would prefer metric units, you can add the unitGroup parameter.

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/New York City,NY,USA?unitGroup=metric&key=YOUR_KEY

For more details on the available parameters, please see the full Timeline Weather API documentation.

Replacing a Dark Sky API Time Machine Request

A typical Dark Sky API Time Machine request is:

https://api.darksky.net/forecast/[key]/[latitude],[longitude][time]

For example:
https://api.darksky.net/forecast/0123456789abcdef9876543210fedcba/42.3601,-71.0589,1602720000 

The equivalent Timeline Weather API request is:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.96972,-77.38519/2020-10-15?key=YOUR_KEY 

This will retrieve the weather data for October 15th, 2020. The Timeline API select between retrieving historical observation data, weather forecast data and statistical weather forecast data depending on the date entered.

Retrieving multiple dates in a single request

The following will retrieve the weather data between October 15th, 2020 and December 31st, 2020.

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.96972,-77.38519/2020-10-15/2020-12-31?key=YOUR_KEY 

Assuming that the current date is November 15th, 2020, then this query will result in data from historical observations (through November 15th), weather forecast data (until about November 30th) and then statistical weather forecast data for December. This transition is handled automatically by the API. The result data will indicate which type of record has been returned.

You can also use dynamic date periods to handle moving date ranges. Just substitute the first date parameter with a period rule and omit the second date parameter:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Berlin,Germany/last30days?key=YOUR_KEY 

Step 3 – Retrieve the data and incorporate the results into your application.

In the requests above, we requested the output in JSON format. Here is Dark Sky’s sample output structure.

{
          "currently": {
              "time": 1509993277,
              ...
          },
          "hourly": {
              
              "data": [{
                  "time": 1509991200,

              },  ...
            ]
          },
         "daily": {
              "data": [{
                  "time": 1509944400,
                  
              },
            ...
            ]
          },
          "alerts": [
          {
            "...
          },
          ...
          ],
}

As you can see, the hourly, daily and current conditions are contained within the same request. Each time period of the hourly and daily data is an element of of time period array.

Timeline Weather API JSON

The Visual Crossing Timeline Weather API JSON output is similar.

 {
     "latitude" : 38.9697,
     "longitude" : -77.385,
     "resolvedAddress" : "Reston, VA, United States",
     "address" : " Reston,VA",
     "timezone" : "America/New_York",
     "days" : [{ //array of days of weather data objects
         "datetime" : "15:00:00",
         "temp" : 59.6,
         "feelslike" : 59.6,
         ...
         "stations" : {
         },
         "source" : "obs",
         "hours" : [{  //array of hours of weather data objects  
             "datetime" : "01:00:00",
             ...
         },...]
     },...],
     "alerts" : [{
             "event" : "Flash Flood Watch",
             "description" : "...",
             ...
         }
     ],
     "currentConditions" : {
         "datetime" : "2020-11-11T22:48:35-05:00",
         "datetimeEpoch" : 1.605152915E9,
         "temp" : 67.9,
         ...
     }
}

The output consists of a set of summary information about the location requested including the address, latitude and longitude and timezone. There are then up to three weather data sections.

Days and hours

The weather data itself is returned as an array of days weather objects. This summarizes the weather data for each day requested. Historical and forecast day level data will also include an hours property indicating the observed or forecasted weather data for each hour. For more details on the weather data object properties that will be returned, please see the full Timeline Weather API documentation.

Current conditions

If your request includes the current date, the current conditions will be populated. This is a weather data object indicating the latest available observations for the location requested.

Alerts

Finally, the alerts property contains an array of currently active weather alerts for the requested location. This is populated if your request includes the current date. See Weather Alerts for more information.

Date and time formatting

The returned data formats dates and times in a consist way for simplicity. All dates and times include a formatted version such as ‘2020-11-15’ and also a value indicating the seconds since the epoch eg

"datetime":"2020-11-12",
"datetimeEpoch":1605139200

Note that the datetime formatted value is given in the local time zone. The seconds since the epoch value is given in Universal Time Coordinated (UTC), sometimes known as GMT, Z or Zulu time.

Step 4 – Consider optional optimizations

The Visual Crossing Weather API includes a number of features that can make your code simpler.

As we discussed above, we support address lookup (also known as address geocoding) as a part of our weather API. If you have a separate address lookup request step before the Dark Sky API request in your current application, you can remove that step.

If your data consumer is better equipped to handled non-JSON data format, then we also offer the CSV output. This useful for importing weather in to Excel and databases. The API also supports the ODATA format should your client application be equipped to consume that weather data format.

If your application currently uses a proxy to avoid cross domain issues, you can consider removing that proxy as the Visual Crossing API support the CORS cross domain standard.

Additional Visual Crossing Weather APIs

Our Timeline Weather API offers the closest fit to the existing Dark SKy Weather API. Some of our other Weather APIs offer additional functionality that may help you. All the following APIs offer both CSV and JSON output for easy integration into application and data science tools such as Microsoft Excel, Business Intelligence or databases.

/forecast – retrieves the weather forecast and current conditions for one or more locations. The service returns hourly and daily data.

/history – retrieves daily or hourly historical weather observations for one or more locations.

/historysummary – retrieves climate statistics and historical data summaries for one or more locations. For example you can retrieve annual, monthly, weekly or even daily typical weather and climate data all based around previous years actual weather.

Next steps

As we’ve shown, converting your existing Dark Sky API application to the Visual Crossing Weather API is straightforward – and you may even be able to simplify your existing code.

If you are a user of the time machine request type in Dark Sky, most of what we have discussed will apply. If you are looking for historical weather data, check our our historical weather data API endpoint. You can even use the historical weather summaries endpoint to produce long term weather forecasts based off the past weather.

Questions or need help?

If you have a question or need help, please post on our actively monitored forum for the fastest replies. You can also contact us via our support site or drop us an email at support@visualcrossing.com.

If you think you see wrong data, please read through our article on how to tell us so we can investigate and fix problems ASAP!