CitizenHQ API.
Eine kostenlose, öffentliche API für Star-Citizen-Daten, nur lesend. Handel und Börse, Schiffe, Blueprints, Mining, Missionen und Orte. Dieselben Daten, die auch CitizenHQ antreiben.
Wie wir die Quellen verbinden
Kurz: Wir führen Preise NICHT zusammen. UEX bleibt die Grundlage, SC Trade Tools ergänzt und widerspricht. Mehr nicht.
| Feld | Quelle | Art der Zahl |
|---|---|---|
| buy, sell, scuBuy, scuSell, updatedAt | UEX Corp | Die letzte Meldung eines Spielers, mit Zeitpunkt. Kann Stunden oder Wochen alt sein. |
| stockScScu/stockMaxScu, demandScScu/demandMaxScu, scBuyStock/scBuyMax, scSellStock/scSellMax | SC Trade Tools | Bestand und Kapazität des Ladens, beide von SC Trade Tools. Nur miteinander zu verrechnen: die Kapazität ändert sich praktisch nie, der Bestand mit jedem Abruf (stockScAt/scFetchedAt). |
| avgProfitPerScu | SC Trade Tools | Universumsweiter Durchschnitt je Ware, stündlich neu. Kein Ortsbezug. |
| scFetchedAt | wir | Wann WIR abgerufen haben, nicht wann gemeldet wurde. |
Warum wir Preise nicht zusammenführen
Es sind zwei verschiedene Arten von Zahl. UEX liefert die letzte Spielermeldung mit Datum. SC Trade Tools liefert einen zeitgewichteten gleitenden Median über viele Meldungen, stündlich neu gerechnet, und ausdrücklich ohne Meldezeitpunkt, weil der in ihrem Modell keine Bedeutung hat. Eine Regel „die jüngere gewinnt“ ließe sich darauf gar nicht anwenden. Beide Werte in eine Spalte zu schreiben wäre erfundene Genauigkeit. Deshalb stehen sie getrennt, jeder mit seiner Herkunft.
Was wir stattdessen tun
- Füllstand, streng innerhalb EINER Quelle: Der Prozentsatz entsteht aus
stockScScu÷stockMaxScu, beide von SC Trade Tools. Die UEX-MengestockScusteht getrennt daneben, mit ihrem eigenen Datum. Diese beiden NICHT ineinander zu rechnen ist der Punkt: UEX liefert eine Einzelmeldung, SC Trade einen gleitenden Median. Wir hatten das kurzzeitig vermischt und zeigten Füllstände über 100 %. - Widerspruch kennzeichnen: Weicht unsere Marge stark von
avgProfitPerScuab, weist die Oberfläche darauf hin. Wir behaupten nicht, wer recht hat.Der Hinweis sagt nur, dass es sich lohnt, vor Ort nachzusehen. - Nichts überschreiben: Kein UEX-Preis wird durch einen fremden ersetzt. Fällt die Zweitquelle aus, fehlen Kapazität und Hinweis, die Preise bleiben unverändert.
Wenn Felder fehlen
null heißt „liegt nicht vor“, nicht „ist null“. Für 11 unserer 135 Handels-Terminals gibt es bei SC Trade Tools kein Gegenstück (teils führen sie den Ort nicht, teils fassen sie zwei unserer Terminals zu einem Shop zusammen). Dort bleiben die sc-Felder dauerhaft leer. Ausführlich unter /datenquellen.
Quickstart
Base URL
https://citizenhq.space/api/v1
curl
curl https://citizenhq.space/api/v1/trade/market
JavaScript (fetch)
fetch("https://citizenhq.space/api/v1/trade/market")
.then((res) => res.json())
.then((data) => console.log(data));Nur GET
Read-only
60 / min
Rate-Limit
Aktiv
CORS
Nicht nötig
API-Key
Endpunkt-Referenz
Handel / Börse
| Endpoint | Beschreibung |
|---|---|
| GET/trade/market | Live-Markt-Board: Preis, 1h/24h-Änderung, Sparkline, Volumen je Ware |
| GET/trade/overview | Handels-Übersicht |
| GET/trade/board | Handels-Board |
| GET/trade/commodity-list | Liste aller handelbaren Waren |
| GET/trade/terminal/:id | Alles an EINEM Ort: was dieses Terminal kauft und was es annimmt, je Zeile mit Preis, gemeldeter Menge (UEX) und dem Alter dieser Meldung. Aus der Zweitquelle SC Trade Tools (#238): scScu/maxScu = Bestand UND Kapazitaet des Ladens (der Fuellstand entsteht NUR aus diesem Paar, nie aus scu/maxScu, denn scu ist UEX), sowie scAt, unser Abrufzeitpunkt. Am Terminal selbst zusaetzlich securityLevel (1-5, #241), freightElevator und autoLoad. |
| GET/trade/commodity/:id | Waren-Detail inkl. Preise je Terminal. Je Zeile aus UEX: priceBuy/priceSell, scuBuy/scuSell/scuSellStock, statusBuy/statusSell (grobe Stufe 0–7) und updatedAt (Zeitpunkt der Spielermeldung, Unix-Sekunden). Aus der Zweitquelle SC Trade Tools (#238) zusätzlich scBuyStock/scBuyMax und scSellStock/scSellMax (Bestand UND Kapazität, woraus sich erst ein Füllstand ergibt), sowie scFetchedAt: UNSER Abrufzeitpunkt, nicht deren Meldedatum (sie führen keines, siehe „Wie wir die Quellen verbinden“). |
| GET/trade/history?commodity=&terminal= | Preisverlauf einer Ware an einem Terminal |
| GET/trade/chart?commodity= | Chart-Daten für eine Ware |
| GET/trade/movers | Gewinner und Verlierer, die größten Preisbewegungen |
| GET/trade/routes | Top-Handelsrouten |
| GET/trade/trader-routes?cargo=&budget=&origin=&dest=&originTerminal=&destTerminal=&sort=&roundtrip=&onward=&freightonly=&autoloadonly=&autoload=&maxage=&minstock=&commodity=&limit=&illegal=&maxbox= | Profit-Routen-Rechner mit Rückroute & Anschlussfracht. Jede Route trägt from/toFreightElevator (physischer Fracht-Aufzug, Handladen) UND from/toAutoLoad (ATC-Auto-Load am Cargo-Deck, nicht dasselbe: ein Boden-Outpost hat oft einen Aufzug, aber kein Auto-Load). freightonly=1 = nur Routen mit Aufzug an beiden Terminals; autoloadonly=1 = nur Routen mit Auto-Load an beiden Terminals; autoload=1 lockert die gemeldete Nachfrage. Jede Route trägt zudem distanceGm (In-System-Luftlinie in Gigametern) + crossSystem (Sprung nötig). Frische & Bestand (#237): maxage=<Stunden> nimmt nur Orte mit einer Meldung aus diesem Zeitraum, minstock=<SCU> nur Orte, die mindestens so viel Vorrat bzw. Bedarf melden (bei autoload=1 gilt das nur für den Kaufort). Beide Filter greifen bei der Auswahl des Ortes, verwerfen also nicht die ganze Ware. Je Bein: buyAt/sellAt (Zeitpunkt der Meldung, Unix-Sekunden), stockScu (Vorrat am Kaufort) und demandScu (gemeldeter Bedarf am Verkaufsort, null = keiner gemeldet). Waren-Modus (#242): commodity=<uexId> liefert ALLE lohnenden Kauf-Verkauf-Paarungen DIESER einen Ware (je Ortspaar die beste, Standard-Deckel 60, per limit= bis 200) statt der einen besten Route je Ware. Schmuggelware & Ladbarkeit (#242): illegal=hide laesst illegale Waren weg, illegal=only zeigt nur sie (jede Route traegt illegal); maxbox=<SCU> nimmt nur Kauforte, deren KLEINSTE angebotene Kiste das Schiff laden kann. Aus der Zweitquelle SC Trade Tools (#238): stockScScu/stockMaxScu und demandScScu/demandMaxScu = Bestand UND Kapazität der beiden Orte; der Füllstand entsteht NUR aus diesem Paar, niemals aus stockScu/demandScu (das ist UEX, eine andere Quelle mit anderer Bedeutung); stockScAt/demandScAt = unser Abrufzeitpunkt dieser Zahlen; alternatives[] = bis zu 4 andere Waren, die auf DERSELBEN Strecke handelbar sind (commodityId, commodity, buy, sell, marginPerScu, illegal, stockScu), fuer den Fall, dass das Regal am Kaufort leer ist (#251), nach Marge je SCU sortiert; fromSecurity/toSecurity = Sicherheitsstufe 1-5 der beiden Orte (#241); avgProfitPerScu = universumsweiter Durchschnittsgewinn je SCU dieser Ware. Letzterer ist ein ROHWERT ohne Urteil, siehe „Wie wir die Quellen verbinden“. sort= kennt profit (Vorgabe), roi, margin, fresh und pergm; pergm ist Gewinn/(Strecke+10 Gm Grundaufwand je Fuhre), Routen ueber Systemgrenzen haben keine Luftlinie und stehen am Ende. |
| GET/trade/best-buyer?commodity=&qty= | Bester Abnehmer für eine Ware & Menge |
| GET/trade/terminals-list | Liste aller Handels-Terminals inkl. freightElevator (physischer Fracht-Aufzug), autoLoad (ATC-Auto-Load am Cargo-Deck), loadingDock, cargoCenter und maxContainerSize. Dazu x/y/z in Metern (Nullpunkt = Stern des Systems), sofern die Position bekannt ist. aktuell 624 von 826 Terminals; sonst null. Siehe /positions für die Einschränkungen. |
| GET/trade/cargo-ships | Liste der Cargo-Schiffe |
| GET/trade/systems | Systeme mit Handelsdaten |
Schiffe
| Endpoint | Beschreibung |
|---|---|
| GET/ships?q=&manufacturer=&role=&size= | Schiffs-Suche mit Filtern |
| GET/ships/manufacturers | Liste der Hersteller |
| GET/ships/roles | Liste der Schiffsrollen |
| GET/ships/:slug | Schiffs-Detail inkl. Kauf-/Miet-Terminals und der ab Werk verbauten Ausrüstung (loadout: je Bauteil Typ, Grad, Größe, Slot-Größe, Stückzahl und Hardpoints; blueprintUuid wenn craftbar). Das ältere Feld craftable bleibt als Teilmenge erhalten. |
Blueprints
| Endpoint | Beschreibung |
|---|---|
| GET/blueprints?q=&type=&limit=&offset= | Blueprint-Suche mit Filtern. Seitenweise: limit (Standard 100, max. 2000, der ganze Bestand passt damit in einen Aufruf) und offset; die Gesamtzahl steht im Kopf X-Total-Count |
| GET/blueprints/types | Liste der Blueprint-Typen |
| GET/blueprints/:uuid | Blueprint-Detail |
Mining
| Endpoint | Beschreibung |
|---|---|
| GET/mining/ores | Erz-Datenbank (Name, Slug, Roh-/Refined-Verkaufspreis, Refine-Uplift)Beispiel-Response ▾[
{
"name": "Iron",
"slug": "iron",
"tier": "common",
"rarity": "Häufig",
"rawSell": 1000, // aUEC/SCU roh (falls verkaufbar)
"refinedSell": 3600, // aUEC/SCU raffiniert
"refineUplift": 260 // % Mehrwert durch Raffinieren
}
] |
| GET/mining/ores/:slug | Erz-Detail: Physik, Quality, Vorkommen |
| GET/mining/board | Mining-Board: je Erz Roh- & Refined-Bestpreis + TerminalBeispiel-Response ▾[
{
"oreId": 45,
"ore": "Iron (Ore)",
"rawSell": null, // Roherz meist nicht verkaufbar
"rawTerminal": null,
"refinedName": "Iron",
"refinedSell": 3600, // aUEC/SCU
"refinedTerminal": "TDD - Area18",
"refinedSystem": "Stanton"
}
] |
| GET/mining/methods | Raffinerie-Verfahren mit Yield/Kosten/Speed-Rating (1=niedrig … 3=hoch)Beispiel-Response ▾[
{
"uexId": 2,
"name": "Dinyx Solventation",
"code": "DIN",
"ratingYield": 3, // Ausbeute (höher = mehr Material)
"ratingCost": 1, // Kosten (niedriger = günstiger)
"ratingSpeed": 1 // Tempo (höher = schneller)
}
] |
| GET/mining/yields/:id | Yield-Modifikator je Refinery-Standort für ein Erz (:id = commodityId, z.B. 45 = Iron)Beispiel-Response ▾// GET /mining/yields/45
[
{
"terminalName": "Refinement Center - Levski",
"system": "Stanton",
"value": 8.00 // Yield-Modifikator in % (+ = besser, − = schlechter)
},
{
"terminalName": "Refinement Processing - CRU-L1",
"system": "Stanton",
"value": 2.00
}
] |
Missionen
| Endpoint | Beschreibung |
|---|---|
| GET/missions?... | Missions-Suche mit Filtern |
| GET/missions/filters | Verfügbare Filter-Werte |
| GET/missions/:uuid | Missions-Detail |
| GET/missions/:uuid/chain | Missions-Kette der Mission |
| GET/chains | Liste aller Missions-Ketten |
Orte
| Endpoint | Beschreibung |
|---|---|
| GET/locations?q=&system=&service= | Orte und Stationen: Hierarchie (System → Planet/Mond → Ort) UND x/y/z in Metern, sofern die Position bekannt ist; sonst null. Damit lässt sich eine Sammelroute über Lagerorte rechnen, nicht nur über Handelsterminals. Nullpunkt und Genauigkeit wie bei /positions beschrieben. |
| GET/locations/systems | Systeme mit Orten |
| GET/positions?system=&type=&q= | Starmap-Positionen mit echten x/y/z in METERN, die Grundlage für Distanz- und Routenberechnung. Nullpunkt ist der Stern des jeweiligen Systems, Distanzen sind daher NUR INNERHALB eines Systems vergleichbar (systemübergreifend fliegt man Sprungpunkte, keine Luftlinie). Standbild aus den Spieldateien wie die Starmap im Spiel. Planeten kreisen, für die Reihenfolge einer Route reicht es, als exakte kürzeste Strecke taugt es nicht. Filter: system (stanton/pyro/nyx), type (Planet, Moon, …), q (Namensteil).Beispiel-Response ▾[
{
"uuid": "e1b7f2c0-…",
"name": "ArcCorp",
"type": "Planet",
"system": "stanton",
"parentUuid": "8a4c…",
"x": 18590000000,
"y": -22150000000,
"z": 0,
"qtValid": true
}
]
// Abstand zweier Orte IM SELBEN System (Meter):
// d = sqrt((x1-x2)^2 + (y1-y2)^2 + (z1-z2)^2)
// 1 Gm = 1e9 m |
| GET/stations | Liste der Stationen |
| GET/stations/detail | Stations-Detail |
| GET/systems | Liste der Sternsysteme |
| GET/systems/:id | System-Detail |
| GET/fuel-prices | Treibstoff-Preise je Terminal |
Items
| Endpoint | Beschreibung |
|---|---|
| GET/items?q=&type=&category=&page=&pageSize= | Item-/Komponenten-Suche mit Filtern, serverseitig paginiert (Default 50/Seite, max. 100). Antwort: { items, total, page, pageSize }, nicht mehr eine nackte Liste. category ist eine grobe Gruppe (weapons/weapon_mods/armor/clothing/ship_components/consumables/misc), type der genaue scunpacked-Typ. |
| GET/items/types | Liste der Item-Typen |
| GET/items/:uuid | Item-Detail |
| GET/item-shops | Liste der Item-Shops |
| GET/item-shops/:id | Item-Shop-Detail |
Meta
| Endpoint | Beschreibung |
|---|---|
| GET/health | Status + letzte Sync-Zeiten |
| GET/stats | Globale Statistiken |
| GET/manufacturers | Liste aller Hersteller |
Nutzungsbedingungen & Attribution
Die API ist read-only (nur GET) und unterliegt einem Fair-Use-Limit von 60 Anfragen pro Minute pro IP-Adresse (Burst 30). Bei Überschreitung antwortet die API mit HTTP 429.
Wenn du Daten aus der API anzeigst oder weiterverarbeitest, gib bitte die Quelle an: "Daten via UEX Corp, SC Trade Tools, scunpacked & Star Citizen Wiki". Antworten tragen dazu einen X-Data-Source-Header.
Alle Daten kommen so, wie sie sind. Live-Werte im Spiel können von den hier gelieferten Daten abweichen. Es besteht keine Verbindung zu Cloud Imperium Games oder Roberts Space Industries. Star Citizen® ist eine Marke von CIG.
▢ Daten von UEX Corp, SC Trade Tools und scunpacked. Preise stammen aus Spielermeldungen und können vom Live-Server abweichen. Woher kommt welche Zahl?