inkwell
1.0.0An API client for the Splatoon 2 Splatnet.
Table of Contents
About Inkwell
This is a client library for the Splatoon 2 Splatnet API. It offers access to player and battle statistics, basically exposing all the information available on the official Nintendo Switch mobile phone app.
How To
This library does not currently handle the log in flow, as it is not publicly documented. You will have to provide a valid session token in order to make requests against the API. In order to obtain this token, search for iksm_session and use one of the methods described to sniff out the token from the phone app. Personally I've found the ink-proxy method to be the easiest and most reliable.
Once you have obtained the iksm_session token, you should plug it into the library:
(ql:quickload :inkwell)
(setf inkwell:*session* "adwdwadwaddadwadadwadawd")
From there you can retrieve information about current battles (list-battles, battle), single-player statistics (single-player), upcoming battle modes (schedules), specific users (user), active and past splafests (active-festivals, list-festivals, votes, rankings), and even the online shop merchandise (shop-info, order).
(inkwell:list-battles)
; => (#<INKWELL:BATTLE CLAM-BLITZ VICTORY {1111}>
; #<INKWELL:BATTLE CLAM-BLITZ LOSS {1110}>
; #<INKWELL:BATTLE CLAM-BLITZ VICTORY {1109}>
; #<INKWELL:BATTLE CLAM-BLITZ LOSS {1107}>
; #<INKWELL:BATTLE CLAM-BLITZ LOSS {1106}>
; ...)
The library takes care to transform the results from the API into sensible objects for you to inspect and extract information from with ease. Have a look at the symbol index to see what is offered.
A note about requests: this library does not take any care to attempt and rate limit or cache. Please be mindful that if you send too many requests over your session, you may get blocked by Nintendo. However, since many statistics only update infrequently (~3 minutes for battles) or rarely (~1 hour for schedules), it should be easy to implement a caching scheme in your application.
System Information
Definition Index
-
INKWELL
- ORG.SHIRAKUMO.INKWELL
No documentation provided.-
EXTERNAL SPECIAL-VARIABLE *BASE-URL*
The base URL for all Splatnet resources.
-
EXTERNAL SPECIAL-VARIABLE *SESSION*
The iksm_session cookie value required for Splatnet requests. There is currently no automated procedure to generate or fetch such a token. You will have to use some form of MITM packet sniffing tool to extract it from requests from your Nintendo Switch mobile app. If you google for iskm_session you should find a couple of tutorials and tools to do it.
-
EXTERNAL CLASS ALPHA-TEAM
Representation of team alpha for a festival (splatfest). See FESTIVAL-TEAM
-
EXTERNAL CLASS BATTLE
-
EXTERNAL CLASS BRAND
Representation of a gear brand. See FREQUENT-SKILL See IMAGE See NAME See ID
-
EXTERNAL CLASS BRAVO-TEAM
Representation of team bravo for a festival (splatfest). See FESTIVAL-TEAM
-
EXTERNAL CLASS CHALLENGE
Representation of an ink points challenge on the app. See ID See NAME See PAINT-POINTS See IMAGE
-
EXTERNAL CLASS FESTIVAL
Representation of a festival (splatfest). This is used for both past and future festivals, though some fields will not be available until the festival is over. See ID See TEAMS See ANNOUNCE-TIME See START-TIME See END-TIME See SPECIAL-STAGE See RESULT-TIME
-
EXTERNAL CLASS FESTIVAL-TEAM
-
EXTERNAL CLASS GEAR
-
EXTERNAL CLASS MERCHANDISE
-
EXTERNAL CLASS PLAYER
-
EXTERNAL CLASS PLAYER-RESULT
-
EXTERNAL CLASS RANK
Representation of a player's rank in a ranked or league mode. See NAME See PROGRESS See S-PLUS-NUMBER
-
EXTERNAL CLASS RANKING
-
EXTERNAL CLASS SALMON-RUN
Representation of a Salmon Run shift. See STAGE See END-TIME See START-TIME See WEAPONS See REWARD
-
EXTERNAL CLASS SCHEDULE
-
EXTERNAL CLASS SINGLE-PLAYER
Representation of single-player mode performance statistics. See HONOR See CLEAR-RATE See CLEARED-WEAPONS See STAGE-INFO
-
EXTERNAL CLASS SKILL
-
EXTERNAL CLASS SPECIAL
-
EXTERNAL CLASS STAGE
-
EXTERNAL CLASS STAGE-INFO
Representation of performance statistics on a single-player stage. See AREA See ID See BOSS-P See WEAPON-INFO
-
EXTERNAL CLASS SUB
-
EXTERNAL CLASS TIMELINE
Representation of the overall timeline object. This object contains bits and pieces of information about the overall status of the splatnet for the user. It is used to present the "home page" on the Switch app for Splatoon. See ID See SALMON-RUN See STATS See SCHEDULE See CHALLENGE See PAINT-POINTS See MERCHANDISE See RANK-UP-MATCH See DLC-AVAILABLE-P See NEW-WEAPONS
-
EXTERNAL CLASS USER
-
EXTERNAL CLASS WEAPON
-
EXTERNAL CLASS WEAPON-INFO
Representation of performance statistics of a weapon on a particular single-player stage. See ID See NAME See LEVEL See CLEAR-TIME See IMAGE
-
EXTERNAL CLASS WEAPON-RELEASE
Representation of a new weapon release. See WEAPON See RELEASE-TIME
-
EXTERNAL CONDITION API-REQUEST-FAILED
-
EXTERNAL FUNCTION ACTIVE-FESTIVALS
Retrieves active festivals (splatfests). See FESTIVAL
-
EXTERNAL FUNCTION BATTLE
- BATTLE
Retrieves a specific battle result. Takes either a battle object or an ID. See BATTLE
-
EXTERNAL FUNCTION LIST-BATTLES
Retrieves a list of recent battle results. See BATTLE
-
EXTERNAL FUNCTION LIST-FESTIVALS
Retrieves past festivals (splatfests). See FESTIVAL
-
EXTERNAL FUNCTION LIST-STAGES
Lists all available stages/maps. See STAGE
-
EXTERNAL FUNCTION ORDER
- MERCHANDISE
- &KEY
- OVERRIDE
Order a marchandise item from the online shop. Takes a MERCHANDISE instance, or a merchandise ID. If the user has already ordered something, and override is NIL, the requested merchandise will not be ordered. See MERCHANDISE
-
EXTERNAL FUNCTION RANKINGS
- FESTIVAL
Retrieves top-100 rank listings for a specific festival (splatfest). Takes a FESTIVAL instance, or a festival ID. Returns a list of two entries, the first being a list of the top 100 rankings for team alpha, the second being a list of the top 100 rankings for team bravo. The lists are sorted by rank. See RANKING
-
EXTERNAL FUNCTION REQUEST
- ENDPOINT
- &KEY
- URLPARTS
- PARAMETERS
- FORM-DATA
- SESSION
- STRING
Perform a request against the specified API endpoint. Note that the endpoint must begin with a slash. If you need to parameterise the URL, use the urlparts argument. Note that slashes are automatically inserted before each urlpart, so you will not need to do so yourself. In case of an error code being returned from the server, a condition of type API-REQUEST-FAILED is signalled. See API-REQUEST-FAILED See *SESSION*
-
EXTERNAL FUNCTION SCHEDULES
Retrieves schedule information for upcoming online rotations. Returns a plist of three keys, :REGULAR :RANKED and :LEAGUE. Each value is a list of SCHEDULE entries. See SCHEDULE
-
EXTERNAL FUNCTION SHOP-INFO
Retrieves online shop information. Returns two values: a list of available merchandise, and, if the user has already ordered something, the ordered merchandise. See MERCHANDISE
-
EXTERNAL FUNCTION SINGLE-PLAYER
Retrieves single-player mode statistics. See SINGLE-PLAYER
-
EXTERNAL FUNCTION TIMELINE
Retrieves the overall timeline object. See TIMELINE
-
EXTERNAL FUNCTION USER
- USER
Retrieves information about a specific user. See USER
-
EXTERNAL FUNCTION VOTES
- FESTIVAL
Retrieves information about votes cast by your friends for a specific festival (splatfest). Takes a FESTIVAL instance, or a festival ID. Returns a list of two entries, the first being a list of all friends that voted for team alpha, and the second being a list of all friends that voted for team bravo. See USER
-
EXTERNAL GENERIC-FUNCTION ANNOUNCE-TIME
- OBJECT
Returns the timestamp on which the festival (splatfest) was announced.
-
EXTERNAL GENERIC-FUNCTION AREA
- OBJECT
Returns the ID of the area the stage-info is about. See STAGE-INFO
-
EXTERNAL GENERIC-FUNCTION ASSISTS
- OBJECT
Returns the number of assists the player achieved in the battle. See BATTLE
-
EXTERNAL GENERIC-FUNCTION BODY
- CONDITION
The HTTP body as a string. See API-REQUEST-FAILED
-
EXTERNAL GENERIC-FUNCTION BOSS-P
- OBJECT
Returns whether this stage is a boss. See STAGE-INFO
-
EXTERNAL GENERIC-FUNCTION BRAND
- OBJECT
-
EXTERNAL GENERIC-FUNCTION CHALLENGE
- OBJECT
-
EXTERNAL GENERIC-FUNCTION CHEATER-P
- OBJECT
Returns whether the player was deemed to be a cheater or not. See RANKING
-
EXTERNAL GENERIC-FUNCTION CLEAR-RATE
- OBJECT
Returns the overall clear-rate. 1.0 means 100%, but it can go up to 10. See SINGLE-PLAYER
-
EXTERNAL GENERIC-FUNCTION CLEAR-TIME
- OBJECT
Returns the clear time using the weapon for a particular stage. The time is in seconds. See WEAPON-INFO
-
EXTERNAL GENERIC-FUNCTION CLEARED-WEAPONS
- OBJECT
Returns a list of cleared weapons. The list is composed of strings of the weapon names. See SINGLE-PLAYER
-
EXTERNAL GENERIC-FUNCTION CLOTHES
- OBJECT
-
EXTERNAL GENERIC-FUNCTION CODE
- CONDITION
The HTTP status code that was returned. See API-REQUEST-FAILED
-
EXTERNAL GENERIC-FUNCTION COLOR
- OBJECT
Returns the colour of the festival (splatfest) team. This is a list with components R G B A. See FESTIVAL-TEAM
-
EXTERNAL GENERIC-FUNCTION DEATHS
- OBJECT
Returns the number of times the player died in the battle. See BATTLE
-
EXTERNAL GENERIC-FUNCTION DLC-AVAILABLE-P
- OBJECT
Returns whether there is DLC ready to download. See TIMELINE
-
EXTERNAL GENERIC-FUNCTION DURATION
- OBJECT
Returns the duration of the battle in seconds. See BATTLE
-
EXTERNAL GENERIC-FUNCTION END-TIME
- OBJECT
Returns the timestamp on which this object becomes invalid/outdated. See SALMON-RUN See SCHEDULE See MERCHANDISE See FESTIVAL
-
EXTERNAL GENERIC-FUNCTION FREQUENT-SKILL
- OBJECT
-
EXTERNAL GENERIC-FUNCTION GEAR
- OBJECT
Returns the piece of gear this merchandise is selling. See GEAR See MERCHANDISE
-
EXTERNAL GENERIC-FUNCTION HEAD
- OBJECT
-
EXTERNAL GENERIC-FUNCTION HONOR
- OBJECT
Returns the single-player honor description. See SINGLE-PLAYER
-
EXTERNAL GENERIC-FUNCTION ID
- OBJECT
Returns some kind of ID (may be a string or number) to identify the object. Note that some IDs are not globally unique. See BATTLE See STAGE See PLAYER See WEAPON See SPECIAL See SUB See STAGE-INFO See WEAPON-INFO See FESTIVAL See MERCHANDISE See GEAR See BRAND See SKILL See USER See RANKING See SCHEDULE See TIMELINE See CHALLENGE
-
EXTERNAL GENERIC-FUNCTION IMAGE
- OBJECT
Returns a full URL to an image resource showing the object. See STAGE See WEAPON See WEAPON-INFO See FESTIVAL-TEAM See GEAR See BRAND See SKILL See CHALLENGE
-
EXTERNAL GENERIC-FUNCTION IMAGE-A
- OBJECT
-
EXTERNAL GENERIC-FUNCTION IMAGE-B
- OBJECT
-
EXTERNAL GENERIC-FUNCTION KILLS
- OBJECT
Returns the number of kills the player achieved in the battle. See BATTLE
-
EXTERNAL GENERIC-FUNCTION KIND
- OBJECT
Returns the kind of gear this is as a keyword. See MERCHANDISE See GEAR
-
EXTERNAL GENERIC-FUNCTION LEVEL
- OBJECT
Returns the level of the weapon. See WEAPON-INFO
-
EXTERNAL GENERIC-FUNCTION LONG-NAME
- OBJECT
Returns the long, descriptive name of the festival (splatfest) team. See FESTIVAL-TEAM
-
EXTERNAL GENERIC-FUNCTION MERCHANDISE
- OBJECT
Returns a single piece of merchandise currently available for purchase. See MERCHANDISE See TIMELINE
-
EXTERNAL GENERIC-FUNCTION MODE
- OBJECT
-
EXTERNAL GENERIC-FUNCTION NAME
- OBJECT
-
EXTERNAL GENERIC-FUNCTION NEW-WEAPONS
- OBJECT
Returns a list of new weapons that will be released soon / have been released recently. See WEAPON-RELEASE See TIMELINE
-
EXTERNAL GENERIC-FUNCTION PAINT-POINTS
- OBJECT
Returns the number of paint points the player gained in the battle. See PLAYER-RESULT See CHALLENGE See TIMELINE
-
EXTERNAL GENERIC-FUNCTION PARTICIPANTS
- OBJECT
Returns the number of people that voted for this festival (splatfest) team. See FESTIVAL-TEAM
-
EXTERNAL GENERIC-FUNCTION PLAYER
- OBJECT
Returns the player associated with this object. See PLAYER See PLAYER-RESULT See RANKING
-
EXTERNAL GENERIC-FUNCTION PLAYER-RANK
- OBJECT
Returns the player's rank number. See PLAYER
-
EXTERNAL GENERIC-FUNCTION POWER
- OBJECT
Returns the battle power. See BATTLE
-
EXTERNAL GENERIC-FUNCTION PRICE
- OBJECT
Returns the price of the merchandise. See MERCHANDISE
-
EXTERNAL GENERIC-FUNCTION PROGRESS
- OBJECT
Returns the progress the player has made in the rank. See RANK
-
EXTERNAL GENERIC-FUNCTION RANK
- OBJECT
-
EXTERNAL GENERIC-FUNCTION RANK-UP-MATCH
- OBJECT
-
EXTERNAL GENERIC-FUNCTION RARITY
- OBJECT
Returns a rarity index of the gear. See GEAR
-
EXTERNAL GENERIC-FUNCTION RELEASE-TIME
- OBJECT
Returns a timestamp of the date on which this weapon will become available. See WEAPON-RELEASE
-
EXTERNAL GENERIC-FUNCTION RESULT-TIME
- OBJECT
Returns the timestamp on which the festival (splatfest) results are announced. See FESTIVAL
-
EXTERNAL GENERIC-FUNCTION REWARD
- OBJECT
Returns the gear that can be won in this Salmon Run shift. See GEAR See SALMON-RUN
-
EXTERNAL GENERIC-FUNCTION RULE
- OBJECT
-
EXTERNAL GENERIC-FUNCTION S-PLUS-NUMBER
- OBJECT
Returns the S+ rank number, if any. See RANK
-
EXTERNAL GENERIC-FUNCTION SALMON-RUN
- OBJECT
Returns a salmon-run object if there is currently a Salmon Run shift open. See SALMON-RUN See TIMELINE
-
EXTERNAL GENERIC-FUNCTION SCHEDULE
- OBJECT
-
EXTERNAL GENERIC-FUNCTION SCORE
- OBJECT
Returns the total score of this ranking. See RANKING
-
EXTERNAL GENERIC-FUNCTION SCORES
- OBJECT
Returns a list of scores for the user's team and the opponent team. The scores are either a point count for ranked modes, or a percentage for turf war. See BATTLE
-
EXTERNAL GENERIC-FUNCTION SHOES
- OBJECT
-
EXTERNAL GENERIC-FUNCTION SKILLS
- OBJECT
-
EXTERNAL GENERIC-FUNCTION SOLO
- OBJECT
Returns the number of won solo battles for this festival (splatfest) team. See FESTIVAL-TEAM
-
EXTERNAL GENERIC-FUNCTION SORTING
- OBJECT
Returns an integer to sort the objects of this kind by. See PLAYER-RESULT See RANKING
-
EXTERNAL GENERIC-FUNCTION SPECIAL
- OBJECT
-
EXTERNAL GENERIC-FUNCTION SPECIAL-STAGE
- OBJECT
-
EXTERNAL GENERIC-FUNCTION SPECIALS
- OBJECT
Returns the number of times the player used their special in the battle. See BATTLE
-
EXTERNAL GENERIC-FUNCTION STAGE
- OBJECT
Returns the stage where the battle took place. See STAGE See BATTLE See SALMON-RUN
-
EXTERNAL GENERIC-FUNCTION STAGE-INFO
- OBJECT
Returns a list of statistics about each single-player stage. See STAGE-INFO See SINGLE-PLAYER
-
EXTERNAL GENERIC-FUNCTION STAGES
- OBJECT
-
EXTERNAL GENERIC-FUNCTION STAR-RANK
- OBJECT
Returns the player's star rank number. See PLAYER
-
EXTERNAL GENERIC-FUNCTION START-TIME
- OBJECT
Returns the starting date timestamp. See BATTLE See FESTIVAL See SCHEDULE See SALMON-RUN
-
EXTERNAL GENERIC-FUNCTION STATS
- OBJECT
-
EXTERNAL GENERIC-FUNCTION SUB
- OBJECT
-
EXTERNAL GENERIC-FUNCTION TEAM
- OBJECT
Returns the number of won team battles for this festival (splatfest) team. See FESTIVAL-TEAM
-
EXTERNAL GENERIC-FUNCTION TEAMS
- OBJECT
Returns a list of two items for the teams for the battle. Each team list is sorted by the player-result's sorting. The first list is always the user's own team. See PLAYER-RESULT See BATTLE
-
EXTERNAL GENERIC-FUNCTION THUMBNAIL
- OBJECT
-
EXTERNAL GENERIC-FUNCTION UNIQUE-ID
- OBJECT
Returns the unique id of this ranking. See RANKING
-
EXTERNAL GENERIC-FUNCTION UPDATED-TIME
- OBJECT
Returns a timestamp of the last time this ranking was updated. See RANKING
-
EXTERNAL GENERIC-FUNCTION URL
- CONDITION
The URL to which the request failed. See API-REQUEST-FAILED
-
EXTERNAL GENERIC-FUNCTION VICTORY-P
- OBJECT
Returns whether the battle was a victory for the user or not. See BATTLE
-
EXTERNAL GENERIC-FUNCTION WEAPON
- OBJECT
Returns the weapon the player used or the weapon that is being released. See WEAPON See PLAYER See WEAPON-RELEASE
-
EXTERNAL GENERIC-FUNCTION WEAPON-INFO
- OBJECT
Returns a list of weapon statistics for the stage. The list is sorted by the clear time, lowest first. See WEAPON-INFO See STAGE-INFO
-
EXTERNAL GENERIC-FUNCTION WEAPONS
- OBJECT
Returns a list of weapons that will be handed out for this Salmon Run shift. See WEAPON See SALMON-RUN