Search Events

http://api.eventfinda.co.nz/v2/events.xml

Searches the database and returns events matching the given criteria.

Example Request

http://api.eventfinda.co.nz/v2/events.xml?row=10&fields=event:(url,name,sessions),session:(timezone,datetime_start)&q=concert&order=popularity

Example Response

<?xml version="1.0"?>
<events count="501">
 <event>
  <url>https://www.eventfinda.co.nz/2018/david-byrne/auckland</url>
  <name>David Byrne - American Utopia NZ Tour</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-11-17 19:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/d ... merican-utopia-nz-tour/christchurch</url>
  <name>David Byrne - American Utopia NZ Tour</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-11-15 19:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/n ... on-winter-recital-series/wellington</url>
  <name>National War Memorial Carillon Winter Recital Series</name>
  <sessions count="18">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-05-30 16:15:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-05-31 12:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-01 12:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-02 16:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-03 16:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-04 16:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-06 12:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-13 12:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-17 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-20 12:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-24 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-27 12:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-01 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-08 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-15 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-22 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-29 14:30:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-08-05 14:30:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/david-byrne/wellington</url>
  <name>David Byrne - American Utopia NZ Tour</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-11-13 19:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/kiwi-legends-in-concert/paraparaumu</url>
  <name>Kiwi Legends In Concert</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-30 19:30:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2019/taupo-summer-concert/taupo</url>
  <name>Taupo Summer Concert</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2019-01-26 10:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/p ... o-jazz-bossa-nova-concert2/auckland</url>
  <name>Pachuco - Jazz Bossa Nova Concert</name>
  <sessions count="35">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-14 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-21 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-28 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-02-04 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-02-11 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-02-18 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-02-25 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-03-04 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-03-11 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-03-18 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-03-25 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-04-01 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-04-08 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-04-15 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-04-22 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-04-29 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-05-06 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-05-13 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-05-20 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-05-27 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-03 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-10 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-17 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-06-24 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-01 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-08 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-15 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-22 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-29 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-08-05 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-08-12 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-08-19 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-08-26 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-09-02 21:40:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-09-09 21:40:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/bob-dylan/auckland</url>
  <name>Bob Dylan</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-08-26 19:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/d ... esi-mela-2018/auckland/manukau-city</url>
  <name>Desi Mela 2018</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-07 18:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/o ... n-te-vaka-songs-of-moana/wellington</url>
  <name><![CDATA[Orchestra Wellington an ...  Vaka – Songs of Moana]]></name>
  <sessions count="2">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-14 14:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-07-14 17:00:00</datetime_start>
   </session>
  </sessions>
 </event>
</events>

To include all available fields in the response remove the fields parameter from the request.

Parameters

The following parameters are available along with the common parameters.

artists

Return events associated with the given artist ids, multiple ids can be separated by commas.

category

Only return events in the category specified by this ID, or its descendant categories.

Specify multiple IDs by separating them with a comma (,).

category_slug

Only return events in the category specified by this URL slug, or its descendant categories.

Specify multiple URL slugs by separating them with a comma (,).

collection

Only return events in the collection specified by this ID.

Specify multiple IDs by separating them with a comma (,).

collection_slug

Only return events in the collection specified by this URL slug.

Specify multiple URL slugs by separating them with a comma (,).

You can find the URL slug for a collection by inspecting its URL on this site, e.g. the Suzanne Vega collection has the URL slug of 2018/suzanne-vega

end_date

Only return events on or before this date (format is ISO 8601, e.g. YYYY-MM-DD HH:mm:ss). The time part is optional. Defaults to 3 years from now if not specified.

featured

If set to 1, only return events marked as featured.

free

If set to 1, only return free events.

location

Only return events in the location/venue specified by this ID, or its descendant locations.

Specify multiple IDs by separating them with a comma (,).

location_slug

Only return locations in the location/venue specified by this URL slug, or its child locations.

Specify multiple URL slugs by separating them with a comma (,).

order

Specify the order the results should be in. Possible values are

  • date (default)
  • popularity
  • distance (only available with the point parameter)
  • distance_date (only available with the point parameter)

point

In the format latitude,longitude

/events.xml?point=-36.84846,174.763332&order=distance
This parameter only makes sense if you also specify the order and/or radius parameters.

presented_by

Return events with a matching presented_by (case insensitive).

/events.xml?presented_by=presented%20by%20acme%20inc.

price_max

Return events who have a ticket type price less than this value

price_min

Return events who have a ticket type price greater or equal to this value

radius

Only include events within the given kilometers of the given point

/events.xml?point=-36.84846,174.763332&radius=5
Would only return events within 5 kilometers of the point. Fractions of a kilometer can also be specified.

start_date

Only return events on or after this date (format is ISO 8601, e.g. YYYY-MM-DD HH:mm:ss). The time part is optional. Defaults to current time if not specified.

Note that because the start_date defaults to now if you are requesting a past event by id, url_slugs, etc. you'll need to specify a start_date prior to the events start date.

ticketed

If true only return events which are ticketed by Eventfinda.

username

Return events listed by the given username.

Formatting datetime_summary Field

The following parameters allow you to format the datetime_summary field on the event result using the standard strftime arguments.

Example Request

This request specifies a date_format or %A %e %B and a date_start_end_separator of until

    /events.xml?rows=2&fields=event:(name,datetime_summary)&date_format=%A%20%e%20%B&date_start_end_separator=%20until%20 
  

Example Response

<?xml version="1.0"?>
<events count="6526">
 <event>
  <name>Raw Meat Comedy</name>
  <datetime_summary>Monday 25 June</datetime_summary>
 </event>
 <event>
  <name>The Guernsey Literary and Potato Peel Pie Society</name>
  <datetime_summary>Monday 25 June</datetime_summary>
 </event>
</events>
date_format

The format of the date part. Default '%a %e %b %Y'

time_format

The format of the time part. Default is no time part, ''.

date_time_separator

Character or characters to use to separate the date and time. Defaults to nothing, ''.

date_start_end_separator

Character or characters to use to separate the start and end. Defaults to ' - '.