ETF2L REST API v1 beta

The ETF2L REST API allows anyone to build applications around the ETF2L dataset, whether they are desktop, mobile or web applications. The API supports several output format and leaves the choice to the developer. v1 of the API is purely GET based, i.e. there are no routes to create, modify or delete data on the server.

Table of contents:

Supported Output Formats

You can request a different output format either by suffixing the corresponding extension to the url or by sending an appropriate Accept header with your request.

JSON(p)

  • Mime-type: application/json
  • URL-extension: .json

To request JSONP you will have to specify a callback parameter 'cb'.

Example JSONP, Example plain JSON

XML

  • Mime-type: application/xml
  • URL-extension: .xml

XML does not really support the datastructures we are serving (mixed arrays and hashes) and would require special treatment for each route. We don't want that, so our XML encoder simply tries its best to fit the data into xml as best as possible without requiring changes to the data itself.

Long story short: you cannot expect sane responses when using the XML format. If you have the choice, you'd rather use something that actually supports arrays and hashes. Example

Yaml

  • Mime-type: application/yaml
  • URL-extension: .xml

Specs and example

VDF

  • Mime-type: text/vdf
  • URL-extension: .vdf

We additionally provide our data in the Valve Data Format. This is especially (and probably only) useful when a gameserver is processing the data. It is the format Valves Source Engine understands natively. Example

HTML

  • Mime-type: text/html
  • URL-extension: -

For convenience during development we also provide a HTML interface. This allows you to click through the API like a website. This is also the default format. Example

Some more exotic formats

Because we can. We do not expect anyone to use these and consider using them as bad practice. But they support our datastructures completely and allow for some quick hacking. Without further ado, we also support these:

  • perl - outputs a perl datastructure, application/x-perl or .perl, example
  • php - outputs a serialized php array, application/x-php or .php, example

Versioning

We will try not to break the API when we're adding new features and will only "release" new versions if it is really necessary. We will also give you a heads up at least a month before we're going to deploy new releases.

With this in mind you have to decide for yourself whether a month is enough for you and users of your software to update your software. If it is we strongly recommend using the latest version.

If you want to be on the safe side, you can target a specific version of the API by accessing a different subdomain. The default https://api.etf2l.org will always point to the latest version.

Currently there is only v1 available, its direct access URL is https://api.etf2l.org.

Pagination

Some of the results will be paginated and will only return 10 entries at once, e.g. player transfers, team results and so on. Pagination is handled the same all over the api. If you want to fetch more entries at once you can use the per_page parameter. Currently this is limited to 100 entries at once and might change in the future. If a resource supports pagination you have to account for it, don't expect to retrieve all entries at once with high per_page values.

By omitting the page parameter the first page will be returned. Paginated results will have a page subsection with more details about the page currently being displayed.

Example:

...,
page:{
    entries_per_page: 10,
    next_page_url: "https://api.etf2l.org/player/7679/transfers/3",
    page: 2,
    previous_page_url: "https://api.etf2l.org/player/7679/transfers",
    total_pages: 3
},
...

Exceptions and errors

All responses include a 'status' section with an error message and the https status code.

The API will respond with the following error codes and will additionally add the corresponding error messages to the body of the response:

Timespans

Some of the results will only show entries for the last 28 days by default. If you want a larger timespan you can use one of these GET parameters:

Available Resources

Player

/player/:id

Basic player details. id can be either the player id, a SteamID or a SteamID64.

Examples:

/player/:id/transfers/:page

Returns all transfers (team joins/leaves) of the player. This resource supports the timespan parameters (see above). By default the result contains all transfers, i.e. since is 0 by default.

Examples:

/player/:id/results/:page

Returns the match history of the player. This resource supports the timespan parameters (see above).

Examples:

Team

/team/:id

Basic team details.

Examples:

/team/:id/transfers/:page

Returns all transfers (team joins/leaves) of the team. This resource supports the timespan parameters (see above). By default the result contains all transfers, i.e. since is 0 by default.

Examples:

/team/:id/results/:page

Returns the match history of the team. This resource supports the timespan parameters (see above).

Examples:

/team/:id/matches/:page

Shows all upcoming matches for this team. Can be limited by these parameters:

  • competition Only shows matches for this competition (expects the competition id)
  • only_scheduled Only shows matches that are scheduled
Examples:

Competition

/competition/list/:page

Lists all currently running competitions

Can be controlled by these parameters:

  • archived Also shows archived competitions
  • category Filters the output by category
Example:

/competition/:id

Shows details about the competition.

Examples:

/competition/:id/teams/:page

Lists all teams participating in the competition.

Example:

/competition/:id/results/:page

Lists all match results for this competition. This resource supports the timespan parameters (see above).

Examples:

/competition/:id/matches/:page

Lists all upcoming matches for this competition.

Can be limited by these parameters:

  • only_scheduled Only shows matches that are scheduled
Examples:

Recruitment

/recruitment/players/:page

Lists all recruitment posts for players looking for teams. This resource supports the timespan parameters (see above) and can be limited further by these parameters:

  • class Can be specified multiple times. Limits recruitment posts for only these classes.
  • skill Can be specified multiple times. Limits recruitment posts for only these divisions.
  • country Limit recruitment posts by country and filter all others.
  • type Limit recruitment posts by team type.
Examples:

/recruitment/team/:page

This is the same as the /recruitment/players/ resource, but for teams.

Examples:

Other

/transfers/:page

Returns all transfers (team joins/leaves) of the the last 28 days. This resource supports the timespan parameters (see above). If you are more interested in scraping all data, than retrieving the latest transfers you can use the ascending parameter to invert the sorting order. This also applies to the player and team transfer views. If you want to filter by team type you can use the type parameter.

Examples:

/results/:page

Returns the most recent match history regardless of competition, team or player. This resource supports the timespan parameters (see above).

You can filter the output by using the country parameter.

Examples:

/whitelists

Returns a list of all whitelists currently maintained by etf2l.

Example:

/search/:term/:page

Returns a list of players and teams matching the search query. You can filter the result with the type parameter.

Examples: