Plings Output API

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>

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!

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 XML

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

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.

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>

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

What's New

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