NAV Navbar
shell
  • API Introduction
  • Clan
  • Player
  • Region
  • Server
  • 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.