Erste Schritte

Migrationsleitfaden

Migriere von SteamApis v1 auf v2. Aktualisierte Authentifizierung, Response-Envelope, Steam-User-Feldnamen und eine deutlich größere Endpoint-Oberfläche.

Migration von v1 auf v2

Dieser Leitfaden beschreibt die Änderungen, die du beim Upgrade von SteamApis API v1 auf v2 vornehmen musst. v2 ergänzt neue Kategorien (Konto, Market Data), reorganisiert Steam-User- und App-Endpoints und führt einen einheitlichen Response-Envelope ein.

Authentifizierung

v1 hat den API-Key als Query-Parameter übergeben, typischerweise api_key oder key:

GET /steam/profile/76561198038526790?api_key=YOUR_KEY

v2 übergibt den API-Key über den Request-Header x-api-key (empfohlen) oder den Query-Parameter ?key= (weiterhin unterstützt):

index.js

fetch('https://api.steamapis.com/v2/steam/users/76561198038526790', {
  headers: { 'x-api-key': 'YOUR_KEY' }
})

Der Header wird empfohlen, weil der Key so nicht in Server-Logs, Browser-Historie oder Referer-Headern landet.

Response-Envelope

v1-Endpoints lieferten die Daten direkt auf oberster Ebene zurück:

{
  "steamid": "76561198038526790",
  "personaname": "PEPZ"
}

v2 packt jede Antwort in einen Standard-Envelope. Die genaue Form hängt davon ab, ob der Endpoint eine einzelne Ressource oder eine paginierte Liste zurückgibt:

Einzelne Ressource

{
  "success": true,
  "result": { "steamID": "76561198038526790", "nickname": "PEPZ" }
}

Paginierte Liste

{
  "success": true,
  "results": [ { /* ... */ } ],
  "cursor": "6789abcdef012345",
  "hasMore": true
}

Fehler nutzen denselben Envelope mit success: false:

Fehler

{
  "success": false,
  "error": { "name": "NOT_FOUND", "message": "User not found", "meta": {} }
}

Um an die Daten zu kommen, verwende data.result (einzelne Ressource) oder data.results (Liste), statt die oberste Ebene direkt zu lesen.

Ein paar frühe v2-Endpoint-Dokus verweisen noch auf den alten response-Key statt result. Behandle das als Drift — der maßgebliche Envelope ist { success, result } / { success, results, cursor, hasMore }.

Umbenennungen bei Steam-User-Feldern

Der v2-User-Endpoint liefert dieselben zugrunde liegenden Steam-Daten zurück, aber mit camelCase-Feldnamen und einem verschachtelten avatar-Objekt. Falls du User-Responses parst, aktualisiere deine Typen:

v1-Feld	v2-Feld	Hinweise
`steamid`	`steamID`	Umbenannt.
`personaname`	`nickname`	Umbenannt.
`profileurl`	`url`	Umbenannt.
`personastate`	`personaState`	camelCase.
`personastateflags`	`personaStateFlags`	camelCase.
`primaryclanid`	`primaryGroupID`	Umbenannt.
`timecreated`	`createdTimestamp`	Umbenannt.
`loccountrycode`	`countryCode`	Umbenannt.
`commentpermission` (number)	`allowsComments` (boolean)	Typänderung.
`communityvisibilitystate` (enum)	`visible` (boolean)	Auf einen Boolean reduziert.
`avatar`, `avatarmedium`, `avatarfull`, `avatarhash`	`avatar.small`, `avatar.medium`, `avatar.large`, `avatar.hash`	Flache Felder in ein verschachteltes `avatar`-Objekt verschoben.
`profilestate`	—	Entfernt.
—	`lastLogOffTimestamp`	Neu.

Steam-ID-Parameter

In v1 verlangten User-Endpoints eine SteamID64 (17-stellige numerische ID). In v2 akzeptiert der steamid-Parameter mehrere Steam-ID-Formate — SteamID64, SteamID, SteamID3 — und die API löst sie automatisch auf.

Endpoint-Mapping

Die folgenden Tabellen mappen jeden v1-Endpoint auf sein v2-Gegenstück, gruppiert nach Kategorie. Einträge mit „Neu in v2" haben keinen v1-Vorgänger.

Konto

v1-Endpoint	v2-Endpoint	Hinweise
—	`GET /v2/account`	Neu in v2. Liefert Balance, Overage-Konfiguration und Abo-Status pro Produkt mit Nutzung im aktuellen Zyklus.

