splatoon3api - v3.0.1

Splatoon3api is a simple library to get the current and next Splatoon 3 Maps (rotations), Salmon Runs, Challenges, Splatfests and Splatnet gear. This package uses the data from splatoon3.ink. Splatoon3api is available in 14 different languages (List of available languages)

If you have trouble with this package, feel free to ask me in my Discord.

Table of contents

• Installation
• Usage
  • Languages
  • Options
  • Stages
    • All Stages
      • Current stages
      • Next stages
  • Other
    • Salmon Run
    • Challenges
    • Splatnet gear
  • Splatfests
    • Currently running Splatfests
    • Upcoming Splatfests
    • Past Splatfests

Installation

Simply execute the following command in your commandline:

npm install splatoon3api
Copy

Usage

import { Client } from 'splatoon3api';

const splatoon3 = new Client();

const stages = await splatoon3.stages.getCurrent();
console.log(stages);
Copy

Every method returns a Promise, so you can use await or .then() to get the result.

Languages

A Client isn't tied to a single language. Every fetch method takes an optional { lang }, which falls back to the client's defaultLang ("en-US" unless configured otherwise) when omitted:

const splatoon3 = new Client({ defaultLang: 'de-DE' });

const stagesDE = await splatoon3.stages.getCurrent(); // uses defaultLang: de-DE
const stagesEN = await splatoon3.stages.getCurrent({ lang: 'en-US' }); // one-off override
Copy

One Client is all you need even in a multi-language app. The underlying schedule/gear/festival data is cached once regardless of language, and each language's translation file is fetched once and reused across every call. You never need to create multiple clients just to serve multiple languages.

Supported values for lang / defaultLang:

• en-US - English (US)
• en-GB - English (GB)
• de-DE - Deutsch
• nl-NL - Nederlands
• fr-FR - Français (FR)
• fr-CA - Français (CA)
• es-ES - Español (ES)
• es-MX - Español (MX)
• it-IT - Italiano
• ru-RU - Русский
• ja-JP - 日本語
• ko-KR - 한국어
• zh-CN - 中文(简体)
• zh-TW - 中文(台灣)

Options

You can tune splatoon3api to your liking by passing options to the Client constructor:

const splatoon3 = new Client({
    defaultLang: 'en-GB',
    userAgent: 'MyApp/1.0 (contact@example.com)',
    cache: {
        enabled: true,
        ttl: 60,
    },
});
Copy

By default, raw upstream data is cached in memory for the lifetime of the Client. If you need a shared cache across multiple processes (e.g. Redis), pass a cacheStore implementing get(key)/set(key, value, ttlSeconds?):

const splatoon3 = new Client({
    cacheStore: {
        async get(key) {
            /* ... */
        },
        async set(key, value, ttlSeconds) {
            /* ... */
        },
    },
});
Copy

Stages

All Stages

To get 11 upcoming and the current stages for Turf War, Ranked, X Battle, and Splatfest, use stages.getAll():

const stages = await splatoon3.stages.getAll();
console.log(stages);
Copy

Current Stages

To get the currently active Turf War, Ranked and X Battle maps, use stages.getCurrent():

const stages = await splatoon3.stages.getCurrent();
console.log(stages);
Copy

Next Stages

To get the next Turf War, Ranked and X Battle maps, use stages.getNext():

const stages = await splatoon3.stages.getNext();
console.log(stages);
Copy

Other

Salmon Run Schedules

To get the current and next Salmon Run schedules, use salmonRun.get():

const salmonRun = await splatoon3.salmonRun.get();
console.log(salmonRun);
Copy

Challenges

To get the current challenges, use challenges.get():

const challenges = await splatoon3.challenges.get();
console.log(challenges);
Copy

Splatnet Gear

To get the currently available Splatnet gear, use gear.get():

const gear = await splatoon3.gear.get();
console.log(gear);
Copy

Splatfests

Splatfests are divided into those four regions:

• US: The Americas, Australia, New Zealand
• EU: Europe
• JP: Japan
• AP: Hong Kong, South Korea (Asia/Pacific)

Currently running Splatfest

To get the currently running Splatfest, use splatfests.running():

const running = await splatoon3.splatfests.running();
console.log(running);
Copy

Please note that the hex colors may differ a little from the real colors. If you want the most accurate colors, you should use the color (rgba) field instead of colorHEX.

Scheduled Splatfests

To get scheduled Splatfests that are coming in the future, use splatfests.upcoming():

const upcoming = await splatoon3.splatfests.upcoming();
console.log(upcoming);
Copy

Note that upcoming Splatfest titles and team names come straight from Nintendo's per-region data rather than the translation file, so lang/defaultLang has no effect on this particular call.

Past Splatfests

To get all past Splatfests, use splatfests.past():

const past = await splatoon3.splatfests.past();
console.log(past);
Copy