How to Build a Yahoo! Weather "Hello World" Application in JavaScript

Next in our series of the “Hello World of APIs” we are looking at Yahoo WeatherTrack this API, a very popular API that provides the latest weather information. As with our previous tutorials, we will focus on detailing what a developer needs to know in order to understand the API and build an application that integrates with it.

In this tutorial we’ll be building our application using JavaScript; this is in response to feedback from previous tutorials, which indicated JavaScript was the most important programming language to cover in the next article. This tutorial will follow the same format as the previous tutorial, walking through the steps required to integrate with the Yahoo Weather! API. In the course of the tutorial the following topics will be discussed:

  • Application Infrastructure Choices – Why JavaScript?
  • Understanding the API – API types, security, etc.;
  • Sending the request – Walkthrough of our example application;

Again, in the same vein as previous tutorials the aim is to leave a reader who is familiar with JavaScript with sufficient knowledge to build an application that integrates with the Yahoo Weather API.

Application Infrastructure Choices – Why JavaScript?

In terms of choosing a programming language, using JavaScript to consume APIs is a fairly obvious choice; it is hugely popular, with a runtime environment present in every browser. In the past JavaScript was almost exclusively a client-side language, but over the last few years increasing numbers of server-side runtimes and application frameworks have become available (Node.js being the standout example). Implicit in its popularity is support for making calls to APIs over HTTP. Every JavaScript implementation and framework has the capability to directly call a HTTP endpoint and interpret the response when encoded in formats such as XML and JSON, and there are JavaScript libraries available for the majority of popular APIs.

However, there are some considerations developers should be aware of when using JavaScript to consume APIs in the browser. The most of important of these is Cross-Origin Request Sharing, or CORS for short. CORS is a security mechanism implemented in all browsers that prevents JavaScript code from calling a HTTP endpoint different from the location the page originated from: The idea is to prevent miscreants hijacking or injecting calls to other sites. CORS is implemented using an exchange of HTTP headers, and APIs that are served over HTTP must provide CORS support if they wish to provide support to JavaScript applications. When developing a client-side application that consumes an external API i.e. from a different location to the one the page was served from, developers must ensure that CORS support is available for their application to work. You of course have the option of implementing JSONP, another mechanism for making cross origin requests, but this is generally considered to have security implications and should be avoided unless you are using it with trusted services.

A pure client-side JavaScript application executed in the browser is also, generally, an insecure choice when an API is consumed that implements any sort of credential-based security to authenticate the application, such as an API key and secret. The credentials to access the API are readily available to any user of the application, and as recent coverage of the Verizon Hum website shows, can easily be sniffed.

You should consider these factors before embarking on writing a JavaScript application. You also want to consider the overall architecture such as what functionality makes sense being implemented in the browser, and what may be better implemented server-side. To support this tutorial we have developed an application that is implemented almost entirely on the client, using a number of frameworks to help us. We’ll discuss why we were able to take this approach below.

Understanding the API

Yahoo provides information on the Weather API at the Yahoo Developer Network (YDN) site. The core documentation is freely available to read without a Yahoo account, but a developer must register for a YDN account if they call a Yahoo API that requires the use of a client ID and secret.

Yahoo organizes information on the Weather API into the following sections:

  • Get Started
  • Documentation
  • Create An App

We’ll cover each of these in turn.

Get Started

The Get Started page provides the developer with a simple overview of what they need to the do to start developing against the Weather API. This includes the following:

  • A link to the Create an App page that allows a developer to get the Client ID and Secret required to access the API. Note that in the case of the Weather API this is not required for personal, non-commercial use, but an Application ID is required to access the Yahoo GeoPlanet API, which, in some cases the RSS version of the Weather API relies on (more on this below).
  • Code snippets for different languages, including JavaScript. These code snippets use Yahoo Query Language (YQL) as the basis for the API call, but developers can use HTTP addresses as well (the RSS version of the API), which is described in the documentation section.
  • A link to the YDN forums.
  • Links to important documentation, including Yahoo’s attribution guidelines that detail how a developer should attribute the fact they are using the Weather API in their application (which they must do or risk violating the terms of use for Yahoo APIs).

Documentation

The documentation page covers only the format of the RSS version of the Weather API, including the required query parameters and the response structure. As mentioned above, you’ll also need to read the GeoPlanet API documentation in order to understand how to retrieve a WOEID (Where On Earth ID) that the RSS version relies on for looking up the weather for a given place.

However, developers have the option of using YQL, and given that the code snippets mentioned above were created using YQL this appears to be Yahoo’s preferred version of the API. In order to use the YQL interface developers should refer to the main YQL page instead. You can also use the YQL console to help you create YQL queries that you can use in your Weather API calls, making queries against the weather.forecast table. There is no API description specification so understanding the API relies on using examples in the console to elicit an understanding of the responses.

Create An App

Yahoo requires a developer to create an app for some of their APIs which is essentially a logical entity registered to their Yahoo user account and used as an internal identifier for the application accessing the API. As mentioned above, creating an app is not required to access the RSS version of the Weather API per se, but developers will need to access the GeoPlanet API to look up the WOEID so using this feature is required. Once you’ve created an app you’ll have access to the app overview page that contains the application ID you need to access the GeoPlanet API, as shown below. However, if you use the YQL interface to query the Weather API you do not need to create an app. YQL queries can be performed without an authentication.

Chris Wood Chris is a freelance API specialist. His main interests are API management, Python and doing interesting stuff. Connect with Chris on Twitter

Comments