@sc-db/sdk

Typed TypeScript client for the SCDB API — open, free data for Star Citizen, derived 100% from the game files (DataForge + the Data.p4k archive): ships, items, FPS gear, missions & contracts, crafting blueprints, the 3D starmap, and per-body mining tables.

The API is public and read-only — no API key, no auth. Types are generated from the API's OpenAPI spec, so the client always matches the live server.

Install

npm i @sc-db/sdk

Usage

import { createScdb } from "@sc-db/sdk";

const scdb = createScdb();              // defaults to https://api.sc-db.fr

// ships
const ships = await scdb.ships({ name: "gladius" });
const ship = await scdb.ship(guid);     // detail + default loadout

// items / FPS gear (filter by type, size, manufacturer…)
const rifles = await scdb.items({ category: "fps_weapon", size: 3 });

// mining — what's mineable where, with probabilities
const cellin = await scdb.miningBody("Stanton2a");
const spots = await scdb.miningProspect(["Quantainium", "Taranite"]);  // best places

// starmap
const systems = await scdb.starmapSystems();
const crusader = await scdb.starmapObject("Stanton2");

Point it at your own instance with createScdb({ baseUrl: "https://…" }).

What you can query

| Area | Methods | | --- | --- | | Meta | stats · meta · types | | Records (raw + graph) | records · record · refs · refsIn | | Ships | ships · ship | | Items | items · itemFacets · item · compareItems | | Missions & contracts | missions · mission · contracts · contract · contractTypes · contractFactions | | Blueprints | blueprints · blueprint · blueprintCategories | | Starmap & locations | starmap · starmapObject · starmapSystems · locations · locationTypes | | Mining | miningBodies · miningBody · miningElements · miningDeposits · miningProspect | | Localization | localization · localizationKey |

Every method is fully typed (request + response). Errors throw ScdbError. scdb.raw exposes the underlying openapi-fetch client as an escape hatch.

Caching

GET responses are cached in memory. The data only changes once per game patch, so the cache never expires by time — instead it's keyed on the build version and refreshes automatically when the API ships a new patch:

await scdb.checkVersion();   // poll for a new patch; flushes the cache if it changed
scdb.clearCache();           // drop everything manually
createScdb({ cache: false }); // opt out entirely

Rate limit

The public API is rate-limited per IP (120 requests / 60s by default). On 429 the response carries Retry-After. Please cache responses (the SDK does) rather than hammering it — and use this client instead of scraping the website.

Links

• API reference (Swagger): https://api.sc-db.fr/docs
• OpenAPI spec: https://api.sc-db.fr/openapi.json
• Website: https://sc-db.fr
• Source: https://github.com/Romain-Boudot/sc-db

License

MIT · Unofficial project, not affiliated with Cloud Imperium Games. Data belongs to CIG; this only re-exposes what ships in the game client.