| Lemonrock Gig Listings XML Feeds | |
A. Selected Gigs
The Lemonrock Gig Listings XML Feed API enables you to provide content on your own web site for gigs in any UK town. The gig information is supplied as an XML file, which contains data about the gigs, but has no formatting/layout information. You can format the gigs in any way you choose.
From your server script, you call the Lemonrock XML Feed API URL (see below).
By specifying dates and the location, you can retrieve gig information about any area for any range of dates, from a single day to several weeks ahead.
Once your server has obtained the XML file, you can use your server software to process the information in the file to create formatted HTML pages on your own site.
You must be a member of Lemonrock to use the Gig Listings XML Feed API. Membership is FREE as a Music Lover. XML Feeds are useful if you run a site with regional content, e.g. an online newspaper, travel guide, UK information guide, etc.
XML Feed API URL
http://www.lemonrock.com/xmlfeed.php
HTTP GET parameters
e-mail address
parameter name: email
inclusion: mandatory
details: Your Lemonrock login e-mail address
password
parameter name: pw
inclusion: mandatory
details: Your Lemonrock login password
key
parameter name: key
inclusion: optional
details: Your Lemonrock key. If you need to make more than 100 calls per day to the XML Feed API, it is recommended that you apply to us for a key. This enables requests to be be processed faster when you submit a batch of requests. You will need a valid Lemonrock login account in order to obtain a key.
town
parameter name: town
inclusion: mandatory (or optional, if postcode is specified - see below)
details: URL encoded town/city name, e.g. Abbots%20Langley or St%20Albans
postcode
parameter name: pc
inclusion: optional (or mandatory, if town is not specified - see above)
details: URL encoded postcode, e.g. WD5%200NF or RG1.
Note: You may specify the postcode only, without a town name or county name. However, the page shown may not match your intended town, as some towns have the same postcode (see note on postcodes below).
county
parameter name: county
inclusion: optional
details: URL encoded county, e.g. Herts or County%20Durham. The county must match the town.
Note: specifying either pc or county in addition to the town makes the town unambiguous, and is the recommended method.
miles
parameter name: miles
inclusion: optional
details: set to a numeric value between 5 and 60. Selects the radius around the specified town.
default: 10
days
parameter name: days
inclusion: optional
details: set to the number of days of listings required (1 = today only, 7 = one week (actually 8 days), 14 = two weeks (actually 15 days)).
default: 7
gig date
parameter name: gigdate
inclusion: optional
details: as an alternative to specifying 'days', which starts at today's date, you can specify a single date that you want gig listings for, by setting gigdate to the yyyy-mm-dd date, e.g. 2008-12-01. For a range of dates, set gigdate to 'between', and specify the following 6 extra parameters:
gigfromdate_day (1 to 31)
gigfromdate_month (1 to 12)
gigfromdate_year (yyyy)
gigtodate_day (1 to 31)
gigtodate_month (1 to 12)
gigtodate_year (yyyy)
e.g.
http://www.lemonrock.com/xmlfeed.php
?email=myname@mydomain.com
&pw=mypassword
&gigdate=between
&gigfromdate_day=31
&gigfromdate_month=08
&gigfromdate_year=2008
&gigtodate_day=04
&gigtodate_month=09
&gigtodate_year=2008
&miles=5
&pc=WD1
(N.B. The above URL has been split onto several lines for display purposes, but the actual URL is all on one line.)
Gig Photos
For gig photos, call the following URL:
http://www.lemonrock.com/gigpic.php
GET parameters:
g = unique gig id as given in the <guid> field
w = width of photo in px (50 - 200, in 10px steps)
e.g. to get a 100px wide thumbnail picture for gig with id 34567, call:
http://www.lemonrock.com/gigpic.php?g=34567&w=100
Code your pages with the URL as the 'src' attribute in an 'img' tag, e.g.:
<img align="left" src="http://www.lemonrock.com/gigpic.php?g=34567&w=100" alt="" />
Only call this URL if the XML 'pic' field indicates that a photo is available. If no photo is available for a gig, a 404 'Not Found' HTTP response is returned.
Notes
Towns such as St Albans, St Andrews, etc, do not have full stops (e.g. St. Albans)
Postcodes: Lemonrock uses only the first part of the postcode, so cannot differentiate between towns using the postcode alone. Postcodes can be complete, or partial; however, Lemonrock uses only the first part, before the space.
Parameters are not case sensitive (st%20albans and St%20Albans are treated as identical).
Cancelled gigs are not included in the feed.
Examples
1. http://www.lemonrock.com/xmlfeed.php?email=myname@mydomain.com &pw=mypassword &town=Exeter &days=14
(note: this works because there is only one Exeter)
2. http://www.lemonrock.com/xmlfeed.php?email=myname@mydomain.com &pw=mypassword &pc=WD2%200NF &town=Abbots%20Langley
(note: days defaults to 1 week, miles defaults to 10)
3. http://www.lemonrock.com/xmlfeed.php?email=myname@mydomain.com &pw=mypassword &town=Watford &county=Herts &miles=8
(N.B. The above URLs have spaces before each & for display purposes, but the actual URLs have no spaces here.)
XML file format
<gigs>
<gig>
<bands></bands> <!-- main band plus support bands, separated by ' + ' -->
<genre></genre> <!-- genre of main band/artist -->
<venue></venue> <!-- venue name -->
<city></city> <!-- city name -->
<county></county> <!-- county name -->
<pc></pc> <!-- venue postcode [**] -->
<lat></lat> <!-- venue latitude [****] -->
<lng></lng> <!-- venue longitude [****] -->
<tel></tel> <!-- venue telephone number [*] -->
<date></date> <!-- gig date yyyy-mm-dd -->
<time></time> <!-- gig time hh:mm NB 00:00 is midnight, 12:00 is noon -->
<fee></fee> <!-- entrance fee (text string). If empty, means FREE entry [*] -->
<soldout></soldout> <!-- 1 = sold out, empty = not sold out [*] -->
<regdesc></regdesc> <!-- if a regular gig, description of frequency, e.g. 'every Tuesday' [*] -->
<miles></miles> <!-- distance in miles of gig from specified location/postcode; empty means 0 miles [*] -->
<guid></guid> <!-- globally unique gig id [*****] -->
<pic></pic> <!-- indicates if a picture is available, 1 = yes, empty = no [*] -->
<url_guid></url_guid> <!-- globally unique path for this gig, to Lemonrock band's page [***] -->
<description></description> <!-- description of gig (max 150 characters) [*] -->
</gig>
<gig>
....
....
</gig>
....
</gigs>
[*] this field may be empty
[**] the postcode may be full or partial, e.g. UB8 or UB8 1LU
[***] the full URL is made by prefixing the path with http://www.lemonrock.com/
[****] latitude and longitude are based on the postcode district (e.g. EX2) and are usually correct to within a mile
[*****] the guid for a repeating gig is in the form guid=<gig id>_date=<gig date yyyy-mm-dd>
XML error file format
If Lemonrock cannot determine the town from your parameters, it will return an error file, as below. The error field is a code as follows:
1 = Unknown town
2 = Unknown postcode
3 = Unknown county
4 = No location data specified
<error>
<code></code> <!-- error code between 1 and 4 -->
<helpurl></helpurl> <!-- URL of Lemonrock help page -->
</error>
See Also
See also the Lemonrock Gig Listings API to link directly to Lemonrock gig listings pages by including HTML links in your own site.
B. All Gigs
Daily XML Gig File
If you want an XML description of all gigs in our database, you can download our daily gig list from:
http://www.lemonrock.com/gigs.xml.gz
The file, a compressed (zipped) XML file, is created each day at 7am and contains all current gigs up to 1 year ahead.
The XML data does not include the <miles> field; otherwise the format is identical to the one produced by the API in the 'XML file format' section above.
|
