Dark Sky specializes in weather forecasting and visualization. The coolest aspect of Dark Sky is their weather API that we can use to retrieve the weather data from almost anywhere in the world. It's not just weather is rainy or sunny but temperature, dew point, wind gust, humidity, precipitation, pressure, UV index, and more, all easily available for wherever you want, whenever you want.

Let's learn how to use Dark Sky's super-simple API. If you are new to using API's I promise you this is going to be really easy! And if you've used API's before then I hope we can teach you something new with the code we've used.

What you will need for this project:

Dark Sky API account
Initial State account
Raspberry Pi or Laptop

Step 1: Getting Started

We’ve already put in a lot of the leg work for you putting the code together and organizing the information. We’ll just need you to make a few adjustments along the way. If you want a bit of a challenge make some changes to our code and what weather data is sent, there is limitless possibilities!

To retrieve all of the things we’ve prepared for you, you’ll need to clone the repository from GitHub. GitHub is a service that allows us to store, revise, and manage projects like this. You will want to run this script on a dedicated device. A Raspberry Pi is a perfect option to run applications like this tutorial.

To clone the repository all we need to do is go into our Pi’s terminal, or your computers terminal that is SSH’d into your pi and type this command:

$ git clone https://github.com/InitialState/darksky.git

Hit enter and you’ll see this information:

Cloning into 'darksky'...
remote: Counting objects: 2, done.
remote: Total 2 (delta 0), reused 0 (delta 0), pack-reused 2
Unpacking objects: 100% (2/2), done.
Checking connectivity... done.

Once you see this then congrats, you’ve successfully cloned the GitHub Repo and have all of the necessary files to build this project. Before we move on to the next step, let’s take some time to explore around this directory and learn a few basic command line commands.

Type in the command below into your terminal:

 $ ls

This command lists everything that’s available in the directory that you’re currently in. This list shows that our GitHub Repo has been successfully cloned into our directory under the name “darksky.” Let’s take a look at what’s in that directory. To move to a directory, all you need to do is type “cd” and then type the name of the directory that you wish to go to.

In this case, we’ll type:

 $ cd darksky

Once we hit enter, you’ll see that we’re now in the darksky directory. Let’s type "ls" again to see what files we’ve installed on our pi.

 README.md  darksky.py ...

Here we see the we’ve got our readme document and python files. Let’s take a look at darksky.py using the "nano" command. The nano command allows us to open up the nano text editor where we have all of our python code for each segment of this project. Go ahead and type:

$ nano darksky.py

Here you can see all of the code we’ve prepared for you for this project. We’re not going to make any changes to this document just yet, but feel free to scroll around and see what we’re going to be doing later in this tutorial.

Step 2: Using the Dark Sky API

In order to use the Dark Sky API, you first need your own API key. Don't worry, getting an API key is quick and free. All you need to do is go to the website and click "Try for Free" to create an account.

You get 1,000 API calls for free each day. Every API request over the free daily limit costs $0.0001.
This limit automatically resets each day at midnight UTC.
The Forecast Request returns the current weather forecast for the next week.
The Time Machine Request returns the observed or forecast weather conditions for a date in the past or future.

Your secret Dark Sky API key will look something like this: 0123456789abcdef9876543210fedcba.

You can make an API call to Dark Sky by typing in a URL into your browser in the following format:

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

Replace "key" with your Dark Sky API key and longitude/latitude with whatever you want. You can find your longitude and latitude by going to Google Maps and searching your location. Those values will be in the URL. Copy and paste the above dark sky URL with your access key and values added into an address bar.

Once you do that you will see something like this:

