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.
https://wellington.gen.nz/[tag url snippet]/[rss|json]
ie. All newsitems tagged with soccer, in RSS format.
Publisher newsitems
Returns newsitems published by a specific publisher.
https://wellington.gen.nz/[publisher url snippet]/[rss|json]
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.
https://wellington.gen.nz/[tag|publisher]+[tag]/[rss|json]
ie. newsitems tagged with transport and consultation and Wellington City Council media releases tagged with runway extension:.
https://wellington.gen.nz/transport+consultation/rsshttps://wellington.gen.nz/wellington-city-council+runway-extension/rss
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.
https://wellington.gen.nz/feed/[feed url snippet]/json
Where the feed url snippet matches one of the feeds listed below.
ie. Wellington City Councils' latest news feed as a JSON list: