Plings Output API

From Plings Info

The feeds.plings.net domain offers several API's for extracting data from the Plings system: They are:

• Activity feed - what's on, when, where, details of activity provider, etc
• Venue data - more detailed information about a venue, e.g. disability access data

About the Data

Please see this page About the data for details about how much data we have, where it is, and what you can expect to see returned

API Keys

API Keys were implemented on 28th May 2009 on the following feeds.

• all XML feeds
• CSV feeds

If you would like to us the data in these formats you will need to apply for an API key. Please email api@plings.net. Tell us a little about yourself and what you plan to do and we'll sort it out.

Please Note You can access all other data formats (ical, kml, rss) without the need for a key.

Development API Key

To see any data that you may have sent to the development server (as opposed to the live server), append the following to the feed URL

?APIKey=insert development API key here
  e.g. http://feeds.plings.net/kml.activity.php/1/town/manchester?APIKey=5A605302-FC5BC526-4473C6AB-B4D9009B-RQMKMLDM

Activity Feed

The API accepts requests via a URL with appropriate parameters appended. e.g.

 http://feeds.plings.net/kml.activity.php/1/town/manchester

[This returns data in KML (Google Earth) format, for activities happening today and tomorrow (1), near the town (town) of Manchester – Ok so Manchester is a city, but it works!]

The data we hold on activities can be interrogated in various ways and the output can gathered in popular formats.

Parameters

All parameters for all activity API's are passed in the same format:

 /<fomatScript>[/<noOfDays>[/<filterName>/<filterValue>]]?<OptionalParameter>

formatScript

This determines the format in which you would like the data to be returned.

Valid values are:

• rss.activity.php – RSS 2.0 (http://cyber.law.harvard.edu/rss/rss.html)
• kml.activity.php - Google Earth file format
• csv.activity.php – Full details of activities in CSV formay
• xml.activity.php – Full details of activities in XML format
• json.activity.php – Full details of activities in JSON format
• ical.activity.php - Full details in iCal format

For further details please refer to the Returned Data Formats section below.

noOfDays

The specifies the number of days in the future that should be searched, default is 0.
Please note:

• The noOfDays parameter must be set, even if it is just set to 0.
• Updated 23/6/10 The returned results will give you 'activities that are taking place during that time period' (They may have started before, or be ending after the specified period)

Examples:

• 0 = Today
• 1 = Today and tomorrow
• 2 = Today, tomorrow and day after
• 7 = The coming week

Note: For filters to be applied, noOfDays must be set, even if it is just set to 0.

Note: Any value for number of days can be added - but please bear in mind that this will have an implication for the amount of data returned

filterName/filterValue

Applies various filters to the restults

Optional Parameters

Additional parameters can be given through the query string, these are:

MaxResults=20&Page=1, Gives the 20 results on page 1, i.e. 1 - 20
MaxResults=20&Page=2, Gives the 20 results on page 2, i.e. 21 - 40 

Examples

updated 31/07/09
1) To get XML data for today in the Post Town known as Stockport:

 http://feeds.plings.net/xml.activity.php/1/town/stockport?APIKey=<API Key Here>

Alternatively you could use the Local Authority Code.

 http://feeds.plings.net/xml.activity.php/1/la/00BS?APIKey=<API Key Here>

2) To get an RSS feed of activities in SK1 1AA 7 days in advance (API Key not required) corrected 31/07/09

 http://feeds.plings.net/rss.activity.php/6/postcode/sk1+1aa

3) To find out what's on at Stockport Art Gallery in October 2008 in csv fomat:

First find the 'place id' by searching at:http://places.plings.net

You should find 'plings:place=41910'

Our query now becomes:

 http://feeds.plings.net/csv.activity.php/30/v/41910?searchDate=2008-10-01&APIKey=<API Key Here>

If we wanted only events that happen after 6pm at night:

 http://feeds.plings.net/csv.activity.php/30/v/41910?searchDate=2008-10-01+18:00&APIKey=<API Key Here>

4) To limit the number of results returned to 10 (in XML format)

http://feeds.plings.net/xml.activity.php/30/v/41910?searchDate=2008-10-01+18:00&MaxResults=10&APIKey=<API Key Here>

New 15/07/09
5) To find all activities on every Monday in the next 30 days in Stockport

http://feeds.plings.net/xml.activity.php/30/town/stockport?onday=Monday&APIKey=<API Key Here>

OR

http://feeds.plings.net/xml.activity.php/30/town/stockport?weekdays=1000000&APIKey=<API Key Here>

6) To find all activities on every Monday, Thursday and Friday in the next 30 days in Stockport

http://feeds.plings.net/xml.activity.php/30/town/stockport?weekdays=1001100&APIKey=<API Key Here>

New 29/04/10
7) Examples of using sortby, sortorder and radius

Postcode search returns activities nearest to the postcode, so below sorts by start time in assending order:

http://feeds.plings.net/xml.activities.php/0/postcode/M1+2EJ?MaxResults=10&sortby=starts&APIKey=<API Key Here>
Sorts by start time in assending order

As above, but within a 10km radius
http://feeds.plings.net/xml.activities.php/0/postcode/M1+2EJ?MaxResults=10&sortby=starts&radius=10&APIKey=<API Key Here>

Closest 10 activities happening today within a 20km radius ordered by end time latest first
http://feeds.plings.net/xml.activities.php/0/postcode/M1+2EJ?MaxResults=10&sortby=ends&sortorder=desc&APIKey=<API Key Here>

Returned Data Formats

RSS – rss.activity.php

Data is returned in RSS format compliant with the RSS 2.0 specification (http://cyber.law.harvard.edu/rss/rss.html). The following mapping is carried out for the RSS items:

<title> - Activity Name

<link> - Link to the plings address

<description> - Activity description, plus other fields.

<category> - The activity category or categories

<pubDate> - The date and time that the activity will happen

KML – kml.activity.php

Data is return in a format that can be opened and processed by Google Earth. Times and Dates are embedded in the date allowing Google Earth to display a time line of activities. The coordinates are gotten from the venue and the description is the same format as that of the RSS format.

CSV – csv.activity.php

Data is returned in CSV format. This a more detailed export of the activities.

XML – xml.activity.php

Data is returned in XML format. The DTD for this feed can be found at: http://feeds.plings.net/xml.activity.dtd

New 13/05/09 Number of Results is now returned in the 'queryDetails' element. This can be used along with the MaxResults and Page functions to return small data sets. Note:- the URLs used are to illustrated the point and not 100% accurate:

1) http://feeds.plings.net/xml.activity.php/0/la/00BN
 
<queryDetails>
    <Results>71</Results>
    <latitude/>
    <longitude/>
</queryDetails>
 
This shows that there are 71 records in the XML feed
 
 
2) http://feeds.plings.net/xml.activity.php/0/la/00BN?MaxResults=10
<queryDetails>
    <Results>10</Results>
    <TotalResults>71</TotalResults>
    <latitude/>
    <longitude/>
</queryDetails>
 
This shows that 10 results are included in the XML feed, but there is a total of 71 results matched
 
 
3) http://feeds.plings.net/xml.activity.php/0/la/00BN?MaxResults=10&amp;Page=1
 
<queryDetails>
    <Results>10</Results>
    <TotalResults>71</TotalResults>
    <Page>1</Page>
    <TotalPages>8</TotalPages>
    <latitude/>
    <longitude/>
</queryDetails>

New 18/6/09 'Ward' information now included in the Activity XML e.g.

<LA>00EY</LA>
<LAName>Blackpool</LAName>
<Ward>00EYNE</Ward>
<WardName>Clifton</WardName>

New 6/7/09 When using a postcode search on the data, the distance from that postcode of the venue is also returned (in both kilometres and miles). e.g:

<DistanceKm>0.316097850671251</DistanceKm>
<DistanceMiles>0.196414098335</DistanceMiles>

New 15/7/09 The network under which an activity provider supplies data to plings is now sent in the Activity XML.

<provider id="xxx">
....
−<network>
  <name>Network Name</name>
  <website>http://www.example.com</website>
 </network>
