Skip to content

Battlefield 2

Battlefield 2 endpoints are available at https://api.bflist.io/v2/bf2/.

Live stats#

Retrieve the current number of active players and servers, along with data coverage. coverage refers to the percentage (0.0-1.0) of known servers for which we currently have data available via the API.

A note on Battlefield 2 active player counts

We do our best to exclude bots from the active player count, but it's possible that a small number of bots are still included. Please consider these numbers as approximate.

Request

GET /livestats HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "servers": 164,
  "players": 303,
  "coverage": 0.993939394
}

List servers#

Get a paginated list of currently available servers.

Since servers for older Battlefield games do not have a guid, one is generated using the server's ip and port. The generated guid is bflist-specific and neither known to nor returned by the server.

The kind field tells you whether a player is a human, a bot, a spectator, or a seeder. See Player kinds for details.

Join links

If a server's current mod is supported by joinme.click, the joinLink-property will contain a URL to directly join the server. In environments which do not allow custom URL protocols (e.g. Discord, Twitch chat), use joinLinkWeb instead. Users will be directed to the joinme.click website and can join from there.

Note: Both properties will be null for servers running mods not supported by joinme.click. For password protected servers, both joinLink and joinLinkWeb are null. These servers cannot be joined directly, since Battlefield 2 will simply show an error instead of prompting players to enter the password.

Server variables

We support custom server variables added using the sponsortext standard. Any variables provided via sv.sponsorText are automatically parsed and exposed under the variables property.

If you prefer to handle parsing yourself - or are already using sponsorText for another purpose - you can access the raw value directly via the sponsorText property.

Request

GET /servers HTTP/1.1

Parameters

param Description
cursor Pagination cursor (optional, required if after is set)
after Pagination marker (optional)
perPage Number of items per page (optional, default: 50)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "servers": [
    {
      "guid": "56be01-bfd9160-a0324d8-3e1af98",
      "ip": "37.230.210.130",
      "port": 16567,
      "queryPort": 29900,
      "name": "PlayBF2! T~GAMER #1 Allmaps",
      "numPlayers": 47,
      "maxPlayers": 64,
      "mapName": "Kubra Dam",
      "mapSize": 64,
      "password": false,
      "gameType": "gpm_cq",
      "gameVersion": "1.5.3153-802.0",
      "gameVariant": "bf2",
      "timelimit": 2100,
      "roundsPerMap": 1,
      "ranked": true,
      "anticheat": true,
      "battlerecorder": true,
      "demoIndex": "http://bf2.tgamer.ru/demo/1",
      "demoDownload": "http://bf2.tgamer.ru/demo/1",
      "voip": true,
      "autobalance": true,
      "friendlyfire": false,
      "tkmode": "Punish",
      "startdelay": 45,
      "spawntime": 15,
      "sponsorText": "$vars:website=http://bf2.tgamer.ru;discord=https://discord.gg/Tjt3sK8;provider=playbf2.ru$",
      "sponsorLogoUrl": "http://bf2.tgamer.ru/files/tgamer.png",
      "communityLogoUrl": "http://bf2.tgamer.ru/files/tgamer.png",
      "scorelimit": 0,
      "ticketratio": 180,
      "teamratio": 100,
      "team1": "MEC",
      "team2": "US",
      "pure": false,
      "globalUnlocks": true,
      "reservedSlots": 0,
      "dedicated": true,
      "os": "linux-64",
      "bots": false,
      "fps": 312,
      "plasma": false,
      "coopBotRatio": 0,
      "coopBotCount": 0,
      "coopBotDiff": 0,
      "noVehicles": false,
      "joinLink": "bf2://37.230.210.130:16567",
      "joinLinkWeb": "https://joinme.click/g/bf2/37.230.210.130:16567",
      "variables": {
        "website": "http://bf2.tgamer.ru",
        "discord": "https://discord.gg/Tjt3sK8",
        "provider": "playbf2.ru"
      },
      "teams": [
        {
          "index": 1,
          "label": "MEC"
        },
        {
          "index": 2,
          "label": "US"
        }
      ],
      "players": [
        {
          "pid": 482774077,
          "name": "GooFy",
          "tag": "=OCA=",
          "score": 24,
          "kills": 12,
          "deaths": 1,
          "ping": 20,
          "team": 2,
          "teamLabel": "US",
          "aibot": false,
          "kind": "human"
        },
        // more players
      ]
    },
    // more servers
  ],
  "cursor": "4c379877-b1f0-4534-8a4c-627d9503de9e",
  "hasMore": true
}

