nxapi/docs/lib/splatnet2.md

nxapi/splatnet2

SplatNet2Api

This is exported as default.

SplatNet 2 API client. An instance of this class should not be created directly; instead one of the createWith* static methods should be used.

Most of this API is intentionally undocumented. Read the source code at src/api/splatnet2.ts, src/common/auth/splatnet2.ts and src/cli/splatnet2 for examples of using this API. If you need any help using this API ask in #splatnet2 on Discord.

You should review HTTP captures of SplatNet 2 in the Nintendo Switch Online app and attempt to match the behaviour of Nintendo's official app.

SplatNet2Api.createWithCoral

Authenticate to SplatNet 2 using a CoralApi instance.

This function should not be called often. If your project will create a new SplatNet2Api object again for the same user before the SplatNet 2 session expires (usually 24 hours after last use), you must store the data object this returns and use SplatNet2Api.createWithSavedToken.

import CoralApi, { CoralAuthData } from 'nxapi/coral';
import SplatNet2Api, { SplatNet2AuthData } from 'nxapi/splatnet2';

const coral: CoralApi;
const coral_auth_data: CoralAuthData;

const {splatnet, data} = await SplatNet2Api.createWithCoral(coral, coral_auth_data.user);
// splatnet instanceof SplatNet2Api
// data is a plain object of type SplatNet2AuthData
// data should be saved and reused

SplatNet2Api.createWithSavedToken

Create a SplatNet2Api instance using cached data from SplatNet2Api.createWithCoral or SplatNet2Api.loginWithCoral.

import SplatNet2Api, { SplatNet2AuthData } from 'nxapi/splatnet2';

const auth_data: SplatNet2AuthData;

const splatnet = SplatNet2Api.createWithSavedToken(auth_data);
// splatnet instanceof SplatNet2Api

SplatNet2Api.createWithCliTokenData

Create a SplatNet2Api instance using the output of the nxapi splatnet2 token --json command.

import SplatNet2Api, { SplatNet2CliTokenData } from 'nxapi/splatnet2';

const data: SplatNet2CliTokenData;

const splatnet = SplatNet2Api.createWithCliTokenData(data);
// splatnet instanceof SplatNet2Api

SplatNet2Api.createWithIksmSession

Create a SplatNet2Api instance with an iksm_session and unique_id value.

SplatNet2Api.createWithCoral/SplatNet2Api.createWithSavedToken or SplatNet2Api.createWithCliTokenData should be preferred over this as they are better able to match SplatNet 2's behaviour.

import SplatNet2Api from 'nxapi/splatnet2';

const iksm_session: string;
const unique_id: string;

const splatnet = SplatNet2Api.createWithIksmSession(iksm_session, unique_id);
// splatnet instanceof SplatNet2Api

API types

nxapi/splatnet2 exports all API types from src/api/splatnet2-types.ts.

toLeagueId

Converts a Date and LeagueType to a string used in league ranking requests (/league_match_ranking/{id}/{region} or SplatNet2Api.getLeagueMatchRanking).

This function does not usually need to be used with SplatNet2Api.getLeagueMatchRanking, as a Date and LeagueType can be passed directly to it.

import { LeagueType, toLeagueId } from 'nxapi/splatnet2';

const league_id = toLeagueId(new Date(Date.UTC(2022, 0, 1, 0)), LeagueType.TEAM);
// league_id === '22010100T'

toXRankSeasonId

Converts a year and month to a string used in X Rank leaderboard requests (/x_power_ranking/{season}/{summary/rule}?page={page} or SplatNet2Api.getXPowerRankingSummary/SplatNet2Api.getXPowerRankingLeaderboard).

Months in this function start from 1, instead of 0 like Dates.

This function does not usually need to be used with SplatNet2Api.getXPowerRankingSummary or SplatNet2Api.getXPowerRankingLeaderboard, as an XRankSeason/Date and XPowerRankingRule can be passed directly to it.

import { toXRankSeasonId } from 'nxapi/splatnet2';

const season_id = toXRankSeasonId(2022, 1);
// season_id === '220101T00_220201T00'

getXRankSeasons

Returns an iterator that yields all X Rank seasons up to the current season according to the system date.

By default this will start from the current season and continue to the first season. Setting the first argument to true will cause this function to start from the first season and continue to the current season.

import { getXRankSeasons, XRankSeason } from 'nxapi/splatnet2';

for (const season of getXRankSeasons()) {
    // season is a plain object of type XRankSeason
}

// Alternatively this can be converted to a plain array.
// The iterator should be used instead where possible as it does not require
// keeping a reference to all Season objects.
// const seasons = [...getXRankSeasons()];

getXRankSeason

Returns an XRankSeason object from a Date, year and month, season ID string or index number.

import { getXRankSeason, XRankSeason } from 'nxapi/splatnet2';

const season = getXRankSeason(2022, 1);
// season is a plain object of type XRankSeason
// season.id === '220101T00_220201T00'
// season.key === '2022_01'
// season.index === 44
// season.start is a Date object with the UTC timestamp 2022-01-01 00:00:00
// season.end is a Date object with the UTC timestamp 2022-02-01 00:00:00
// season.complete === true, assuming the system time is after 2022-02-01 00:00:00 (UTC)

// This function can also be called like this:
const season = getXRankSeason(new Date(Date.UTC(2022, 1)));
const season = getXRankSeason('220101T00_220201T00');
const season = getXRankSeason(44);

getNextXRankSeason

Returns an XRankSeason object for the season following an X Rank season from an XRankSeason, Date, year and month, season ID string or index number.

import { getNextXRankSeason, XRankSeason } from 'nxapi/splatnet2';

const season = getNextXRankSeason(2022, 1);
// season is a plain object of type XRankSeason
// season.id === '220201T00_220301T00'
// season.key === '2022_02'
// season.index === 45
// season.start is a Date object with the UTC timestamp 2022-02-01 00:00:00
// season.end is a Date object with the UTC timestamp 2022-03-01 00:00:00
// season.complete === true, assuming the system time is after 2022-03-01 00:00:00 (UTC)

// This function can also be called like this:
const season = getNextXRankSeason(new Date(Date.UTC(2022, 1)));
const season = getNextXRankSeason('220101T00_220201T00');
const season = getNextXRankSeason(44);

getPreviousXRankSeason

Returns an XRankSeason object for the season following an X Rank season from an XRankSeason, Date, year and month, season ID string or index number.

import { getNextXRankSeason, XRankSeason } from 'nxapi/splatnet2';

const season = getPreviousXRankSeason(2022, 1);
// season is a plain object of type XRankSeason
// season.id === '211201T00_220101T00'
// season.key === '2021_12'
// season.index === 43
// season.start is a Date object with the UTC timestamp 2021-12-01 00:00:00
// season.end is a Date object with the UTC timestamp 2022-01-01 00:00:00
// season.complete === true, assuming the system time is after 2022-01-01 00:00:00 (UTC)

// This function can also be called like this:
const season = getPreviousXRankSeason(new Date(Date.UTC(2022, 1)));
const season = getPreviousXRankSeason('220101T00_220201T00');
const season = getPreviousXRankSeason(44);