</provider>

New 17/11/09 The number of Linked Activities is now returned in the Activity XML. By default this is the number of Linked Activities in the future. You can use the optional parameter allLinkedActivities=1 to get a count of all linked activities, future and past.

<linkedActivities>13</linkedActivities>

JSON – json.activity.php

new 30/09/09
You can access data in this format without the need for an API key for client side applications. By default 20 results are returned in response to your API call. You can override this default to between 0 and 200 results using the 'MaxResults' parameter. By using the 'Page' parameter you can get data beyond that.

If you are building a server-side application we anticipate that many people will prefer the XML output for which an API key is required. If your server-side application would prefer JSON you will be able, in time, to get large amounts of JSON data by POSTing your API key along with your request.

The returned data fields are consistent with the XML fields.

JSON Sample requests:

http://feeds.plings.net/json.activity.php/1/la/00BS
will return the first 20 results for activities taking place today and tomorrow in Stockport (00BS)

http://feeds.plings.net/json.activity.php/1/la/00BS?MaxResults=50
will return the first 50 results for activities taking place today and tomorrow in Stockport (00BS)

http://feeds.plings.net/json.activity.php/1/la/00BS?MaxResults=200&Page=2
will return 200 results (201 - 400) for activities taking place today and tomorrow in Stockport (00BS) if there are that many!

JSONP

You can request jsonp (json with a callback) by using the json parameter:

http://feeds.plings.net/json.activity.php/1/la/00BS?callback=sampleCallback

iCAL - ical.activity.php

Data is returned in iCALENDAR format.

Please Note: - All Day Events: An 'All Day' event is recorded with a start and end time of midnight on the same day in the data. e.g. in the XML output:

<Starts>2008-11-25 00:00:00</Starts>
<Ends>2008-11-25 00:00:00</Ends>

You will need to take account of this in any data you display.

Single Activity

Data for a single activity can now be accessed in XML

Format: http://feeds.plings.net/activity.php/<ActivityID>.xml

Example: Activity 73009 from the Development Server (i.e. make the call and include the development API key)

http://feeds.plings.net/activity.php/73009.xml?APIKey=5A605302-FC5BC526-4473C6AB-B4D9009B-RQMKMLDM

By default, when calling a single activity by XML we return all future linked activities, with some detailed data about each one. See Linked Activities below.

Linked Activities

new 17/11/09

Activities can be linked in the Input API, so that similar activities can be grouped together (e.g. a set of 6 weekly sessions of Painting could be linked). Until now this data has not been published in the Output API.

When calling a single activity by XML we return all future linked activities, with some detailed data about each one. If you don't want to see any of these linked activities pass the parameter suppressLinkedActivities.

By using the optional parameter allLinkedActivities=1 you will also get the past linked activities.

<linkedActivities count="97">
 
 <activity id="1117810">
  <Name>Example</Name>
  <Starts>2009-11-17 18:45:00</Starts>
  <Ends>2009-11-17 21:15:00</Ends>
  <Details>Music Sessions</Details>
  <MinAge>13</MinAge>
  <MaxAge>19</MaxAge>
  <Cost>0.00</Cost>
  <ProviderProjectDept>Example</ProviderProjectDept>
  <ContactName>Example</ContactName>
  <ContactNumber>000000000</ContactNumber>
  <ContactEmail>example</ContactEmail>
  <ContactAddress/>
 
  <venue id="324467478">
   <Name>Example</Name>
   <BuildingNameNo>140</BuildingNameNo>
   <Street>Example</Street>
   <Town/>
   <PostTown>Manchester</PostTown>
   <County>Lancashire</County>
   <Postcode>M20 456</Postcode>
   <Telephone>0161000000</Telephone>
   <PlingsPlacesLink>http://places.plings.net/index.php/v/324467478</PlingsPlacesLink>
 
   <LA>
    <LACode>00BN</LACode>
    <LAName>Manchester</LAName>
   </LA>
 
   <Ward>
    <WardCode>Example</WardCode>
    <WardName/>
   </Ward>
   <Latitude/>
   <Longitude/>
  </venue>
 </activity>
 
 <activity>
  .....more activities here .....
 </activity>
 
