fivem-server-api
Version:
Query FiveM server info, player list, player count, resources, tags, locale, OneSync, game build, and more from any server IP or CFX.re URL. Also includes global server search with filtering, pagination, icon URL helper, private server detection, caching,
90 lines (89 loc) • 3.28 kB
TypeScript
export interface SearchFilter {
query?: string;
locale?: string;
hostname?: string;
gametype?: string;
mapname?: string;
tag?: string;
}
export interface SearchPlayer {
name: string;
identifiers: string[];
endpoint: string;
ping: number;
id: number;
}
export interface SearchServerData {
svMaxclients: number;
clients: number;
protocol: number;
hostname: string;
gametype: string;
mapname: string;
resources: string[];
server: string;
players: SearchPlayer[];
iconVersion: number;
vars: Record<string, string>;
enhancedHostSupport: boolean;
upvotePower: number;
burstPower: number;
connectEndPoints: string[];
}
export interface SearchResult {
EndPoint: string;
Data: SearchServerData;
}
/**
* Search FiveM servers from the Cfx.re global server list.
* Stops decoding early when enough matching results are found.
*
* @param filter - Filter criteria (locale, hostname, gametype, mapname, tag, query)
* @param limit - Maximum number of results to return (default: 20, pass 0 for unlimited)
* @param timeout - Request timeout in ms (default: 30000)
* @param offset - Number of results to skip before collecting (for pagination)
* @returns Matching servers (resolved to plain objects)
*/
export declare function searchServers(filter?: SearchFilter, limit?: number, timeout?: number, offset?: number): Promise<SearchResult[]>;
/**
* Get a single server by its Cfx.re endpoint ID.
*
* @param endpoint - The server's unique endpoint ID (e.g. "3lamjz")
* @param timeout - Request timeout in ms
* @returns The matching server or null if not found
*/
export declare function getServerByEndpoint(endpoint: string, timeout?: number): Promise<SearchResult | null>;
/**
* Get all servers from the Cfx.re global server list.
*
* @param timeout - Request timeout in ms (default: 30000)
* @returns All servers currently listed
*/
export declare function getAllServers(timeout?: number): Promise<SearchResult[]>;
/**
* Get servers filtered by locale (e.g. "en-US", "de-DE").
*
* @param locale - The locale code to match
* @param timeout - Request timeout in ms
* @param offset - Number of results to skip (for pagination)
* @returns Servers matching the given locale (default: first 20)
*/
export declare function getServersByLocale(locale: string, timeout?: number, offset?: number): Promise<SearchResult[]>;
/**
* Build the icon URL for a server from the Cfx.re CDN.
* Returns null when iconVersion is 0 (no custom icon set).
*
* @param endpointOrResult - Either a server endpoint ID (string) or a full SearchResult object
* @param iconVersion - The icon version number (only needed if first arg is a string)
* @returns The full icon image URL (PNG) or null if no icon available
*
* @example
* const url = getIconUrl(result); // => "https://..." or null
* const url = getIconUrl("3lamjz", 5); // => "https://..."
*/
export declare function getIconUrl(endpointOrResult: string | SearchResult, iconVersion?: number): string | null;
/**
* Check if a server is private (IP hidden by Cfx.re).
* Private servers have "private-placeholder.cfx.re" in connectEndPoints.
*/
export declare function isPrivateServer(result: SearchResult): boolean;