1.6.1 • Published 1 month agoCLI

fivem-server-api

Licence

ISC

Version

1.6.1

Deps

Size

84 kB

Vulns

Weekly

Stars

Summary Dependency Versions

fivem-server-api

Package for getting information about a FiveM server via its API endpoints.

Installation

npm i fivem-server-api

CLI

npx fivem-server-api cfx.re/join/my59jq
npx fivem-server-api 1.2.3.4:30120 --json
npx fivem-server-api cfx.re/join/code --timeout=15000

Usage

// ESM
import FiveM, { FiveMError } from "fivem-server-api";

// CJS
const FiveM = require("fivem-server-api");

Accepted Input Formats

Format	Example
IP:PORT	`205.178.183.132:30120`
IP only	`205.178.183.132`
Domain:PORT	`myserver.com:30120`
CFX.re short URL	`cfx.re/join/my59jq`
CFX.re full URL	`https://cfx.re/join/my59jq`
CFX.re code only	`my59jq`

Basic Example

import FiveM from "fivem-server-api";

const server = new FiveM("cfx.re/join/my59jq", { timeout: 10000 });

const online = await server.getServerStatus();

if (online) {
  const info = await server.getServer();
  console.log("Name:", await server.getServerName());
  console.log("Players:", await server.getPlayers());
  console.log("Resources:", (await server.getResources()).length);
}

Error Handling

All methods throw FiveMError on failure, except getServerStatus() which returns false when unreachable.

import FiveM, { FiveMError } from "fivem-server-api";

const server = new FiveM("1.2.3.4:30120");

try {
  const players = await server.getPlayersAll();
  console.log(`Online: ${players.length}`);
} catch (err) {
  if (err instanceof FiveMError) {
    console.error(`[${err.method}] ${err.message}`);
  }
}

FiveMError properties: name, message, method, url, status, cause.

Options

Option	Type	Default	Description
`timeout`	`number`	`5000`	Request timeout in milliseconds
`retries`	`number`	`0`	Number of retry attempts on failure
`retryDelay`	`number`	`1000`	Delay between retries in milliseconds
`cacheTtl`	`number`	`5000`	Cache duration for `info.json` in ms. Set `0` to disable
`debug`	`boolean \| (msg: string) => void`	`false`	Enable logging. Pass `true` for console.log, or a custom logger function
`minInterval`	`number`	`0`	Minimum delay between requests in ms (rate limiting)

const server = new FiveM("cfx.re/join/code", {
  timeout: 10000,
  retries: 2,
  retryDelay: 1000,
  cacheTtl: 0,
  debug: (msg) => console.log("[DEBUG]", msg),
  minInterval: 500,
});

Method List

Properties & Control

Method	Returns	Description
`ready()`	`Promise<void>`	Resolves when server IP is resolved (CFX.re). No-op for IP:PORT
`clearCache()`	`void`	Clear cached `info.json` to force re-fetch
`playerCount`	`number`	Sync getter — cached count from last `getPlayers()`/`getPlayersAll()`/`getServer()`
`getIp()`	`string`	Resolved server IP:PORT (sync)

Data Methods

