How to replace the Dark Sky API with Visual Crossing Weather

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.

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

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.

All results in the Dark SKY API are for a single location and are returned in a JSON format.

Visual Crossing

The Visual Crossing Weather API currently offers three end points:

/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.

Location lookup

The Dark Sky API requires that all requests are submitted using the latitude and longitude of the query location. Both APIs support a single location only.

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. All the API requests support multiple location look ups in same request.

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 trial 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. Note that you can use the Weather Data Services page to construct the desired request, view the results in the browser and construct the API request URL.

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 and CSV output which may be easier to use depending on your use case.

4. Consider optional optimizations such as removing any unnecessary address lookup requests that your application may currently need to make. 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 ‘. If you are a user of the ‘ Time Machine Request ‘, nearly all of what we discuss here is relevant but we will also create a separate, dedicated article in the near future.

Step 1 – Sign up for a free trial account

The Visual Crossing Weather API offers multiple Weather API tiers to fit any requirement. For any user that would like to spread the word about the Visual Crossing Weather API, we also offer upgraded free plans via our Ambassadors Program.

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

For more information on our pricing, visit our pricing and editions page.

Step 2 – Construct the API 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/42.3601,-71.0589

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

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?
contentType=json&locationMode=single&locations=38.96972,-77.38519&aggregateHours=24&key=YOUR_KEY

This will request the 15-day weather forecast and current weather conditions for the supplied location. If you would like hourly resolution, simply switch the aggregateHours to 1.

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?
contentType=json&locationMode=single&locations=38.96972,-77.38519&aggregateHours=1&key=YOUR_KEY

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/weatherdata/forecast?
&contentType=json&locationMode=single&locations=Herndon,VA,USA&aggregateHours=24&key=YOUR_KEY

You can also supply multiple locations in the same request by joining locations in the request using a pipe (|) delimiter.

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?
contentType=json&locationMode=array&locations=Herndon,VA,USA|New York City,NY
&aggregateHours=24&key=YOUR_KEY

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

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?
&contentType=json&locationMode=single&locations=Herndon,VA,USA&aggregateHours=24&unitGroup=metric&key=YOUR_KEY

For more details on the available parameters including requesting weather alerts, please see the full weather API documentation.

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.

The Visual Crossing output is similar but keeps the hourly and daily data results separate. This helps to keep latency low if you only require the hourly or daily data (particularly as hourly level information is available for the full 15-day forecast period).

{
	"location" :  {
			"values" : [{
					"wdir" : 295.0,
					"temp" : 55.6,
					....
				   },
			],
			"id" : "Herndon,VA",
			"address" : "Herndon,VA",
			"name" : "Herndon,VA",
			"index" : 0,
			"latitude" : 38.96972,
			"longitude" : -77.38519,
			"currentConditions" : {
				"wdir" : 319.0,
				"temp" : 64.1,
				...
			},
			"alerts" : []
	},
	"columns" : {
		"wdir" : {
			"id" : "wdir",
			"name" : "Wind Direction",
			...
		},
			...
	}
}

The output consists of a location or locations property that contains a location instances for each of the locations requested in the forecast request.

If the ‘locationMode’ parameter of the query is set to ‘single’ then the result will be a location property that provides a single location weather data. If the locationMode is set to ‘array’ then there will be a locations property with a list of the location data.

Within the location instance, the values property contains an array of weather forecast values for each time period (for example each hour or day of the forecast). The ‘currentConditions’ property contains the latest actual weather observations for the location.

Finally, the alerts property contains an array of currently active weather alerts for the requested location. See Weather Alerts for more information.

The dates and times returned by the Visual Crossing Weather API are all returned in local time of the request location. Two properties are currently returned for each weather period:

"datetimeStr" : "2020-04-23T00:00:00-04:00",
"datetime" : 1587600000000,

The datetime property represents the number of milliseconds since the UNIX epoch (1st January 1970). The datetimeStr is the ISO 8601 format. In general we recommend using the datetimeStr value as this is designed to be unambiguous and easy to parse in languages such as Javascript, Java and Python. See Dates and Times in the Weather API for more information.

For full information on the weather data returned by the weather API, see the Weather Data and JSON format documentation.

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.

In addition, if you are performing requests for multiple locations, you can combine those into a single API call within the Visual Crossing API. using the above techniques.

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.

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.

Do you have questions or comments? We have full support and forums or you can ask a question below.

Leave a Reply

Your email address will not be published. Required fields are marked *