This article will walk you through a simple example of using a REST API. Go ahead and follow along in your own Grow account. This will help you become more familiar with the steps, things to look for, and what to do if you run into errors.

We are going create a metric for your dashboard, using a weather API that anyone can access to pull in weather for your city. The API we are going to use is http://openweathermap.org/current.

You can ask the API to give you the weather info in a variety of different ways. Let's use the weather by zip code. You can either click on this option on the side, or scroll down to "By ZIP Code."

If we want to make an API call for the weather by zip code, we would use the following call: api.openweathermap.org/data/2.5/weather?zip={zip code},{country code} but replacing the { }  with the actual info (zip and country codes).

Using the zip code for Grow's location (Orem, Utah), I would form the URL like this: api.openweathermap.org/data/2.5/weather?zip=84097,us 

So let's go try that. Log in to your Grow account, click Add Metric, then select Custom REST API from the list of data sources. Enter the URL and press the blue Connect button.

But we get an error. The error says Error Invalid URI "api.openweathermap.org/data/2.5/weather?zip=84097,us" 

So our URL is invalid. We have to add the http:// in front. So our new URL is: http://api.openweathermap.org/data/2.5/weather?zip=84097,us
Go ahead and press the blue Connect button again.

And we hit another error. This time our error message says Unauthorized: {"cod":401, "message": "Invalid API key. Please see http://openweathermap.org/faq#error401 for more info."} 

So let's go to the URL they give and find out how to fix this problem. We find there that we need a valid AppID, which we can register for free.

So let's register and get our AppID. Once you have registered, you can find your API keys under the tab labeled "API keys."

So I have an API key, but I still don't know how to use it. A little searching on the site and I find these instructions about how to use a key.

Per these instructions, we need to add the key to our previous URL. Their example is: http://api.openweathermap.org/data/2.5/forecast/city?id=524901&APPID={APIKEY} 

So our new URL would look like this: http://api.openweathermap.org/data/2.5/weather?zip=84097,us&APPID=02cxxx
(Here, you would insert your own API key.)

When we try this URL, we get data back!

Go ahead and press the blue Continue to make a metric with this data.

However, we hit one more problem. The temperature in the field main.temp comes in as really high. Our example shows that it is currently 300.119 degrees, which is clearly not correct. 

Reading the documentation, we find out that the default units is in Kelvin. They do, however, give us the conversion to specify what format we want the temperature in.

To get imperial units, we need to add units=imperial  to our URL. So our new URl looks like this: http://api.openweathermap.org/data/2.5/weather?zip=84097,us&units=imperial&APPID=02cxxx 

In Grow, go to Data Settings in the left-hand panel and enter that new URL, then press the blue Connect button.

This time, the temperature comes back as 80.67. For mid-June, that's not too bad!

To finish building your metric, go ahead and change the chart type to Single Value. Select that cell as your data value for your metric. You can either leave the value as is, or set the number formatting to round it. Give it a label and a metric title, then click Save.

And that's it!

Sometimes working with APIs can be a game of trial and error. Most services' API documentation can help you out if you run into errors. You are always welcome to chat in to our site and we can also take a look into any issues you have.

Questions? Email us at support@grow.com or chat in on the site.

Did this answer your question?