Method	Returns	Throws	Description
`getServerStatus()`	`Promise<boolean>`	No	Server online status
`getServer()`	`Promise<ServerInfo>`	Yes	Full server info from `info.json`
`getServerName()`	`Promise<string>`	Yes	Server name (color codes stripped)
`getServerDesc()`	`Promise<string>`	Yes	Server description
`getPlayers()`	`Promise<number>`	Yes	Number of players online
`getPlayersAll()`	`Promise<Player[]>`	Yes	All players with name, ping, identifiers
`getPlayer(query)`	`Promise<Player \| null>`	Yes	Search by id (number), name substring, or identifier
`getMaxPlayers()`	`Promise<number>`	Yes	Max player slots
`getResources()`	`Promise<string[]>`	Yes	Resource names
`getTags()`	`Promise<string>`	Yes	Server tags (comma-separated)
`getOnesync()`	`Promise<boolean>`	Yes	OneSync enabled
`getLocale()`	`Promise<string>`	Yes	Server locale (e.g. `id-ID`)
`getGamename()`	`Promise<string>`	Yes	Game name (e.g. `gta5`)
`getSteamTicket()`	`Promise<boolean>`	Yes	Steam ticket required
`getGameBuild()`	`Promise<number>`	Yes	Enforced game build
`getEnhancedHostSupport()`	`Promise<boolean>`	Yes	Enhanced host support
`getLicenseKeyToken()`	`Promise<string>`	Yes	License key token
`getScriptHookAllowed()`	`Promise<boolean>`	Yes	ScriptHook allowed
`getEndpoint()`	`Promise<string \| null>`	Yes	Dynamic server endpoint
`getIcon()`	`Promise<string>`	Yes	Server icon (base64 data URI)
`getUpvotePower()`	`Promise<number>`	Yes	Server upvote power
`getBurstPower()`	`Promise<number>`	Yes	Server burst power (boost)
`getClients()`	`Promise<number>`	Yes	Player count via lightweight `dynamic.json`. Falls back to `players.json`
`getHostname()`	`Promise<string>`	Yes	Raw hostname from `dynamic.json`. Falls back to `sv_projectName`
`getGametype()`	`Promise<string>`	Yes	Game type from `dynamic.json` (Roleplay, Freeroam, etc.)
`getMapname()`	`Promise<string>`	Yes	Map name from `dynamic.json` (San Andreas, etc.)
`getSvMaxclients()`	`Promise<number>`	Yes	Max clients from `dynamic.json`. Falls back to info.json
`getOwnerName()`	`Promise<string>`	Yes	Owner display name
`getOwnerProfile()`	`Promise<string>`	Yes	Owner forum profile URL
`getOwnerAvatar()`	`Promise<string>`	Yes	Owner avatar URL

Player Search

// By ID (number — exact match)
const player = await server.getPlayer(42);

// By name (string — case-insensitive substring)
const player = await server.getPlayer("playername");

// By identifier (string starting with license:/steam:/discord: — exact match)
const player = await server.getPlayer("license:abc123def");

Watch (Polling)

const handle = server.watch(5000, async (s) => {
  const count = await s.getPlayers();
  console.log(`Players: ${count} (cached: ${s.playerCount})`);
});

// Later: handle.stop();

Multi-Server

const result = await FiveM.multi([
  { cfxre: "1.2.3.4:30120" },
  { cfxre: "cfx.re/join/code1" },
  { cfxre: "cfx.re/join/code2", options: { timeout: 10000 } },
]);

console.log("All servers:", result.servers.length);

const statuses = await result.getAllStatus();
// Map<string, boolean> — IP → online/offline

const counts = await result.getAllPlayers();
// Map<string, number> — IP → player count (-1 if failed)

const online = await result.getOnlineServers();
// Server[] — only online servers

Server Search

Search the global FiveM server list from Cfx.re. By default returns 20 results — pass 0 for unlimited. Stops decoding early when enough matches are found.

import {
  searchServers, getAllServers, getServerByEndpoint, getServersByLocale,
  getIconUrl, isPrivateServer,
} from "fivem-server-api";

// Get all servers (default 30s timeout)
const all = await getAllServers();
console.log(`Total: ${all.length} servers`);

// Filter by locale (default 20 results)
const idServers = await getServersByLocale("id-ID");
console.log(`Indonesian servers: ${idServers.length}`);

// Search with multiple filters + pagination
const page1 = await searchServers(
  { query: "roleplay", gametype: "roleplay", locale: "id-ID" },
  10,    // limit (default: 20, pass 0 for unlimited)
  30000, // timeout ms (default: 30000)
  0,     // offset (default: 0)
);
const page2 = await searchServers(
  { query: "roleplay" },
  10,     // 10 per page
  30000,
  10,     // skip first 10
);

// Find a specific server by endpoint ID
const server = await getServerByEndpoint("3lamjz");
if (server) {
  console.log(server.Data.hostname);
  console.log(`${server.Data.clients}/${server.Data.svMaxclients} players`);

  // Icon URL — null if iconVersion is 0 (no custom icon)
  const iconUrl = getIconUrl(server);
  // => "https://frontend.cfx-services.net/api/servers/icon/3lamjz/5.png"

  // Check if server is private
  if (isPrivateServer(server)) {
    console.log("Private server — IP hidden");
  }
}

SearchFilter