Get a server#

Retrieve a single server.

The kind field tells you whether a player is a human, a bot, a spectator, or a seeder. See Player kinds for details.

Request

GET /servers/{ip}:{port} HTTP/1.1

Parameters

param Description
ip Server's (public) IP address
port Server's game port

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "7ca45bd-2a591f5-223b6a6-d43525",
  "ip": "185.107.96.59",
  "port": 16567,
  "queryPort": 29900,
  "name": "SUPER@ - S1 Strike at Karkand Infantry Only",
  "numPlayers": 61,
  "maxPlayers": 64,
  "mapName": "Strike At Karkand",
  "mapSize": 64,
  "password": false,
  "gameType": "gpm_cq",
  "gameVersion": "1.5.3153-802.0",
  "gameVariant": "bf2",
  "timelimit": 0,
  "roundsPerMap": 10,
  "ranked": true,
  "anticheat": true,
  "battlerecorder": true,
  "demoIndex": "http://battlerecorder.superinfantryclan.com/s1",
  "demoDownload": "http://battlerecorder.superinfantryclan.com/s1",
  "voip": true,
  "autobalance": true,
  "friendlyfire": false,
  "tkmode": "No Punish",
  "startdelay": 15,
  "spawntime": 15,
  "sponsorText": "$vars:website=http://www.superinfantryclan.com;discord:https://discord.gg/wSFyxMn;provider=bf2hub.com",
  "sponsorLogoUrl": "http://www.superinfantryclan.com/bf2/109338097-superbf2.jpg",
  "communityLogoUrl": "http://www.superinfantryclan.com/bf2/109338097-superbf2.jpg",
  "scorelimit": 0,
  "ticketratio": 100,
  "teamratio": 100,
  "team1": "MEC",
  "team2": "US",
  "pure": true,
  "globalUnlocks": true,
  "reservedSlots": 0,
  "dedicated": true,
  "os": "linux-64",
  "bots": false,
  "fps": 36,
  "plasma": false,
  "coopBotRatio": 0,
  "coopBotCount": 0,
  "coopBotDiff": 0,
  "noVehicles": 1,
  "joinLink": "bf2://185.107.96.59:16567",
  "joinLinkWeb": "https://joinme.click/g/bf2/185.107.96.59:16567",
  "variables": {
    "website": "http://www.superinfantryclan.com",
    "discord": "https://discord.gg/wSFyxMn",
    "provider": "bf2hub.com"
  },
  "teams": [
    {
      "index": 1,
      "label": "MEC"
    },
    {
      "index": 2,
      "label": "US"
    }
  ],
  "players": [
    {
      "pid": 43812139,
      "name": "The_Man_13",
      "tag": "=420=",
      "score": 10,
      "kills": 4,
      "deaths": 1,
      "ping": 121,
      "team": 1,
      "teamLabel": "MEC",
      "aibot": false,
      "kind": "human"
    },
    // more players
  ]
}

Get a player#

Fetch a currently active player.

The kind field tells you whether a player is a human, a bot, a spectator, or a seeder. See Player kinds for details.

Player Name Conflicts

In rare cases, two active players may have exactly the same name. To avoid inconsistencies, the API responds with a 409 Conflict error if a request refers to a player name that isn't unique.