</linkedActivities>

JSON

There is also a single activity json:

Format: http://feeds.plings.net/activity.php/<ActivityID>.json

This accepts the same parameters as the single activity XML, and also a callback parameter for JSONP.

Single Venue XML

updated 30/09/09
Data for a single venue can also now be accessed in XML

Format: http://feeds.plings.net/xml.venue.php?v=<plingsplace id>

Example: Roe Hill, Hatfield (plings:place=42025) (from our listing: http://places.plings.net/index.php/v/42025) as XML

 http://feeds.plings.net/xml.venue.php?v=42025&APIKey=<API Key Here>

Variation

The API will also accept a request in the following format:

 http://feeds.plings.net/xml.venue.php/42025?APIKey=<API Key Here>

See it in action

We have a Google Map interface that takes many of the parameters at:

• http://maps.plings.net/activities.php/0/la/00BS

We have custom displays of Plings and associated data at:

• http://plings.info/demo/webplings/
• http://manchester.plings.net

The source code for these 2 visualisations is available at:

• https://launchpad.net/webplings

Changelog RSS

new 09/03/11

http://feeds.plings.net/rss.changelog.php?objects=activities,venues

The above provides an RSS feed of activities and venues that have been created, updated or deleted in the past 3hours over the entire Plings dataset. Currently, there are no other parameters available to limit the results returned (e.g. by postcode or local authority).

If you plan to poll this feed regularly then you might want to consider doing so every 2 hours as this will eliminate any risk of missing a change due to network lag.

<item>
 <title>1181883</title>
 <description></description>
 <link>http://plings.net/a/1181883</link>
 <pubDate>Mon, 07 Mar 2011 09:30:51 +0000</pubDate>
 <category>C</category>
 <guid>plings:activities=1181883</guid>
</item>

Fields

title

This contains the plings id of the activity or venue that has been either created, updated or deleted.

category

This will contain one of the following values

• C
• U
• D

(i.e CUD - Create, Update, Delete) and indicates what change has occured.

guid

You can parse this to find out if this change is related to an activity or a venue, and it's associated Plings unique identifier.

• If activities then use http://feeds.plings.net/activity.php/{id}.xml?APIKey=
• If venues then use http://feeds.plings.net/xml.venue.php/{id}?APIKey=

What's New

09/03/10 Changelog RSS Adds a new feed/service of an RSS feed of all updates, deletes, and creations in the dataset.

01/10/10 Single activity JSON api, and document callbacks for JSONP.

29/04/10 New filter results by latitude and longitude co-ordinates added. See filterName/filterValue

28/04/10 New parameters for sorting results added See Optional Parameters

17/11/09 Linked Activities in the XML outputs. See Optional Parameters, XML – xml.activity.php, and Single Activity XML

30/09/09: JSON output now available on activity calls.

06/07/09: When doing a postcode search and requesting an XML output, the distance of the venue from that postcode is also returned. This has long been the case, but only now documented.

18/06/09: LA (Local Authority Code), LAName (Local Authority Name), Ward (Ward code) and WardName, added as additional data fields to Activity XML output. They can be found as part of Venue data.

02/06/09: HTTPS - secure data transfer added as an option to data transfer calls

13/05/09: Number of results now returned in XML requests. see Plings Output API#XML - xml.activity.php

16/04/09: Our XML DTD was out of date, although, there have been no changes to the Output fields, the document has been updated to make sure everything in the XML data feed is reflected in the DTD.

06/04/09: Plings_Output_API#Optional_Parameters - added the MaxResults and Page parameters to the documentation.

24/03/09: Single Activity XML added to the documentation. The method has been available for a while, but only just documented.

17/12/08: Time parameters added.
You can now request all plings starting after a certain time on a certain date. Use:

 ?searchDate=yyyy-mm-dd+hh:mm

More Links

You might also like...

• Plings Input API
  • Example Code SOAP
  • Example Code HTTP POST
• Plings Output API