Field	Type	Description
`query`	`string`	Searches across hostname, sv_projectName, tags, gametype, mapname (case-insensitive partial)
`locale`	`string`	Exact locale match (e.g. `"en-US"`, `"id-ID"`)
`hostname`	`string`	Partial match on server hostname and sv_projectName
`gametype`	`string`	Partial match on game type (e.g. `"roleplay"`, `"freeroam"`)
`mapname`	`string`	Partial match on map name (e.g. `"San Andreas"`)
`tag`	`string`	Partial match on server tags

SearchResult

interface SearchResult {
  EndPoint: string;        // Unique server ID (e.g. "3lamjz")
  Data: {
    hostname: string;      // Server display name
    clients: number;       // Current players
    svMaxclients: number;  // Max player slots
    gametype: string;      // e.g. "Roleplay", "Freeroam"
    mapname: string;       // e.g. "San Andreas"
    iconVersion: number;   // Icon version (0 = no custom icon)
    vars: Record<string, string>;  // locale, tags, sv_projectName, etc.
    resources: string[];
    players: SearchPlayer[];
    connectEndPoints: string[];     // IP:PORT or "private-placeholder.cfx.re" for private servers
    upvotePower: number;
    burstPower: number;
    // ... and more
  };
}

Icon & Private Helpers

import { getIconUrl, isPrivateServer } from "fivem-server-api";

// getIconUrl(server) => string | null
// Returns Cfx.re CDN icon URL, or null if iconVersion is 0
const icon = getIconUrl(result);
if (icon) {
  // https://frontend.cfx-services.net/api/servers/icon/oax6pvv/2006463867.png
}

// isPrivateServer(server) => boolean
// True if connectEndPoints contains "private-placeholder.cfx.re"
if (isPrivateServer(result)) {
  console.log("This server hides its IP");
}

TypeScript Types

interface ServerOptions {
  timeout?: number;
  retries?: number;
  retryDelay?: number;
  cacheTtl?: number;
  debug?: boolean | ((message: string) => void);
  minInterval?: number;
}

interface Player {
  id: number;
  identifiers: string[];
  name: string;
  ping: number;
}

interface ServerInfo {
  server: string;
  icon: string;
  resources: string[];
  players: Player[];
  vars: Record<string, string>;
  [key: string]: unknown;
}

interface DynamicInfo {
  clients: number;
  gametype: string;
  hostname: string;
  mapname: string;
  sv_maxclients: string;
  iv: string;
}

interface WatchHandle {
  stop(): void;
}

interface MultiServerConfig {
  cfxre: string;
  options?: ServerOptions;
}

All types are exported:

import type {
  Player, ServerInfo, DynamicInfo, ServerOptions,
  WatchHandle, MultiServerConfig,
  SearchFilter, SearchResult, SearchPlayer, SearchServerData,
} from "fivem-server-api";

All utility functions are exported:

import {
  searchServers, getAllServers, getServerByEndpoint, getServersByLocale,
  getIconUrl, isPrivateServer,
} from "fivem-server-api";

Migrating from v1.x

v1.x	v2.x
Returns `errmsg` on error	Throws `FiveMError` — use `try/catch`
Needs `setTimeout` before use	No delay — internal ready state
`console.log` on connect	Silent by default (use `debug` option)
`getServerStatus()` → object	`getServerStatus()` → `boolean`
No caching	`info.json` cached with configurable TTL
Duplicate `index.cjs` / `index.mjs`	Single TypeScript source
—	`ready()`, `clearCache()`, `playerCount`, `getPlayer()`
—	`watch()`, `Server.multi()`, CLI tool

// v1.x
const FiveM = require("fivem-server-api");
const server = new FiveM("1.2.3.4:30120", { timeout: 5000, errmsg: "Error" });
setTimeout(async () => {
  const status = await server.getServerStatus();
  if (status.online) { /* ... */ }
}, 2000);

// v2.x
import FiveM from "fivem-server-api";
const server = new FiveM("1.2.3.4:30120", { timeout: 5000 });
await server.ready(); // optional — methods auto-wait
const online = await server.getServerStatus();
if (online) { /* ... */ }

License

ISC

Keywords

fivem gta5 gta-v cfx.re server-list server-search server-info server-status server-icon player-count player-list typescript cli pagination roleplay game-server