Guardian Open API CFC Wrapper

Sadly, I negated to follow up the initial release of the code and to update the wrapper once the API had been pushed into a formed release. I have punished myself with wooden spoons and bamboo sticks as penance.

I am pleased to say that I have now (finally) updated the CFC wrapper to include the current up-to-date implementation of the API and available methods for use within your ColdFusion applications.

What Does It Do?

There is a lot of information available to read on the official Guardian site for the open platform. The underlying use of the API is to access over 1 Million articles across the last 10 years, including current content. Essentially, the Guardian are opening up a shed load (yep, it's an official form of measurement) of their content for free.

There are tiered access levels (three, I believe) from which you can obtain more information and resources from the API requests, but the free version is incredibly detailed from what I've seen so far.

What's In It?

There are four main methods within the API, which are:

Content Search

Item Search

Tag Search

Section Search

What has changed in the update?

The methods available for use have been amended. The parameters for each method have completely changed from the initial release I made in march last year. The API developers revised most of the arguments for each method, and more or less started again from scratch.

I have also revised the folder structure for the wrapper, which now sits happily in a separate package structure as you would expect.

In addition to these changes, the API now officially handles JSON response requests. In the initial release, only XML was allowed as a response format, and I had written in a function to convert the XML to JSON within the wrapper to return JSON if requested by the user. An API isn't truly an API in my opinion if it doesn't offer a choice of response formats though, and I'm certainly glad this was finally amended.

Let's see it in action then

OK

Instantiation

Creating and instantiating the object is incredibly simple, and requires one parameter, the API key. There is an optional second parameter, set to true by default which handles the output of the data. If true, the XML will be parsed or the JSON will be returned in structural format, depending on your chosen return format.

In the above example, we are running a quick tag search on the keyword 'literature', limiting the response to 3 items and requesting the data in JSON format.

The response from the above code call would be similar to below:

Let's take another look at a quick easy example. This time, we'll run a content search for anything containing 'iPhone', and we'll filter the results for content published on or after a particular date: