Developers

The FFindr API lets you embed FFindr's content and functionality in your own web pages. Currently you can:

  1. event_get: retrieve event
  2. event_post: create event
  3. events_get: retrieve events
  4. team_get: retrieve team
  5. team_post: create team
  6. teams_get: retrieve teams
  7. player_get: retrieve player
  8. player_post: create player
  9. registrations_get: retrieve registrations and bids of an event
  10. rosters_get: retrieve team rosters
  11. user_get: retrieve user account
  12. user_post: create user account

If you feel that something is missing, just ask to get it implemented.

Getting started

Authentication

Authentication is required to access the FFindr API. Just generate your personal API key to get started.

Watch out! Please login to access this feature

Preparing the request

Requests to the FFindr API have the following base URL. The data format depends on whether you choose xml or json, just replace [format] with your format of choice. Then replace [api_key] with your 32-digit FFindr API key, and you are ready to communicate with the FFindr API.

$base_url = 'http://FFindr.com/api/[format]/[api_key]/';

Data exchange examples

The following PHP code samples explain how to prepare and send data. Currently there are three kinds of requests supported: GET (for data retrieval), POST (for data submission), and PUT (for data updates).

Every request requires some data in order to tell the API what to do. Refer to the documentation further down to see which arguments and values (data) is needed for your function of choice. Data is then prepared as follows:

// an argument array with its values
$request_vals = array(
  'argument_one'   => 'frisbee',
  'argument_two'   => 'true',
  'argument_three' => '2010',
);

// create argument value pairs
$request = array();
foreach($request_vals as $key => $val)
{
  $request[] = $key . '=' . urlencode($val);
}

// create the request url, e.g. for events
$request_url = $base_url . 'event/';

// create a single argument string with & separator
$request_data = implode('&', $request);

Finally you need to actually submit the data, using cURL for example. Each function type (GET, POST, PUT) requires some special settings:

1.1 GET: Making a data retrieval request

// all data is passed within the URL
$ch = curl_init($request_url . '?' . $request_data);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response_string = curl_exec($ch);
curl_close ($ch);

Actually you can quickly test GET requests within your browser: simply add a "?" to the $base_url and then all argument/value pairs separated by "&". Example: http://ffindr.com/api/xml/[api_key]/event/?event_country=slovenia&event_key=european-ultimate-championships-2011

1.2 POST: Making a data submission request

