Scala client for the Guardian's OpenPlatform Content API

Introduction

This library provides a simple client wrapper round the guardian.co.uk Open Platform Content API, for scala 2.8.0, 2.8.1, 2.9.0-1 and 2.9.1.

To use from sbt:

resolvers += "Guardian Github Releases" at "http://guardian.github.com/maven/repo-releases"
libraryDependencies += "com.gu.openplatform" %% "content-api-client" % "1.13"

To use from maven:

<dependency>
    <groupId>com.gu.openplatform</groupId>
    <artifactId>content-api-client_${scala.version}</artifactId>
    <version>1.13</version>
</dependency>

...

<repository>
    <id>com.gu</id>
    <name>Guardian Github Releases</name>
    <url>http://guardian.github.com/maven/repo-releases</url>
</repository>

What calls can I make on the Content API?

There are four different types of request that can be made on the Content API: content search, tag search, section search and single item. The best place to look for documentation on these is to visit the API explorer.

Content Search

The content search, on http://content.guardianapis.com/search, allows searching for content:

// return total number of items of content
Api.search.total

// display the web titles of the 10 most recent items of content
Api.search.foreach(c => println(c.webTitle))

// display the web titles of 11-20th most recent items of content
Api.search.page(2).foreach(c => println(c.webTitle))

// get most recent content matching a search term
Api.search.q("tottenham hotspur").foreach(c => println(c.webTitle))

// get most relevant content matching a search term
Api.search.q("tottenham hotspur white hart lane").orderBy("relevance").foreach(c => println(c.webTitle))

// content matching multiple tags
Api.search.tags("football/tottenham-hotspur,tone/matchreports").foreach(c => println(c.webTitle))

Tag Search

The tag search, on http://content.guardianapis.com/tags, allows searching for tags:

// return the first 10 tags
Api.tags.foreach(tag => println(tag.tagType + ":" + tag.webTitle))

// return the first 10 series tags
Api.tags.tagType("series").foreach(tag => println(tag.tagType + ":" + tag.webTitle))

Section Search

The section search, on http://content.guardianapis.com/sections, allows searching for sections:

// return all sections
Api.sections.foreach(section => println(section.id))

Item

Every content item on http://www.guardian.co.uk should be available on the same url on http://content.guardianapis.com:

// content return
Api.item.itemId("/politics/2010/sep/20/nick-clegg-conference-speech").content.get.webTitle

// tag return
Api.item.itemId("/travel/france").tag.get.webTitle

// latest content for tag
Api.item.itemId("/travel/france").results.foreach(c => println(c.webTitle))

More reading

Further examples can be found in ExampleUsageTest.scala.