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

  • event_country * STRING (the event's country of origin in English and with dashes instead of spaces)
  • event_key * STRING (the event name without spaces and special characters, copy this part from the event's URL)

* 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

  • name * STRING (a name for the event that is not yet used for another event)
  • date_start * DATE (first day of the event formatted YYYY-MM-DD, e.g. 2010-12-31)
  • date_end * DATE (last day of the event formatted YYYY-MM-DD, e.g. 2010-12-31)
  • location * STRING (name of the event's location)
  • country_tld * STRING (country code of the event's location, e.g. US=United States, UK=United Kingdom)
  • latitude * FLOAT (latitude of the event's location)
  • longitude * FLOAT (longitude of the event's location)
  • disciplines * INT (comma-separated surface codes: 50=ultimate, 51=discgolf, 52=freestyle, 53=ddc, ... ask for others)
  • surfaces * INT (comma-separated surface codes: 10=grass, 11=turf, 12=indoor, 13=beach, 14=beach indoor, 17=indoor turf)
  • divisions * INT (comma-separated division codes: 30=open, 31=women, 32=mixed, 33=masters, 34=juniors, ... ask for others)
  • level * INT (one level code: 40=beginner, 41=intermediate, 42=advanced, 43=all levels)
  • format * INT (one format code: 20=tournament, 21=hat tournament, 22=meeting, 24=league, 25=hat league, ... ask for others)
  • description TEXT (provide a detailed description)
  • website STRING (valid URL of the event's website)
  • contact_name STRING (name of a/the contact person)
  • contact_phone STRING (phone number of a/the contact person)
  • contact_email STRING (valid e-mail address of a/the contact person)
  • group STRING (with the according credentials you can add events to an existing event group, e.g. pass "bula-sanctioned" to BULA sanction the event if you are a BULA admin)

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

  • event_country * STRING (the events' country of origin in English and with dashes instead of spaces)
  • date_start * DATE (events' start date not before YYYY-MM-DD, e.g. 2011-06-09)
  • date_end * DATE (events' end date not after YYYY-MM-DD, e.g. 2011-06-13)

* 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

  • team_country * STRING (the team's country of origin without spaces and special characters)
  • team_key * STRING (the team name without spaces and special characters, copy this part from the team's URL)

* 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

  • name * STRING (a unique team name)
  • contact_email * STRING (valid e-mail address of a/the contact person)
  • location * STRING (name of the event's location)
  • country_tld * STRING (country code of the event's location, e.g. US=United States, UK=United Kingdom)
  • latitude * FLOAT (latitude of the event's location)
  • longitude * FLOAT (longitude of the event's location)
  • disciplines * INT (comma-separated surface codes: 50=ultimate, 51=discgolf, 52=freestyle, 53=ddc, ... ask for others)
  • contact_name STRING (name of a/the contact person)
  • contact_phone STRING (phone number of a/the contact person)
  • date_start INTEGER (the year of the team's foundation formatted YYYY, e.g. 2010)
  • date_end INTEGER (the year of the team's breakup formatted YYYY, e.g. 2010)
  • biography TEXT (provide a detailed biography)
  • practice TEXT (provide a information about regular training sessions, meetings, etc.)
  • website STRING (valid URL of the team's website)

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). The request is limited to a maximum of 250 teams.

Arguments

  • team_country * STRING (the teams' country of origin in English and with dashes instead of spaces)

* 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

  • player_country * STRING (the player's country of origin without spaces and special characters)
  • player_key * STRING (the player name without spaces and special characters, copy this part from the player's URL)

* 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

  • name * STRING (the player's first and last name)
  • contact_email * STRING (the player's e-mail address)
  • location * STRING (name of the player's hometown)
  • country_tld * STRING (country code of the hometown, e.g. US=United States, UK=United Kingdom)
  • latitude * FLOAT (latitude of the hometown's location)
  • longitude * FLOAT (longitude of the hometown's location)
  • disciplines * INT (comma-separated surface codes: 50=ultimate, 51=discgolf, 52=freestyle, 53=ddc, ... ask for others)
  • contact_phone STRING (phone number of the player)
  • website STRING (valid URL of the player's website)
  • birthday INTEGER (the player's date of birth formatted YYYY-MM-DD, e.g. 1987-01-13)
  • gender INTEGER (gender code, i.e. 1 for male and 2 for female players)
  • biography TEXT (provide a detailed biography)
  • privacy INTEGER (privacy code to control who can see the page: 0=administrator only, 1=registered users, 2=everyone)

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

  • event_country * STRING (the event's country of origin in English and with dashes instead of spaces)
  • event_key * STRING (the event name without spaces and special characters, copy this part from the event's URL)

* required

Request URL

$base_url . 'registrations/'

Response variables

  • status INT (0=pending, 1=selected, 2=refused)
  • adminStatus INT (0=unconfirmed, 1=confirmed, 2=paid)
  • adminNote TEXT

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

  • team_country * STRING (the team's country of origin without spaces and special characters)
  • team_key * STRING (the team name without spaces and special characters, copy this part from the team's URL)

* required

Request URL

$base_url . 'rosters/'

Response variables

  • position INT (0=all, 1=handler, 2=cutter, 3=deep cutter)
  • type INT (0=player, 1=coach, 2=staff, 3=guest)
  • captain BOOLEAN (0=no, 1=yes)
  • gender INT (0=unknown, 1=male, 2=female)

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

  • username * STRING (the username of the FFindr user account)

* 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

  • username * STRING (a username of 4 to 20 alphanumeric characters that is not yet used for another account)
  • password * STRING (arbitrary string of 4 to 20 characters)
  • email * STRING (an e-mail address that is not yet used for another account)
  • country_tld STRING (country code of the event's location, e.g. US=United States, UK=United Kingdom)
  • language STRING (language code of available interface languages: EN=english, DE=deutsch, FR=français, ES=español, RU=pусский, UA=українська, SE=svenska, IT=italiano, NL=dutch, CA=catalá)

* 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>