Tags

The Wellynews API


Word cloud by Wordle

A number of large news organisations have begun providing APIs to their content. These APIs allow content to be queried programmatically for use in mash ups and the like.

The Wellynews API lets you do something simular with local newsitems.

For example the API can provide a feed of local newsitems related to consultation; or maybe zebras.

It can also handle potentially interesting combinations, such as what Wellington City Council has said about the Central Library closure or sculpture on the waterfront.

Getting started

Supported Formats

The API allows newsitems to be extracted in RSS or JSON format. RSS is widely supported by feed readers, web browsers and server side libraries. JSON is typically used for passing data into browser based JavaScript applications and mashups.

The desired format is specified by appending either rss or json to the end of the query url.

ie. Transport newsitems in RSS format:

or the same newsitems in JSON format:

Newsitem queries

The following types of newsitem query are supported.

Tag newitems

Returns newsitems tagged with a given tag.

ie. All newsitems tagged with soccer, in RSS format.

Publisher newsitems

Returns newsitems published by a specific publisher.

ie. newsitems published by the Wellington City Council, in JSON format.

Combinations

List newsitems tagged with a combination of two tags or a publisher and a tag.

The tags are separated with a plus character. For publisher and tag combinations the publisher must always appear on the left hand side of the plus.

ie. newsitems tagged with transport and consultation and Wellington City Council media releases tagged with runway extension:.

Credit: This url scheme was inspired by the Guardian newspapers' tag combiners.

Geotagged newsitems

Some newsitems contain location information. This makes the following possible:

Geotagged newsitems in RSS format.

-Searching for newitems based on location.
ie. Newsitems near Island Bay:

RSS feeds of newsitems near a location.
ie. An RSS feed of newsitems near Wellington railway station:

Newsitems near your current position (HTML5 browsers such as Firefox 4 and Safari 5 only).
Click the near me link on the geotagged newsitems page to experiment with this feature

Geotags are embedded in our RSS feeds using the GeoRSS standard. A GeoRSS tagged feed item has this format:

<item>
<title>Can you replace the Hilton?</title>
<geo:lat>-41.284896</geo:lat>
<geo:long>174.778531</geo:long>
</item>
Pagination

Each RSS or JSON call returns a maximum of 30 results. For JSON calls, additional results can be obtained from using the page parameter to paginate through the results.

ie. page 6 of the Victoria University newsitems:

You can see the total number of available results in the totalItems field of the JSON results. The showingFrom and showingTo fields tell you which results you are currently viewing:


{
  "totalItems": 377,
  "showingFrom": 151,
  "showingTo": 180,
  "newsitems": [ ... ]
}

RSS to JSON feed mirroring

Provides JSON copies of local RSS feeds. This makes it easier to integrate feeds into sites using JavaScript.

ie. Wellington City Councils' latest news feed as a JSON list:

Example

Using JSON and JavaScript to show the latest transport newsitems on a page.

Transport

These newsitems have been loaded using a JSON API call.

Source code

Source code.

This example was implemented using the jQuery JavaScript library.

Lines 1-2: HTML for the Transport heading and an empty div tag which jQuery will write the newsitems into.

Line 4: Sourcing in the jQuery library file; you would normally do the in the head tag.

Lines 6-8: jQuery. Once the page has finished loading and is ready, fetch JSON data from the API and pass it to the function renderNewsitems.

Lines 10-16: jQuery. The renderNewsitems function is using jQuery to write out the first 4 items from the JSON data as HTML into the empty newsitems div.

Contact

Doing something interesting with this?

Contact enquires (at) wellington.gen.nz and let us know.