Eventfinda Developer API: Overview

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.

End points description
Resource descriptions

Rate limiting: Please limit Eventfinda API queries to a maximum of one request per second. Clients initiating more requests than this on a sustained basis will be throttled until their request rate falls below this threshold.

Quick Start Examples

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

Java
JavaScript
Objective-C
Perl
PHP
Python
Ruby

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 (https://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.eventfinda.com.au", 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

JavaScript

Please note that in order to make CORS you will need to contact us with your origin domain.

      <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script>

var username = 'apiusername';
var password = 'apipassword';
$.ajax({
  url: 'https://api.eventfinda.com.au/v2/events.json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader ("Authorization", "Basic " + btoa(username + ":" + password));
  },
  success: function(xhr) {
    console.log(xhr);
  }
});
</script>

Objective-C

      // Property declaration in header
  NSMutableData *apiData;

  // Implementation
  - (void)performAPIRequest
  {
      NSURLRequest *apiRequest    = [NSURLRequest requestWithURL:[NSURL URLWithString:@"https://api.eventfinda.com.au/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 = 'https://api.eventfinda.com.au/v2/events.json?rows=2';
  my $username = "...";
  my $password = "***";

  $ua->credentials("api.eventfinda.com.au: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 = 'https://api.eventfinda.com.au/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 = 'https://api.eventfinda.com.au/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('https://api.eventfinda.com.au/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
  https://cdn.eventfinda.com.au/uploads/events/transformed/329070-170741-2.jpg
  https://cdn.eventfinda.com.au/uploads/events/transformed/329070-170741-15.jpg
  https://cdn.eventfinda.com.au/uploads/events/transformed/329070-170741-8.jpg
  https://cdn.eventfinda.com.au/uploads/events/transformed/329070-170741-7.jpg
  329050
  https://cdn.eventfinda.com.au/uploads/events/transformed/329050-170741-2.jpg?v=2
  https://cdn.eventfinda.com.au/uploads/events/transformed/329050-170741-15.jpg?v=2
  https://cdn.eventfinda.com.au/uploads/events/transformed/329050-170741-8.jpg?v=2
  https://cdn.eventfinda.com.au/uploads/events/transformed/329050-170741-7.jpg?v=2
Amazing Maze 'n Maize
  327124
  https://cdn.eventfinda.com.au/uploads/events/transformed/327124-169996-2.jpg?v=4
  https://cdn.eventfinda.com.au/uploads/events/transformed/327124-169996-15.jpg?v=4
  https://cdn.eventfinda.com.au/uploads/events/transformed/327124-169996-8.jpg?v=4
  https://cdn.eventfinda.com.au/uploads/events/transformed/327124-169996-27.jpg?v=4
  https://cdn.eventfinda.com.au/uploads/events/transformed/327124-169996-7.jpg?v=4
  327119
  https://cdn.eventfinda.com.au/uploads/events/transformed/327119-169996-2.jpg?v=5
  https://cdn.eventfinda.com.au/uploads/events/transformed/327119-169996-15.jpg?v=5
  https://cdn.eventfinda.com.au/uploads/events/transformed/327119-169996-8.jpg?v=5
  https://cdn.eventfinda.com.au/uploads/events/transformed/327119-169996-7.jpg?v=5

Eventfinda Developer API: Overview

Overview & Examples

Quick Start Examples

Java

JavaScript

Objective-C

Perl

PHP

Python

Ruby

Output

API Help & Support

Log in / Sign up

Cart