Overview & Examples

Welcome to our API documentation. The Eventfinda API is implemented using a REST-based interface, with all responses sent over HTTP. It uses HTTP Basic access authentication which means before you can use it you need to apply for access which is an instant process. By default you will be given standard access, however if you require or would prefer full access please contact us. The Resource documentation describes which fields are only available with full access. The Access column will contain either All or Full. Full means the information is only available with full access and All means the field is available to all API users. Some fields will have an asterisk (*) with more information about the access in the description.

The documentation is broken into two main parts.

Quick Start Examples

Here are some examples of how to use the API in a selection of programming languages.

These are bare bones examples to give you an idea of how it works, without any error handling or use of libraries. It's recommended that you make use of a REST client for your chosen programming language.

Java

      //This code requires Apache HttpComponents (http://hc.apache.org/downloads.cgi) to be working.
  import java.io.BufferedReader;
  import java.io.ByteArrayInputStream;
  import java.io.InputStreamReader;
  import javax.xml.parsers.DocumentBuilder;
  import javax.xml.parsers.DocumentBuilderFactory;
  import org.apache.http.HttpEntity;
  import org.apache.http.HttpHost;
  import org.apache.http.HttpResponse;
  import org.apache.http.auth.AuthScope;
  import org.apache.http.auth.UsernamePasswordCredentials;
  import org.apache.http.client.AuthCache;
  import org.apache.http.client.methods.HttpGet;
  import org.apache.http.client.protocol.ClientContext;
  import org.apache.http.impl.auth.BasicScheme;
  import org.apache.http.impl.client.BasicAuthCache;
  import org.apache.http.impl.client.DefaultHttpClient;
  import org.apache.http.protocol.BasicHttpContext;
  import org.apache.http.util.EntityUtils;
  import org.w3c.dom.Document;
  import org.w3c.dom.Element;
  import org.w3c.dom.Node;
  import org.w3c.dom.NodeList;

  public class Main {
    public static void main(String[] args) throws Exception {

          HttpHost targetHost = new HttpHost("api.eventfinder.co.nz", 80, "http");
          DefaultHttpClient httpclient = new DefaultHttpClient();
        
          try {
            httpclient.getCredentialsProvider().setCredentials(
              new AuthScope(targetHost.getHostName(), targetHost.getPort()),
              new UsernamePasswordCredentials("USERNAME", "PASSWORD")
            );
  
            AuthCache authCache = new BasicAuthCache();
            BasicScheme basicAuth = new BasicScheme();
            authCache.put(targetHost, basicAuth);
  
            BasicHttpContext localcontext = new BasicHttpContext();
            localcontext.setAttribute(ClientContext.AUTH_CACHE, authCache);
          
            HttpGet httpget = new HttpGet("/v2/events.xml?rows=2");
  
            HttpResponse response = httpclient.execute(targetHost, httpget, localcontext);
            HttpEntity entity = response.getEntity();
          
            BufferedReader rd = new BufferedReader(new InputStreamReader(entity.getContent()));
          
            String line = "";
            String xml_string = "";
          
            while ((line = rd.readLine()) != null) {
              xml_string += line;
            } 
      
            DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
            DocumentBuilder b = f.newDocumentBuilder();
            Document doc = b.parse(new ByteArrayInputStream(xml_string.getBytes("UTF-8")));
            NodeList events = doc.getElementsByTagName("event");
            for (int i = 0; i < events.getLength(); i++) {
              Element event = (Element) events.item(i);
              Node title = event.getElementsByTagName("name").item(0);
              System.out.println(title.getTextContent());
              Element all_img = (Element)event.getElementsByTagName("images").item(0);
              NodeList images = all_img.getElementsByTagName("image");
              for (int j = 0; j < images.getLength(); j++) {
                Element img = (Element) images.item(j);
                Node id = img.getElementsByTagName("id").item(0);
                System.out.println(id.getTextContent());
              
                NodeList trans = img.getElementsByTagName("transform");
                for (int k = 0; k < trans.getLength(); k++) {
                  Element tran = (Element) trans.item(k);
                  Node url = tran.getElementsByTagName("url").item(0);
                  System.out.println(url.getTextContent());
                }
              }
            }
    
            EntityUtils.consume(entity);
  
        } finally {
            httpclient.getConnectionManager().shutdown();
        }
      }
    }
    

View Output

