swalib v1.0.2

Steam Web API Library

Version

Steam Web API Library is currently in version 1.0.2 per the Semantic Versioning standards.

Enhancements, features, and known issues are available in the Issues and Projects section of this respository.

Overview

Steam Web API Library is a JavaScript library that makes it easier to query data from the Steam Web API. The library reduces the amount of tedious API endpoint information you need to look up by doing that part for you. All you need to do is import the library and follow the usage guide below! The library can return data as a JSON, XML, or VDF (Valve Data Format) object.

1.0 | Quickstart Guide

Steam Web API Library is easy to install and use:

1. Run npm i swalib in your project root directory.

2. Ensure that you have your Steam Web API key in a .env file in the root directory of your project. Refer to example.env for naming requirements:

STEAM_KEY=XXXXXXXXXXXXXXXXXXXXXXX

Note: a future update will allow you to specify where your .env file is located. For the time being, it must be in the root directory of your project.

3. Import Steam Web API Library into your project:

import CallSteamAPI from "./SteamWebAPILibrary.js";

2.0 | Usage and Functionality

NOTE: Methods that request information from specific Steam users require that the user profiles be set to "public" visibility. Otherwise the server will return an undefined object.

2.1 | Option one (recommended) -- passing arguments as a destructured object in the async function.

Create an async function and call the library method you wish to use, then call the function as needed in your synchronous code.

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getNewsForApp({
    appid: "440",
    count: "4",
    format: "json",
    maxlength: "500",
  });

  return result;
}

myFunc();

Parameters that have a default value will maintain their default value whether or not they are included in your destructured object.

2.2 | Option two -- passing arguments in your function call directly.

Create an async function and call the library method you wish to use, then call the function as needed in your synchronous code. Arguments passed must match parameter order.

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc(appid, count, maxlength, format) {
  const result = await myAppVariable.getNewsForApp({
    appid,
    count,
    maxlength,
    format,
  });

  return result;
}

myFunc("440", "5", "500", "json");

2.3 | Querying for specific data endpoints

Steam Web API Library is capable of flexibly returning specific fields as well as returning the whole data object. By default, the full data object will be returned.

Specific data endpoint querying is only supported in JSON format. XML and VDF objects are returned as-in in their full scope and format.

The special specificData parameter determines whether the library will attempt to pull specific data information from the API. If specificData is specified with a valid endpoint, the library will return only that data:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getPlayerAchievements({
    appid: "440",
    steamid: "01234567890123456",
    specificData: "gameName", //Returns only the "gameName" field for the specified user and app
  });

  return result;
}

3.0 | Parameter Definitions

4.0 | Expected Return Values, Per Method

Below are the expected server responses for each available argument, per method.

"Code" refers to the HTTPS response from the Steam Web API server(s).

4.1 | getNewsForApp

4.2 | getGlobalAchievementPercentagesForApp

4.3 | getPlayerSummaries

4.4 | getFriendList

4.5 | getPlayerAchievements

4.6 | getUserStatsForGames

4.7 | getOwnedGames

4.8 | getRecentlyPlayedGames

5.0 | Methods

Steam Web API Library has a method for each available Steam Web API Method. The method names are identical to the official Steam Web API documentation. This section describes how to use each method within the context of the Steam Web API Library. The methods are presented in the same order as the official Steam Web API Library (as of the time of this writing).

5.1 | getNewsForApp

Description: Returns the latest news for a game, specified by its appID.

Arguments:

• appid : The appID of the game for which you want to retrieve news, as a string.

• count (optional) : The number of items to return, as a string or integer.

• maxlength (optional) : The maximum length of each entry in characters, as a string or integer.

• format (optional) : The format to return the data-- JSON (default), XML, or VDF.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getNewsForApp({
    appid: "413150", // Return info for the app "Stardew Valley"
    count: "10", // Return up to 10 results, if available
    maxlength: "500", // Return up to a maximum of 500 characters per result
  });

  // Do something with the result
}

myFunc();

5.2 | getGlobalAchievementPercentagesForApp

Description: Returns global achievements for the specific game in percentages.

Arguments:

• appid : The appID of the game for which you want to retrieve the global achievement stats.

