End Points

Listed below are the API end points.

    http://api.eventfinda.co.nz/v2/artists.xml
http://api.eventfinda.co.nz/v2/categories.xml
http://api.eventfinda.co.nz/v2/events.xml
http://api.eventfinda.co.nz/v2/locations.xml

  

Response Formats

The response format is based on the dot extension format. There are three possible response formats.

  • JSON
  • JSONP
  • XML

The examples in this documentation use the XML format. You can use the other formats by simply changing the dot extension.

http://api.eventfinda.co.nz/v2/locations.json
http://api.eventfinda.co.nz/v2/artists.json?callback=someFunction
http://api.eventfinda.co.nz/v2/events.xml

Common Parameters

A large proportion of the possible parameters for each end point are common between all of them.

autocomplete Filters results to those whose name matches an ngram search of the autocomplete.
/events.xml?autocomplete=vect&feilds=location:(id,name)
The above would match results whose name contained similar ngram character sequences to vect such as vector.
created_since Only return results created after this UTC date and time (format is ISO 8601, e.g. YYYY-MM-DD HH:mm:ss). Also see modified_since
fields Which fields to return for partial results. For example you can choice to only return the url and name field on an event result by using
/events.xml?fields=event:(url,name)
You can also specify how much of a text field to return by using a ~ character followed by the number of characters.
/events.xml?fields=location:(id,description~140)
You can specify fields for dependent results by separating them with commas.
/events.xml?fields=event:(url,name,sessions,location),location:(url,name),session:(datetime_summary)
This would include only the datetime_summary of the sessions associated with events.
id Only return results whose id is specified. Seperate ids by a comma.
-id Exclude results whose id is specified. Seperate ids by a comma.
levels The number of levels to show of heirarchical results such as locations and categories.
/locations.xml?levels=3
This means that for any matched result if will also include 3 levels of children and parents. So the results children will also include their children, and the results parents will also include their parents. But the parents will not include any children and the children will not include any parents.
modified_since Only return results modified after this UTC date and time (format is ISO 8601, e.g. YYYY-MM-DD HH:mm:ss). Also see created_since
offset Specifies an offset into the search results. Combined with the rows parameter, this will let you return any subset of the full results. This will allow you to page through results.
/events.xml?rows=10&offset=0
/events.xml?rows=10&offset=10
/events.xml?rows=10&offset=20
order The order to return the results. The options for this depend on the end point and will be explained later for each end point. Leaving it out will default the order to something sensible.

If the q parameter is used the default order will normally be by relevance to the terms.
q A free text query.
/events.xml?q=(cycling+AND+running+AND+swimming)+OR+triathlon
You can use boolean logic using AND, OR and NOT and logical groupings using brackets ( ).
rows Specifies how many results to return. If this parameter is not specified, 10 results will be returned. The total number of results that match is given as the 'count' attribute of the events element. The maximum is 20, anything over that is set to the default.
suppress_response_code If this parameter is true then the HTTP response code will always be 200 which can be helpful for some versions of Adobe Flash which would otherwise intercept non 200 responses.
url_slugs Only return results whose url_slug is included in the list. Seperate url_slugs by a comma.

Parameter Values

Boolean parameters such as suppress_response_code are parsed for a true or false value with on, true, yes and + all considered true while off, false, no and - are all considered false.

All values should be URL encoded.

Date and time values should be in ISO 8601 format and the UTC time zone, e.g. 2018-11-19 05:12:55 . The time part is often optional.