Objectif Lune joins Upland Software.Learn more >

Back to all How-tos

Using the OpenWeatherMap API

While there are many different APIs available to provide weather information on the Internet, OpenWeatherMap appears to offer the simplest, most extensive features available. It is easy to use and free for up to 50,000 requests per day. In this How-To we will explore obtaining weather information in HTML form (the easiest to include in your page) and in JSON format which is better if you wish to customize the weather display in your template.

This trick should work with any sort of output: HTML, Web and Email.

Obtaining your API Key

As with almost any online service, using OWM requires an API key. This key comes when you signup for free on the website and must be used for any request made to the OWM service.

To obtain your API key, simply sign up to openweathermap.org and then locate the key in your profile page once logged in.

Preformatted HTML Weather widget

The easiest way to include the weather information in your template is to request the data in HTML format. Here is an example of what this looks like: http://api.openweathermap.org/data/2.5/weather?q=Montreal&mode=html&appid=your-api-key

Creating the containing <div>

In order to insert the weather widget, a space for it must be prepared. The simplest way is through the use of a <div> element, with the appropriate size and location. For example, to insert the widget on the right of your contents with text wrapping around it, you can insert a right-aligned box:

  • Click on the Insert Inline Box button in the toolbar.
  • Change the Width parameter in the Attributes Pane to 130px and the Height to 150px.
  • Click on the Float Right button in the toolbar to push the box to the right.
  • Change the ID of the box to weather_widget.
  • If desired, change the spacing and margins of the box, or add a border, using its formatting dialog: Right-click on the box and select Box… to access this dialog.

Obtaining the HTML weather contents

Once the container is ready, we need to use a small script to retrieve the HTML contents on the OpenWeatherMap server and insert it into the container.

  • Create a new Script in the Scripts pane.
  • Set the Selector to #weather_widget.
  • Insert the contents of the script below into the script box.
    // Change this to your API key between the single quotes ('):
    var api_key = 'enter_api_key_here';
    results.loadhtml('http://api.openweathermap.org/data/2.5/weather?q=Montreal&mode=html&appid=' + api_key);

You can now preview the results by going to the Preview pane.

Of course you can use data from your own record. For example with fields called address_city and address_country (assuming the country is a 2-letter ISO-3166 code), the following URL would work great and change for each record: 'http://api.openweathermap.org/data/2.5/weather?q=' + record.fields.address_city + ',' + record.fields.address_country + '&mode=html&appid=' + api_key

Personalizing the data using JSON

This second section is addressed to those who at least have a basic grasp of JavaScript, as the example script is limited and would require modification to be personalized for your own template.

Obtaining the JSON Data

While the above example retrieves an HTML page that is already formatted through the loadhtml() function, here we need to rather use loadjson() which retrieves, you guessed it, JSON data. Let’s assume for a moment you have the same <div> as above, and a script with the same selector (#weather_widget). Take a look at this script:

// Change this to your API key between the single quotes ('):
var api_key = 'enter_api_key_here';
var weather_data = loadjson('http://api.openweathermap.org/data/2.5/weather?q=Montreal,ca&units=imperial&appid=' + api_key);

results.append("Weather For: " + weather_data.name + '<br/>');
results.append("Current: " + weather_data.main.temp + '&deg;F<br/>');

Note the added &units=imperial parameter in the URL. Otherwise, unlike the HTML version, the default measurement would be in ° Kelvin. Probably not useful unless you’re a scientist. To get the temperature in ° Celcius, you can use &units=metric.

For the full list of possible data points available through the weather_data JSON structure, please see the current weather API reference.

But wait, there’s more! OpenWeatherMap also offers other data such as 5-day and 16-day forecast as well as, *gasp*, historical data. Hours of fun to have… on your lunch break! Now get back to work!


Leave a Reply

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