{"latitude":37.8267,"longitude":-122.4233,"timezone":"America/Los_Angeles","currently":{"time":1550615286,"summary":"Clear","icon":"clear-
day","nearestStormDistance":57,"nearestStormBearing":15,"precipIntensity":0,"precipProbability":0,"temperature":53.9,"apparentTemperature":53.9,
"dewPoint":29.59,"humidity":0.39,"pressure":1022.45,"windSpeed":3.87,"windGust":9.25,"windBearing":259,"cloudCover":0.01,"uvIndex":3,
"visibility":7.8,"ozone":309.71},"minutely":{"summary":"Clear for the hour.","icon":"clear-day","data":[
{"time":1550615280,"precipIntensity":0,"precipProbability":0},...

It can be a little overwhelming and hard to read so what I recommend doing is using a JSON Formatter to help make the data more readable. When you do this it will look something like this:

object {9}
	latitude: 37.8267
	longitude: -122.4233
	timezone: America/Los_Angeles
currently {19}
	time: 1550615286
	summary: Clear
	icon: clear-day
	nearestStormDistance: 57
	nearestStormBearing: 15
	precipIntensity: 0
	precipProbability: 0
	temperature: 53.9
	apparentTemperature: 53.9
	dewPoint: 29.59
	humidity: 0.39
	pressure: 1022.45
	windSpeed: 3.87
	windGust: 9.25
	windBearing: 259
	cloudCover: 0.01
	uvIndex: 3
	visibility: 7.8
	ozone: 309.71

You've just made an API call! See how easy that was? You didn't even have to write a single line of code. Now that you've mastered API's we can move on to the data streaming portion.

Step 3: Initial State

We want to stream all of our weather data to a cloud service and have that service turn our data into a nice dashboard that we can access from our laptop or mobile device. Our data needs a destination. We will use Initial State as that destination.

Step 1: Register for Initial State Account

Go to https://iot.app.initialstate.com and create a new account. You get a 14 day free trial and anyone with an edu email address can register for a free student plan.

Step 2: Install the ISStreamer

Install the Initial State Python module onto your Raspberry Pi. In the command prompt, run the following command:

$ cd /home/pi/
$ \curl -sSL https://get.initialstate.com/python -o - | sudo bash

Step 3: Make some Automagic
After Step 2 you will see something similar to the following output to the screen:

pi@raspberrypi ~ $ \curl -sSL https://get.initialstate.com/python -o - | sudo bash
Password:
Beginning ISStreamer Python Easy Installation!
This may take a couple minutes to install, grab some coffee :)
But don't forget to come back, I'll have questions later!

Found easy_install: setuptools 1.1.6
Found pip: pip 1.5.6 from /Library/Python/2.7/site-packages/pip-1.5.6- py2.7.egg (python 2.7)
pip major version: 1
pip minor version: 5
ISStreamer found, updating...
Requirement already up-to-date: ISStreamer in /Library/Python/2.7/site-packages
Cleaning up...

Do you want automagically get an example script? [y/N]
Where do you want to save the example? [default: ./is_example.py]

Please select which Initial State app you're using:
1. app.initialstate.com
2. [NEW!] iot.app.initialstate.com
Enter choice 1 or 2:
Enter iot.app.initialstate.com user name:
Enter iot.app.initialstate.com password:

When asked if you want to automagically get an example script put "y" for yes and press enter to save your script in the default location. For the question about which app you are using, select 2 (unless you signed up before November 2018) and enter your username and password.

Step 4: Run the Example Script

Run the test script to make sure we can create a data stream to your Initial State account. Write the following command:

$ python is_example.py

Step 6: Example Data

Go back to your Initial State account in your web browser. A new data bucket called “Python Stream Example” should have shown up on the left in your log shelf (you may have to refresh the page). Click on this bucket to view your data.

Step 4: Dark Sky Weather Dashboard

Now for the fun part. We are ready to start using the Dark Sky API to create a weather dashboard and capture the weather history for the location we choose. To do this, we are going to use the Python script: https://github.com/initialstate/darksky/blob/master/darksky.py. This script simply calls the Dark Sky API using your API key and retrieves the weather information on a specified time interval. It also streams that data to your Initial State account, which will allow you to create a Dark Sky weather dashboard.

You can either copy this script to your Pi, or access it through the GitHub repository that we cloned earlier. You can do this by changing into your darksky directory by typing:

$ cd darksky

From here, you'll be able to access the python file that we'll run to create our weather dashboard. Before you run it, you need to set your desired parameters and insert your keys. Nano into the darksky.py file by typing:

$ nano darksky.py

Then edit the section near the top of the script:

# --------- User Settings ---------
CITY = "Nashville"
GPS_COORDS = "36.1628414,-86.780199"
DARKSKY_API_KEY = "PLACE YOUR DARK SKY API KEY HERE"
BUCKET_NAME = ":partly_sunny: " + CITY + " Weather"
BUCKET_KEY = "ds1"
ACCESS_KEY = "PLACE YOUR INITIAL STATE ACCESS KEY HERE"
MINUTES_BETWEEN_READS = 15
# ---------------------------------

You need to set the desired GPS coordinates and city name. You also have to insert your Dark Sky API key and your Initial State account access key or your data isn't going to go anywhere. The MINUTES_BETWEEN_READS parameter will set how often your script will poll the Dark Sky API for weather information. 15 minutes provides a nice interval long-term. For the sake of short-term testing, you can set this to 0.5 minutes. Make your changes then enter control+X to exit and save.

Once you have your parameters set, you are ready to run your script:

$ python darksky.py

If you are ssh'ing into your Pi and want to leave this script running uninterrupted for a long time, you can use the nohup command (no hang-up) as follows:

$ nohup python darksky.py &

This script is going to do a bit more than just read the weather data and send it to Initial State. This script is going to take advantage of the emoji support built into Initial State's tools to make the dashboard a bit more cool. You can see the logic used to take the weather status from the currently -> icon and convert it to an emoji token in the weather_icon function. Something similar happens for the moon phase in the moon_icon function and wind direction in the wind_dir_icon function.

Step 5: Conclusion

Go to your Initial State account and look at your data. I changed all my percentage values to arc gauges, the precipitation to a liquid gauge, and the temperature to a temperature gauge. You can change to any kind of Tile types and choose your colors for the gauges & line charts. You can make your dashboard dark or light and embed the final product into a website using an embed iFrame.

If you want to use the dashboard layout from a public share as your dashboard, you can import a layout into your data bucket by following the instructions at here. You can add a background image to your dashboard to give it more context.

The public share URL for our dashboard is https://go.init.st/0hw08py.

Now you've master the Dark Sky API the possibilities are endless! There is an unlimited amount of free API's online to explore so get started.