Eventfinda Developer API: Usage

The Eventfinda Developer API allows third party websites and applications to access the Eventfinda database in order to display event information. The API is implemented using a REST-based interface, with all responses sent back as XML over HTTP. Authentication is performed using HTTP Basic Authentication, and each request must include the HTTP Authentication headers.

An example using curl:

curl -u username:password https://api.eventfinda.co.nz/venues/get/id/904

If the API request is successful, the response will be returned in XML format.

If the request is unsuccessful, the response will have a 404 status code. The example below shows the HTTP response returned if the requested item cannot be found:

HTTP/1.1 404 Not Found
Date: Wed, 26 Sep 2007 12:10:53 GMT
[…]

Any successful API requests will return a 200 status code. API requests which cannot be successfully authenticated will return a 403 status code. Error conditions will return a 500 status code.

In the documentation that follows, the following notation is used:

• {$id}: This identifier should be replaced by the appropriate data (the id variable) for your request.
• […]: Indicates where lines from the response payload have been removed for brevity.

API Request Format

All API URIs can be broken down into three main components:

https://api.eventfinda.co.nz/{module}/{action}/{arg1}/{value1}/{arg2}/{value2}/...

• Module: The type of content being requested, e.g. event, venue
• Action: The action to be performed, e.g. list, get, search
• Arguments: Arbitrary number of optional arguments for the request, in label/value pairs. Unless otherwise stated, the order of arguments sent with API requests is unimportant.

API Versions

Method calls to versions of the API past 1.0 must be prefixed with the API version number, e.g.:

/2.0/events/get/id/5528

Method calls not preceded with an API version number will be assumed to be requesting version 1.0 of the API.

CDATA Sections

Text elements which might contain characters that have special meaning in XML will be enclosed in a CDATA wrapper to avoid unintended consequences (such as an invalid XML response). For example:

<description>
  <![CDATA[
    We Will Rock You, the musical by Queen and Ben Elton is an electrifying show 
    that's guaranteed to blow your mind.
  ]]>
</description>

Character Encoding

The Eventfinda API will respond with UTF-8 encoded XML. If you're using a different character encoding, you should convert the responses returned from the API to your target encoding.