QuickStart¶

Installation¶

To install the package, run the following command:

pip install splatnet3_scraper

Usage¶

This package includes three interfaces for interacting with SplatNet 3. The first is the Scraper Module module, which provides a user-level interface that greatly simplifies the process of retrieving data from SplatNet 3. The second is the Query Module, which provides a high-level interface that simplifies the process of creating queries without having to worry about the underlying implementation details. The third is the Auth Module module, which provides a low-level interface that gives the user full control over the authentication and querying process. The Scraper Module module is recommended for most users, it is the easiest to use and is designed with users who are not highly familiar with Python or just do not want to worry about the implementation details. The Query Module is recommended for users for whom the Scraper Module module is not sufficient, but want to avoid having to worry about the implementation details. The Auth Module module is recommended for advanced users who want to have full control over the authentication and querying process. All three modules require a Nintendo Switch Online membership as well as having played at least one match online in Splatoon 3. For more information on obtaining a session token, see Obtaining A Session Token.

Obtaining Ranked Battle Data¶

This example will show how to use the Scraper Module module to obtain ranked battle data and save it to a JSON file. This is the recommended method for most users, as it is simple and handles query orchestration as well as their underlying implementation details automagically. This module provides a single class, SplatNet_Scraper, which contains many methods that can be used to retrieve commonly requested data from SplatNet 3. This class is currently in active development and as such the methods provided by this class are limited, but more methods will be added as development continues. For a full list of methods, see the documentation for SplatNet_Scraper. If you need to retrieve data that is not currently supported by this class, you can place a feature request on the Github Repository as an issue, or you can use the Query Module to create your own queries until the feature is added. First we will import the SplatNet_Scraper class and instantiate it using a session token:

from splatnet3_scraper.scraper import SplatNet_Scraper
session_token = "your_session_token"
scraper = SplatNet_Scraper(session_token)

Please note that the session_token variable should be replaced with a valid session token. That’s all it takes to get started! The SplatNet_Scraper class is now ready to be used to retrieve data from SplatNet 3. Pulling data from SplatNet 3 is as simple as calling one of the methods provided by the SplatNet_Scraper class. For this example, we will be using the SplatNet_Scraper.get_vs_battles() method, which can be used to retrieve data for all ranked battles. The following code can be used to retrieve ranked battle data:

summary, battles = scraper.get_vs_battles(mode="anarchy", detail=True)

The summary variable is a QueryResponse object, which contains the data returned by the query as well as some metadata about the query. The data property can be used to access the raw data returned by the query. The battles variable is a list of QueryResponse objects, which each contain the data for a single ranked battle.

That’s it, we now have the data we need. It’s really that simple! This example will keep being updated as the SplatNet_Scraper class is updated, so check back later for more examples or more features to be built-in to the shown function, SplatNet_Scraper.get_vs_battles().

Query Example¶

Let’s say we want to access data not currently supported by the Scraper Module module, such as the stage rotation schedule. We can use the Query Module to create our own queries. The Query Module provides a high-level interface that still abstracts away the implementation details, but gives the user more control over the process. This module provides a main class, the QueryHandler, which can be used to create queries and execute them.

This example will show how to use the Query Module to obtain the stage rotation schedule and save it to a JSON file. This is the recommended method for users who want to pull data that is not currently supported by the Scraper Module module, but do not want to worry about the implementation details.

Obtaining and Saving the Stage Rotation Schedule¶

This example will show how to use the query module to obtain the stage rotation schedule and save it to a JSON file. This i The scraper module is the recommended module for most users, as it provides a high-level interface that greatly simplifies the process of retrieving data from SplatNet 3. This module provides a single class, QueryHandler, which can be used to retrieve data from SplatNet 3. There are a few ways to instantiate this class, but following in the spirit of the above example, we will be using the QueryHandler.from_session_token() method, which takes a session token as its only argument. For a full list of options, see the documentation for QueryHandler. First we will import the QueryHandler class and instantiate it using a session token:

from splatnet3_scraper.query import QueryHandler

session_token = "your_session_token"
handler = QueryHandler.from_session_token(session_token)

Please note that the session_token variable should be replaced with a valid session token. Similar to the Scraper Module module, the handler object is now ready to be used to retrieve data from SplatNet 3. The main way to retrieve data from SplatNet 3 is by using the QueryHandler.query() method. This method takes the query name as its first argument, and any variables that are required by the query as its second argument. For a full list of queries and their required variables, see the documentation for Queries. For this example, we will be using the StageScheduleQuery, which requires no variables to be passed. The following code can be used to retrieve the stage rotation schedule for X Battles:

response = handler.query("StageScheduleQuery")

The response object is a QueryResponse object, which contains the data returned by the query as well as some metadata about the query. The data property can be used to access the raw data returned by the query. The QueryResponse object also supports numpy-style indexing, which can be used to quickly and clearly access specific parts of the data. For example, the following code can be used to access the name of the game mode for the first X Battle in the schedule:

game_mode = response["xSchedules", "nodes", 0, "vsRule", "name"]

The QueryResponse object also provides a QueryResponse.parsed_json() method, which returns a JSONParser object that can be used to interact with the data in multiple ways. For more information, see the documentation for JSONParser. The following code can be used to save the stage rotation schedule data to a JSON file:

response.parsed_json().to_json("schedule.json")

That’s it! The stage rotation schedule data has now been saved to a JSON file. You are now ready to start retrieving data from SplatNet 3!