$ch = curl_init($request_url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// data is passed within the CURLOPT_POSTFIELDS option
curl_setopt($ch, CURLOPT_POSTFIELDS, $request_data);
$response_string = curl_exec($ch);
curl_close ($ch);

1.3 PUT: Making a data update request

$ch = curl_init($request_url);
// data is placed in a temporary data file
$putData = tmpfile();
fwrite($putData, $request_data);
fseek($putData, 0); 
// the data file is then passed within the CURLOPT_INFILE option
curl_setopt($ch, CURLOPT_INFILE, $putData);
curl_setopt($ch, CURLOPT_INFILESIZE, strlen($request_data));
curl_setopt($ch, CURLOPT_PUT, true);
$response_string = curl_exec($ch);
curl_close ($ch);

2. Extracting the data

// parse JSON response string, use simplexml_load_string for xml requests
$response = json_decode($response_string);

if ((int)$response->code === 200)
{
  // access data, check documentation for data structure
  echo $response->event->name;
}
else
{
  echo $response->error->message;
}

Documentation

As for everything else, the best way to learn the API is to use it.

1. event_get: retrieve event Back to top

Get an event by its country and its key (GET).

Arguments

* required

Request URL

$base_url . 'event/'

Response example JSON

{
  "code":200,
  "event":
  {
    "name":"B\u00e4m HAT 08",
    "link":"http://ffindr.com/en/event/baem-hat-08",
    "date":
    {
      "start":"Sat, 04 Oct 2008 00:00:00 +0200",
      "end":"Sun, 05 Oct 2008 00:00:00 +0200"
    },
    "place":
    {
      "name":"Neustadt an der Weinstra\u00dfe ",
      "country":"germany",
      "coordinates":
      {
        "latitude": 49.35252,
        "longitude": 8.173577
      }
    },
    "category":
    [
      "grass",
      "hat",
      "open",
      "all",
      "ultimate"
    ],
    "contact":
    {
      "name":"David",
      "email":"david...@...com",
      "phone":"01577..."
    },
    "description":"Hey leute,\r\nt\u00e4glich gibt es weitere ...",
    "administrator":
    {
      "username":"David",
      "link":"http://ffindr.com/en/user/David"
    }
  }
}

2. event_post: create event Back to top

Submit and create an event (POST). Event will be automatically included in the according calendars.

Arguments

Request URL and response example

Identical to event_get, with code 201 for successful event creation.

3. events_get: retrieve events Back to top

Get events by their country and a date range (GET). The request is limited to a maximum of 100 events.

Arguments

* required

Request URL

$base_url . 'events/'

Response example JSON

{
  "code":200,
  "events":
  {
    [
      // see response of a single event of event_get
    ]
  }
}

4. team_get: retrieve team Back to top

Get a team by its country and its key (GET).

Arguments

* required

Request URL

$base_url . 'team/'

Response example JSON

{
  "code":200,
  "team":
  {
    "name":"Iznogood",
    "link":"http://ffindr.com/en/team/france/iznogood",
    "founded":1986,
    "disbanded":2010,
    "place":
    {
      "name":"Noisy-le-Sec (93)",
      "country":"france",
      "coordinates":
      {
        "latitude":48.885323,
        "longitude":2.457851
      }
    },
    "category":"ultimate",
    "contact":
    {
      "name":"Chris",
      "website":"http://iznogoodonzenet.free.fr"
    },
    "administrator":
    {
      "username":"Chrisizno",
      "link":"http://ffindr.com/en/user/Chrisizno"
    },
    "biography":"il était une fois...",
    "practice":"jeudi 20h00"
  }
}

5. team_post: create team Back to top

Submit and create a team (POST).

Arguments

Request URL and response example

Identical to team_get, with code 201 for successful team creation.

6. teams_get: retrieve teams Back to top

Get teams by their country (GET).

Arguments

* required

Request URL

$base_url . 'teams/'

Response example JSON

{
  "code":200,
  "teams":
  {
    [
      // see response of a single team of team_get
    ]
  }
}

7. player_get: retrieve player Back to top

Get a player by its country and its key (GET).

Arguments

* required

Request URL

$base_url . 'player/'

Response example JSON

{
  "code":200,
  "player":
  {
    "name":"Christian Jennewein",
    "link":"http://ffindr.com/en/player/germany/christian-jennewein",
    "image":"ffindr.com/uploads/images/items/549c6028197b7f06204396699cd4192b72fb6388.png",
    "gender":"male",
    "playing_since":1999,
    "place":
    {
      "name":"Noisy-le-Sec (93)",
      "country":"france",
      "coordinates":
      {
        "latitude":48.885323,
        "longitude":2.457851
      }
    },
    "category":"ultimate",
    "administrator":
    {
      "username":"christian",
      "link":"http://ffindr.com/en/user/christian"
    },
    "biography":"Once upon a time..."
  }
}

8. player_post: create player Back to top

Submit and create a player (POST).

Arguments

Request URL and response example

Identical to player_get, with code 201 for successful player creation.

9. registrations_get: retrieve registrations and bids of an event Back to top

Retrieve all registrations including all their submitted bids for a given event. Please note: only the event's admin is entitled to retrieve the data (GET).

Arguments

* required

Request URL

$base_url . 'registrations/'

Response variables

Response example JSON

{
  "code":200,
  "registrations":
  [
    {
      "division":"Open",
      "bids":
      [
        {
          "name":"First Player",
          "link":"http://ffindr.com/en/player/germany/first-player",
          "email":"first@player.com",
          "submitdate":"Sat, 02 Oct 2010 10:14:15 +0200",
          "status":0,
          "adminStatus":1
        },
        {
          "name":"Second Player",
          "link":"http://ffindr.com/en/player/france/second-player",
          "email":"second@player.com",
          "submitdate":"Sat, 02 Oct 2010 10:37:11 +0200",
          "status":0,
          "adminStatus":1,
          "adminNote":"Paid 100 euros too much."
        }
      ]
    }
  ]
}

10. rosters_get: retrieve team rosters Back to top

Get all rosters for a given team (GET).

Arguments

* required

Request URL

$base_url . 'rosters/'

Response variables

Response example JSON

{
  "code":200,
  "rosters":
  [
    {
      "name":"My Team 2010",
      "submitdate":"Tue, 05 Sep 2010 13:30:12 +0200",
      "lastmod":"Tue, 05 Oct 2010 14:06:40 +0200",
      "players":
      [
        {
          "name":"First Player",
          "link":"http://ffindr.com/en/player/germany/first-player",
          "number":1,
          "position":1,
          "type":2,
          "captain":1            
        },                      
        {
          "name":"Second Player",
          "link":"http://ffindr.com/en/player/france/second-player",
          "number":2,
          "position":2,
          "type":1,
          "captain":0            
        }
      ]
    }
  ]
}

11. user_get: retrieve user account Back to top

Retrieve a user account (GET).

Arguments

* required

Request URL

$base_url . 'user/'

Response example JSON

{
  "code":200,
  "user":
  {
    "username":"santaclaus",
    "country_tld":"no",
    "language":"en",
    "link":"http://ffindr.com/en/user/santaclaus"
  }
}

12. user_post: create user account Back to top

Create a new user account (POST). Please note that all created user accounts automatically approve FFindr's Terms of Service.

Arguments

* required

Request URL and response example

Identical to user_get, with code 201 for successful user account creation.

Link to FFindr

Use one of the following graphics to link from your website to FFindr.

FFindr

<a href="http://ffindr.com" alt="FFindr.com"><img alt="FFindr" src="http://ffindr.com/images/banner/ffindr-180x100-flags.png" title="FFindr! find Frisbee anywhere." style="border:0;"></a>

FFindr

<a href="http://ffindr.com" alt="FFindr.com"><img alt="FFindr" src="http://ffindr.com/images/banner/ffindr-234x60-flags.png" title="FFindr! find Frisbee anywhere." style="border:0;"></a>

FFindr

<a href="http://ffindr.com" alt="FFindr.com"><img alt="FFindr" src="http://ffindr.com/images/banner/ffindr-468x60-flags.png" title="FFindr! find Frisbee anywhere." style="border:0;"></a>

FFindr

<a href="http://ffindr.com" alt="FFindr.com"><img alt="FFindr" src="http://ffindr.com/images/banner/ffindr-80x15-light.png" title="FFindr! find Frisbee anywhere." style="border:0;"></a>

FFindr

<a href="http://ffindr.com" alt="FFindr.com"><img alt="FFindr" src="http://ffindr.com/images/banner/ffindr-80x15-dark.png" title="FFindr! find Frisbee anywhere." style="border:0;"></a>