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="466">
 <event>
  <url>https://www.eventfinda.co.nz/2018/gardens-magic-2018/wellington</url>
  <name>Gardens Magic 2018</name>
  <sessions count="18">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-09 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-10 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-11 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-12 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-13 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-14 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-16 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-17 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-18 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-19 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-20 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-21 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-23 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-24 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-25 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-26 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-27 20:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-28 20:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/summer-concert-series/porirua-mana</url>
  <name>Summer Concert Series</name>
  <sessions count="4">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-19 18:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-20 18:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-21 18:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-22 13:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/a ... d-folk-festival-2018/auckland/kumeu</url>
  <name>Auckland Folk Festival 2018</name>
  <sessions count="4">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-26 19:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-26 19:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-27 08:00:00</datetime_start>
   </session>
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-28 08:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/k ... -magic-dance-dance-dance/wellington</url>
  <name><![CDATA[Kids Magic Dance, Dance, Dance!]]></name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-27 11:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/t ... ast-pointers-can-mel-parsons/nelson</url>
  <name><![CDATA[The East Pointers (CAN) & Mel Parsons]]></name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-22 20:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/p ... -sunset-symphony-fireworks/auckland</url>
  <name><![CDATA[Ports of Auckland SeePo ... nset Symphony & Fireworks]]></name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-28 18:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/a ... chest-neil-macleod-ludus/wellington</url>
  <name>Aro Creative with Sky Canvas, Heavy Chest, Neil Macleod, Lud</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-22 11:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/symphony-in-the-park/porirua-mana</url>
  <name>Symphony In the Park</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-03-03 18:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/b ... ner-rock-steady-supergroup/feilding</url>
  <name>Bad Company, Foreigner: Rock Steady Supergroup </name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-26 20:00:00</datetime_start>
   </session>
  </sessions>
 </event>
 <event>
  <url>https://www.eventfinda.co.nz/2018/r ... collective-gardens-magic/wellington</url>
  <name>Raw Collective - Gardens Magic</name>
  <sessions count="1">
   <session>
    <timezone>Pacific/Auckland</timezone>
    <datetime_start>2018-01-23 20: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 Dub FX North Island Tour collection has the URL slug of 2018/dub-fx-north-island-tour

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="6108">
 <event>
  <name>Soundsplash Festival 2018</name>
  <datetime_summary>Sunday 21 January until Monday 22 January</datetime_summary>
 </event>
 <event>
  <name><![CDATA[The East Pointers (CAN) & Mel Parsons]]></name>
  <datetime_summary>Monday 22 January</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 ' - '.