Steam-User

v1-Endpoint	v2-Endpoint	Hinweise
`GET /steam/profile/{SteamID64}`	`GET /v2/steam/users/{steamid}`	Umbenannt. Auch die Feldnamen haben sich geändert — siehe Umbenennungen bei Steam-User-Feldern.
`GET /steam/profile/{SteamID64}/summary`	`GET /v2/steam/users/{steamid}` + `GET /v2/steam/users/{steamid}/badges`	Summary aufgeteilt. Kernprofil verschmilzt mit dem User-Endpoint; Badges haben ihren eigenen Endpoint.
`GET /steam/profile/{SteamID64}/games`	`GET /v2/steam/users/{steamid}/games`	Pfad geändert.
`GET /steam/profile/vanity/{VanityName}`	`GET /v2/steam/users/vanity/{vanityUrl}`	Pfad geändert.
`GET /steam/inventory/{SteamID64}/{AppId}/{ContextId}`	`GET /v2/steam/users/{steamid}/inventory/{appId}/{contextId}`	Pfad geändert (Inventory-Endpoint bleibt unter Steam-Usern).
—	`GET /v2/steam/users/{steamid}/bans`	Neu in v2. Dedizierter Ban-Status-Endpoint.
—	`GET /v2/steam/users/{steamid}/recently-played`	Neu in v2. In den letzten zwei Wochen gespielte Spiele mit Minuten pro Plattform.
—	`GET /v2/steam/users/{steamid}/achievements/{appid}`	Neu in v2. Pro-Spiel-Erfolge mit Freischalt-Zeitstempeln.
—	`GET /v2/steam/users/{steamid}/stats/{appid}`	Neu in v2. Pro-Spiel-Stats und freigeschaltete Erfolge.
—	`GET /v2/steam/users/{steamid}/friends`	Neu in v2. Freundesliste mit Freundschafts-Zeitstempeln.
—	`GET /v2/steam/users/{steamid}/groups`	Neu in v2. Gruppen, in denen der Benutzer Mitglied ist.

Steam-Apps

v1-Endpoint	v2-Endpoint	Hinweise
`GET /market/apps`	`GET /v2/steam/apps`	Umbenannt und umgebaut. Gibt eine paginierte Liste aller getrackten Steam-Apps zurück. Nutze `cursor` zur Paginierung.
`GET /market/app/{AppID}`	`GET /v2/steam/apps/{appId}`	Umbenannt. App-Details (Name, Typ, Last Modified usw.).
`GET /market/stats`	—	Kein direktes Gegenstück. Die nächstgelegenen Äquivalente sind `GET /v2/steam/apps/player-counts` und `GET /v2/steam/apps/store/rankings/{type}`.
—	`GET /v2/steam/apps/player-counts`	Neu in v2. Aktuelle Concurrent-Spielerzahlen pro App, paginiert.
—	`GET /v2/steam/apps/{appId}/changes`	Neu in v2. App-Changelog.
—	`GET /v2/steam/apps/{appId}/global-achievements`	Neu in v2. Globaler Freischalt-Prozentsatz pro Erfolg.
—	`GET /v2/steam/apps/{appId}/news`	Neu in v2. Aggregierte Community Announcements und externe Presseberichte.
—	`GET /v2/steam/apps/{appId}/schema`	Neu in v2. Vollständiges Stats-/Erfolg-Schema (Anzeigenamen, Beschreibungen, Icon-URLs).
—	`GET /v2/steam/apps/store/rankings/{type}`	Neu in v2. Steam-Store-Ranking-Listen (`popularnew`, `topsellers`, `popularcomingsoon`, `specials`, `trendingfree`, `mostplayed`).

Steam-Items

v1-Endpoint	v2-Endpoint	Hinweise
`GET /market/items/{AppID}`	`GET /v2/steam/items`	Umbenannt und umgebaut. Paginierte Liste aller getrackten Items; filter nach `appId`.
`GET /market/item/{AppID}/{MarketHashName}`	`GET /v2/steam/items/{appId}/{marketHashName}`	Pfad geändert. Einzelnes Item mit aktuellem Preis/Volumen.
`GET /market/items/{AppID}/histograms`	`GET /v2/steam/items/{itemId}/histograms`	Pfad geändert. Jetzt über die interne `itemId` statt `appId`.
`GET /market/items/{AppID}/descriptions`	—	Entfernt. Steam-Beschreibungen werden nicht mehr als eigenständiger Endpoint angeboten.
`GET /market/items/cards`	—	Entfernt. Kein direktes Gegenstück.
`GET /market/items/{AppID}/assetinfos`	—	Entfernt.
—	`GET /v2/steam/items/{itemId}/meta`	Neu in v2. Item-Metadaten (Typ, Tags, Beschreibung).
—	`GET /v2/steam/items/{itemId}/prices`	Neu in v2. Zeitreihe der Preishistorie des Items.
—	`GET /v2/steam/items/{itemId}/changes`	Neu in v2. Item-Changelog.
—	`GET /v2/steam/items/{appId}/list`	Neu in v2. Vorgefertigte Bulk-Preisliste für den gesamten Markt einer App (302-Redirect auf eine CDN-Datei).

Bilder

v1-Endpoint	v2-Endpoint	Hinweise
`GET /image/item/{AppID}/{MarketHashName}`	—	Entfernt. Konstruiere Steam-CDN-URLs direkt aus den Hash-Feldern des Items.
`GET /image/items/{AppID}`	—	Entfernt.

Market Data (Drittanbieter-Marktplätze)

Market Data ist eine neue Kategorie in v2. Sie aggregiert Preis-, Angebots-, Verkaufs- und Order-Book-Daten von 26 Drittanbieter-Marktplätzen — Funktionalität, die es in v1 nicht gab.

Market-Data-Endpoints werden unter https://marketplaceapi.steamapis.com/ gehostet — eine andere Base-URL als die Haupt-API (https://api.steamapis.com/).

Zusätzlich zu den REST-Endpoints unten stellt v2 auch einen Echtzeit-WebSocket-Offer-Stream bereit:

v1-Endpoint	v2-Endpoint	Protokoll	Hinweise
—	`wss://marketplaceapi.steamapis.com/ws/v2/offers`	WebSocket	Neu in v2. Pusht einzelne Marktplatz-Listings, sobald sie erkannt werden.

v1-Endpoint	v2-Endpoint	Hinweise
—	`GET /v2/marketplaces`	Neu in v2. Liste der unterstützten Marktplätze.
—	`GET /v2/items`	Neu in v2. Einzelnes Item über mehrere Marktplätze hinweg.
—	`GET /v2/items/search`	Neu in v2. Items nach Name suchen.
—	`GET /v2/items/compare`	Neu in v2. Ein Item über Marktplätze hinweg vergleichen.
—	`GET /v2/buy-orders`	Neu in v2.
—	`GET /v2/price-history`	Neu in v2. Preishistorie-Zeitreihe.
—	`GET /v2/sales`	Neu in v2. Aktuelle Verkäufe.

Zusammenfassung der Breaking Changes

Authentifizierung — API-Key vom api_key-Query-Parameter in den x-api-key-Request-Header umziehen (oder als ?key= belassen, wenn Header-Zugriff nicht praktikabel ist).
Response-Envelope — data.result (einzelne Ressource) oder data.results (Liste) auspacken, statt die oberste Ebene direkt zu lesen. Paginierte Listen-Responses enthalten zusätzlich cursor und hasMore.
Steam-User-Felder — steamid → steamID, personaname → nickname, profileurl → url und weitere umbenennen (siehe vollständige Tabelle oben). Flache Avatar-Felder in ein verschachteltes avatar-Objekt verschoben.
Endpoint-Pfade — Steam-User-Endpoints liegen jetzt unter /v2/steam/users/, App-Endpoints unter /v2/steam/apps/, Item-Endpoints unter /v2/steam/items/.
Steam-ID-Eingabe — v2 akzeptiert mehrere Steam-ID-Formate, nicht nur SteamID64.
Neue Endpoints — Konto, Bans, Recently Played, Achievements, Stats, Friends, Groups, Player Counts, Global Achievements, News, Schema, Store Rankings, Item-Liste und die komplette Market-Data-Kategorie.
Fehlerformat — Fehler liefern { "success": false, "error": { "name": "...", "message": "...", "meta": ... } } statt eines pro Endpoint abweichenden Formats.

Schnellstart

Starte mit SteamApis v2, indem du deinen API-Schlüssel holst und deine erste API-Anfrage machst.

Konto

Rufe deine API-Kontodetails ab, einschließlich Balance, Overage-Einstellungen und Produktabos mit Nutzungszählern.