Request

GET /players/{name} HTTP/1.1

Parameters

param Description
name Player's url-encoded name/nick (without any tag/prefix)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pid": 500337422,
  "name": "weah92",
  "tag": "",
  "score": 52,
  "kills": 18,
  "deaths": 2,
  "ping": 10,
  "team": 2,
  "teamLabel": "US",
  "aibot": false,
  "kind": "human"
}

Get a player's current server#

Get the server a player is currently playing on.

Request

GET /players/{name}/server HTTP/1.1

Parameters

param Description
name Player's url-encoded name/nick (without any tag/prefix)

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "guid": "42fd2a6-399101e-c01aca-2cc568",
  "ip": "135.125.56.26",
  "port": 16469,
  "queryPort": 29940,
  "name": "=DOG= No Explosives (Infantry)",
  "numPlayers": 12,
  "maxPlayers": 64,
  "mapName": "Strike At Karkand",
  "mapSize": 64,
  "password": false,
  "gameType": "gpm_cq",
  "gameVersion": "1.5.3153-802.0",
  "gameVariant": "bf2",
  "timelimit": 2400,
  "roundsPerMap": 4,
  "ranked": true,
  "anticheat": true,
  "battlerecorder": true,
  "demoIndex": "http://www.dogclan.net/demos/",
  "demoDownload": "http://www.dogclan.net/demos/",
  "voip": true,
  "autobalance": true,
  "friendlyfire": true,
  "tkmode": "No Punish",
  "startdelay": 15,
  "spawntime": 15,
  "sponsorText": "Join Us On Discord     https://discord.gg/RB7PjBk",
  "sponsorLogoUrl": "http://www.dogclan.net/banner.png",
  "communityLogoUrl": "http://www.dogclan.net/banner.png",
  "scorelimit": 0,
  "ticketratio": 100,
  "teamratio": 100,
  "team1": "MEC",
  "team2": "US",
  "pure": true,
  "globalUnlocks": true,
  "reservedSlots": 0,
  "dedicated": true,
  "os": "linux-64",
  "bots": false,
  "fps": 36,
  "plasma": false,
  "coopBotRatio": 0,
  "coopBotCount": 0,
  "coopBotDiff": 0,
  "noVehicles": true,
  "joinLink": "bf2://135.125.56.26:16469",
  "joinLinkWeb": "https://joinme.click/g/bf2/135.125.56.26:16469",
  "teams": [
    {
      "index": 1,
      "label": "MEC"
    },
    {
      "index": 2,
      "label": "US"
    }
  ],
  "players": [
    {
      "pid": 500178902,
      "name": "roxxy27091987",
      "tag": "=DOG=",
      "score": 72,
      "kills": 29,
      "deaths": 7,
      "ping": 39,
      "team": 2,
      "teamLabel": "US",
      "aibot": false,
      "kind": "human"
    },
    // more players
  ]
}

Player kinds#

Each player has a kind field, which tells apart human players from bots, spectators and seeders. It is derived by us (the game's own aibot flag is passed through unchanged) and is also what the active player count is based on, i.e. only players of kind human are counted.

Note: Do not store kind permanently. A player's reported kind may change over time, and players may be reported as seeder temporarily.

kind Description
human A human player
aibot A bot flagged as such by the server (aibot is true)
bot A bot not flagged as such by the server (e.g. coop bots using regular accounts)
spectator An automated spectator account (e.g. BF2AutoSpectator)
seeder A player without any score, kills or deaths and without a ping or a pid
unknown Cannot be determined, i.e. a player with an invalid (negative) pid

Seeders and local profiles

Players using a local/singleplayer profile also have a pid of 0. Players that have just joined may not have a ping yet. Until they have a non-zero score, kills or deaths (or a ping, if they have a pid), they cannot be told apart from seeders and are temporarily reported as seeder. Once they become active, their kind changes to human.