NAV Navbar
Logo
shell

API Introduction

Welcome to the S4DB API.

The S4DB API allows you to access the S4DB data in a simple, programmatic way using conventional HTTPS requests.

The S4DB API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints.

Request an API Key

You can request an S4DB API Key by opening a ticket in the S4DB Support System. You may explain your use case and also how many requests you expect to do.

Authentication

The S4DB API requires you to provide a valid S4DB API Key for each request. The S4DB API Key has to be added as a header “X-S4DB-API-Key: KEY”. You have to replace “KEY” with your own key.

Region

A lot of endpoints have the optional url parameter “region”. With this parameter you can specify from which region you’d like to request the data.

Errors

The S4DB API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is wrong.
401 Unauthorized – Your API key is wrong.
404 Not Found – The specified API could not be found.
405 Method Not Allowed – You tried to access an API with an invalid method.
429 Too Many Requests – You’re requesting too much.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Clan

Get a specific Clan

curl "https://api.s4db.net/clan/NewSphere"
  -H "X-S4DB-API-Key: KEY"

The above command returns JSON structured like this:

{
   "success": true,
   "name": "NewSphere",
   "master": "NewSphereMemo",
   "member_count": 25,
   "announcement": "Welcome to NewSphere, Invite Only. ",
   "description": "",
   "views": 27300,
   "favorites": 93,
   "fame": 59.88538681948424,
   "hate": 40.11461318051576
}

This endpoint retrieves a specific Clan.

HTTP Request

GET https://api.s4db.net/clan/<Name>

URL Parameters

Parameter Description
Name The Name of the Clan to retrieve.

Query Parameters

Parameter Required Default Description
region No eu The region where you want the data from. Please check the region endpoint for more information.

Player

Get a specific Player

curl "https://api.s4db.net/player/Buffele"
  -H "X-S4DB-API-Key: KEY"

The above command returns JSON structured like this:

{
   "success": true,
   "name": "Buffele",
   "clan": null,
   "level": 80,
   "exp": 6806600,
   "playtime": 8235524,
   "tdrate": 60.2,
   "kdrate": 1,
   "matches_played": 9782,
   "matches_won": 3670,
   "matches_lost": 6112,
   "last_online": "2017-02-14T23:00:00.000Z",
   "views": 26727,
   "favorites": 265,
   "fame": 88.47209515096066,
   "hate": 11.527904849039345
}

This endpoint retrieves a specific Player.

HTTP Request

GET https://api.s4db.net/player/<Name>

URL Parameters

Parameter Description
Name The Name of the Player to retrieve.

Query Parameters

Parameter Required Default Description
region No eu The region where you want the data from. Please check the region endpoint for more information.

Region

A region in S4DB represents the location where the data came from.

Get All Regions

curl "https://api.s4db.net/region"
  -H "X-S4DB-API-Key: KEY"

The above command returns JSON structured like this:

[
   {
      "slug": "eu",
      "name": "Europe"
   },
   {
      "slug": "sa",
      "name": "South America"
   }
]

This endpoint retrieves all regions.

HTTP Request

GET https://api.s4db.net/region

Server

Get All Servers

curl "https://api.s4db.net/server"
  -H "X-S4DB-API-Key: KEY"

The above command returns JSON structured like this:

[
   {
      "id": 23,
      "name": "AeriaGames Login",
      "player_limit": -1,
      "player_online": -1,
      "state": 2,
      "last_update": "2017-02-23T18:08:03.000Z"
   },
   {
      "id": 1,
      "name": "Auth",
      "player_limit": -1,
      "player_online": -1,
      "state": 2,
      "last_update": "2017-02-23T18:08:23.000Z"
   },
   {
      "id": 10,
      "name": "English 1 (Europe)",
      "player_limit": 4000,
      "player_online": 721,
      "state": 2,
      "last_update": "2017-02-23T18:08:24.000Z"
   }
]

This endpoint retrieves all servers.

HTTP Request

GET https://api.s4db.net/server

Query Parameters

Parameter Required Default Description
region No eu The region where you want the data from. Please check the region endpoint for more information.