Public API

The basics

• Base URL: https://samp.directory/api/v1
• Everything is a GET request returning JSON. Times are UTC in ISO 8601, e.g. 2026-10-05T21:18:18Z.
• Responses are cached for 60 seconds, and servers are re-checked about every 10 minutes, so polling faster than once a minute gains nothing.
• Limit: 60 requests a minute per IP address. Past that you get 429 with a Retry-After header.
• It can be called straight from a web page; any website is allowed.
• Please credit and link samp.directory where you show the data.
• Version 1 will not change in ways that break existing code. New fields may be added, so ignore ones you do not know.

GET/servers

Servers busiest first. A server reachable at several addresses is listed once, with the rest in otherAddresses.

search

Part of a name, gamemode or ip:port.

category

Gamemode slugs, comma-separated: roleplay, deathmatch, freeroam, … (see /facets).

language

Language slugs, comma-separated: english, russian, … (see /facets).

includeEmpty

true to include servers with no players and offline ones. Default false.

passworded

true or false to only get servers with or without a password.

page, size

Pages start at 0. size is 1–200, default 100.

curl "https://samp.directory/api/v1/servers?category=roleplay&size=2"

{
  "total": 312, "page": 0, "size": 2, "totalPlayers": 10083,
  "servers": [
    {
      "address": "51.79.37.124:7777",
      "name": "FZ Roleplay [S1] Rol en español",
      "online": true, "players": 897, "maxPlayers": 899,
      "gamemode": "FZ:RP v5.06", "language": "Español - Spanish",
      "categories": ["roleplay"], "languages": ["spanish"],
      "passworded": false, "openMp": false, "version": "0.3.7",
      "website": "https://rol.fenixzone.com", "discord": null,
      "otherAddresses": ["51.161.18.96:7777"],
      "lastSeenOnline": "2026-10-05T23:06:21Z",
      "url": "https://samp.directory/server/51.79.37.124/7777",
      …
    }
  ]
}

GET/servers/{ip}/{port}

One server, with the same fields plus its rank by players and, if its owner has written one, a description. 404 when the server is not listed.

curl "https://samp.directory/api/v1/servers/141.95.95.184/7777"

GET/servers/{ip}/{port}/history

Player counts over time, oldest first, about one reading an hour.

days

1 to 90. Default 1.

[{ "time": "2026-10-05T10:03:35Z", "players": 897, "online": true }, …]

GET/servers/{ip}/{port}/players

Who is on the server, highest score first, as of the last check. Empty for servers with 100 or more players: SA:MP servers do not share their player list past that.

[{ "name": "Raul_Castillo", "score": 370 }, …]

GET/stats

Players and servers online across the whole network right now, the 24-hour peak and the all-time record.

{ "players": 13505, "serversOnline": 1317, "serversWithPlayers": 335,
  "peak24h": 22743, "peak24hTime": "2026-10-05T16:36:52Z",
  "record": 22743, "recordTime": "2026-10-05T16:36:52Z",
  "since": "2026-10-04T20:58:45Z", "time": "2026-10-05T23:07:08Z" }

GET/stats/history

Total players online across all servers over time, in the same shape as a server's history.

days

1 to 90. Default 1.

GET/facets

Gamemode categories and languages, with how many servers and players each has. Use the slugs to filter /servers.

{ "categories": [{ "slug": "roleplay", "name": "Roleplay", "servers": 685, "players": 10083 }, …],
  "languages":  [{ "slug": "portuguese", "name": "Portuguese", "servers": 412, "players": 3908 }, …] }

Just want a status image?

Every server page has ready-made badges and a forum banner under “For server owners”, with code for HTML, BBCode and Markdown. No code needed.