• format (optional) : The format to return the data-- JSON (default), XML, or VDF.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getGlobalAchievementPercentagesForApp({
    gameid: "413150", // Returns data for the game Stardew Valley
  });

  // Do something with the result
}

myFunc();

5.3 | getPlayerSummaries

Description: Returns profile information for a list of Steam Player IDs. The profiles must have Public visibility to be retrieved successfully.

Arguments:

• steamids: A string of Steam Player IDs, separated by a comma. The API supports up to 100.

• format (optional) : The format to return the data-- JSON (default), XML, or VDF.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getPlayerSummaries({
    steamids:
      "76561197960435530, 76561197960435531, 76561197960435532, 76561197960435533", // Return info for the specified Steam IDs
  });

  // Do something with the result
}

myFunc();

5.4 | getFriendList

Description: Returns the friend list of a specified Steam user. The profile must have Public visibility to be retrieved successfully.

Arguments:

• steamid: The Steam Player ID of the profile to retrieve, as a string.

• relationship (optional): The relationship of the information to the specified user, as a string. Accepted arguments are "all" and "friend".

• format (optional) : The format to return the data-- JSON (default), XML, or VDF.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getFriendList({
    steamid: "01234567890123456", // Return info for the specified Steam ID
    relationship: "all", // Return all relationship data for the specified Steam ID
  });

  // Do something with the result
}

myFunc();

5.5 | getPlayerAchievements

Description: Returns a list of achievements for a particular user, for a specific app ID.

Arguments

• steamid: The Steam Player ID of the profile to retrieve, as a string.

• appid : The appID of the game for which you want to retrieve the player achievements.

• format (optional) : The format to return the data-- JSON (default), XML, or VDF.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getPlayerAchievements({
    steamid: "0123456789123456", // Return info for the specified Steam ID
    appid: "440", // Return all relationship data for the app Team Fortress 2
  });

  // Do something with the result
}

myFunc();

5.6 | getUserStatsForGame

Description: Returns a list of information and achievements for a particular user, for a specific app ID.

Arguments:

• steamid: The Steam Player ID of the profile to retrieve, as a string.

• appid : The appID of the game for which you want to retrieve user stats, as a string or integer.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getUserStatsForGame({
    steamid: "01234567890123456", // Return info for the specified Steam ID
    appid: "440", // Return all relationship data for the app "Team Fortress 2"
  });

  // Do something with the result
}

myFunc();

5.7 | getOwnedGames

Description: Returns a list of owned games for a particular user, if the user's profile is set to Public visibility.

Arguments:

• steamid: The Steam Player ID of the profile to retrieve, as a string.

• include_appinfo (optional): Whether or not you want additional app info included in the results, as as boolean. By default, this is set to true.

• include_played_free_games (optional): Whether or not you want to include free games that all Steam accounts technically "own", as a boolean. By default, this is set to true.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getOwnedGames({
    steamid: "01234567890123456", // Return data for the specified Steam ID
    specificData: "games", // Return the specific games object inside of the primary returned object
    includeAppInfo: false, // Disable additional app info, which is enabled by default.
    includePlayedFreeGames: false, // Disable including played free games, which is enabled by default.
  });

  // Do something with the result
}

myFunc();

5.8 | getRecentlyPlayedGames

Description: Returns a list of games played by a specified user within the last two weeks, if the profile is set to Public visibility.

Arguments:

• steamid: The Steam Player ID of the profile to retrieve, as a string.

Example:

import CallSteamAPI from "./src/SteamWebAPILibrary.js";

const myAppVariable = new CallSteamAPI();

async function myFunc() {
  const result = await myAppVariable.getRecentlyPlayedGames({
    steamid: "01234567890123456", // Return info for the specified Steam ID
    count: "3", // Return up to 3 most recently played games
  });

  // Do something with the result
}

myFunc();

6.0 | Tests

Description: In order to scalable and maintainable code, this package has a suite of tests. This section discusses what those tests do, and how to run them.

Summary: This package has an in-memory cache. Since it currently supports GET requests, it doesn't not invalidate this cache, and since it's in-memory it doesn't need to support expiration.

The tests located in /tests currently test the in-memory cache, which can also be switched off by explicitely passing in a false value for useCache.

When running these tests, the CallSteamAPI class bypasses the check for a Steam API Key.