Objective-C

      // Property declaration in header
  NSMutableData *apiData;

  // Implementation
  - (void)performAPIRequest
  {
      NSURLRequest *apiRequest    = [NSURLRequest requestWithURL:[NSURL URLWithString:@"http://api.eventfinder.co.nz/v2/events.json?rows=2"]];
      NSURLConnection *connection = [[NSURLConnection alloc] initWithRequest:apiRequest delegate:self];
      [connection start];
  }

  - (void)connection:(NSURLConnection *)connection didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
  {
      NSURLCredential *newCredential = [NSURLCredential credentialWithUser:@"USERNAME"
                                                                  password:@"PASSWORD"
                                                               persistence:NSURLCredentialPersistenceForSession];
      [[challenge sender] useCredential:newCredential forAuthenticationChallenge:challenge];
  }

  - (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response
  {
      apiData = [[NSMutableData alloc] init];
  }

  - (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data
  {
      [apiData appendData:data];
  }

  - (void)connectionDidFinishLoading:(NSURLConnection *)connection
  {
      NSDictionary *apiResponse = [NSJSONSerialization JSONObjectWithData:apiData options:kNilOptions error:nil];
      NSArray *events = [apiResponse objectForKey:@"events"];

      for (NSDictionary *event in events) {
          NSLog(@"%@", [event objectForKey:@"name"]);
          NSDictionary *images      = [event objectForKey:@"images"];
          NSArray *image_collection = [images objectForKey:@"images"];
          for (NSDictionary *image in image_collection) {
              NSLog(@"%@", [image objectForKey:@"id"]);
              NSDictionary *transforms      = [image objectForKey:@"transforms"];
              NSArray *transform_collection = [transforms objectForKey:@"transforms"];
              for (NSDictionary *transform in transform_collection) {
                  NSLog(@"%@", [transform objectForKey:@"url"]);
              }
          }
      }
  }
  
    

View Output

Perl

      #!/bin/perl
      
  use LWP::UserAgent;
  use JSON;
  use strict;

  my $ua = new LWP::UserAgent();

  # Request the response in JSON format using the .json extension
  my $url = 'http://api.eventfinder.co.nz/v2/events.json?rows=2';
  my $username = "...";
  my $password = "***";

  $ua->credentials("api.eventfinder.co.nz:80", "API", $username => $password);

  # Pass request to the user agent and get a response back
  my $res = $ua->get($url);
  my $collection = decode_json $res->content;

  # Iterate over the events and their image transforms echoing out the event
  # name and the image transform URLs
  foreach my $event (@{$collection->{'events'}}) {
    # echo the name field
    print $event->{'name'} . "\n";
    # iterate over the images collection of images
    foreach my $image (@{$event->{'images'}->{'images'}}) {
      print $image->{'id'} . "\n";
      # iterate over the transforms collection of transforms
      foreach my $transform (@{$image->{'transforms'}->{'transforms'}}) {
        print $transform->{'url'} . "\n";
      }
    }      
  }

  
    

View Output

PHP

      <?php

  // Request the response in JSON format using the .json extension
  $url = 'http://api.eventfinder.co.nz/v2/events.json?rows=2';

  $process = curl_init($url);
  curl_setopt($process, CURLOPT_USERPWD, $username . ":" . $password);
  curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
  $return = curl_exec($process);

  $collection = json_decode($return);

  // Iterate over the events and their image transforms echoing out the event
  // name and the image transform URLs
  foreach ($collection->events as $event) {
    // echo the name field
    echo $event->name . "\n";
    // iterate over the images collection of images
    foreach ($event->images->images as $image) {
      echo $image->id . "\n";
      // iterate over the transforms collection of transforms
      foreach ($image->transforms->transforms as $transform) {
        echo $transform->url . "\n";
      }
    }
  }
  
  

View Output

Python

    import json, urllib2, base64

  url = 'http://api.eventfinder.co.nz/v2/events.json?rows=2'
  username = 'username';
  password = 'password';
  request = urllib2.Request(url)
  base64string = base64.encodestring('%s:%s' % (username, password)).replace('\n', '')
  request.add_header("Authorization", "Basic %s" % base64string)  

  result = urllib2.urlopen(request)
  data = json.load(result)

  for event in data["events"]:
       print event["name"]
       for img in event["images"]["images"]:
           print img['id']
           for imgtran in img["transforms"]["transforms"]:
               print imgtran["url"]
    
  

View Output

Ruby

This example requires the httparty library to be installed.

gem install httparty
#!/bin/ruby

  auth     = {:username => "USERNAME", :password => "PASSWORD"}
  response = HTTParty.get('http://api.eventfinder.co.nz/v2/events.json?rows=2', :basic_auth => auth)

  response["events"].each do |event|
    puts event["name"]
    event["images"]["images"].each do |image|
      puts image["id"]
      image["transforms"]["transforms"].each do |transform|
        puts transform["url"]
      end
    end
  end

View Output

Output

Garuda Indonesia Films and Music Festival: 1
  329070
  http://s1.eventfinder.co.nz/uploads/events/transformed/329070-170741-2.jpg
  http://s1.eventfinder.co.nz/uploads/events/transformed/329070-170741-15.jpg
  http://s1.eventfinder.co.nz/uploads/events/transformed/329070-170741-8.jpg
  http://s1.eventfinder.co.nz/uploads/events/transformed/329070-170741-7.jpg
  329050
  http://s1.eventfinder.co.nz/uploads/events/transformed/329050-170741-2.jpg?v=2
  http://s1.eventfinder.co.nz/uploads/events/transformed/329050-170741-15.jpg?v=2
  http://s1.eventfinder.co.nz/uploads/events/transformed/329050-170741-8.jpg?v=2
  http://s1.eventfinder.co.nz/uploads/events/transformed/329050-170741-7.jpg?v=2
Amazing Maze 'n Maize
  327124
  http://s1.eventfinder.co.nz/uploads/events/transformed/327124-169996-2.jpg?v=4
  http://s1.eventfinder.co.nz/uploads/events/transformed/327124-169996-15.jpg?v=4
  http://s1.eventfinder.co.nz/uploads/events/transformed/327124-169996-8.jpg?v=4
  http://s1.eventfinder.co.nz/uploads/events/transformed/327124-169996-27.jpg?v=4
  http://s1.eventfinder.co.nz/uploads/events/transformed/327124-169996-7.jpg?v=4
  327119
  http://s1.eventfinder.co.nz/uploads/events/transformed/327119-169996-2.jpg?v=5
  http://s1.eventfinder.co.nz/uploads/events/transformed/327119-169996-15.jpg?v=5
  http://s1.eventfinder.co.nz/uploads/events/transformed/327119-169996-8.jpg?v=5
  http://s1.eventfinder.co.nz/uploads/events/transformed/327119-169996-7.jpg?v=5