🔒 Query Service

POST

/{service}/query

Query data from any of the available Nintendo Switch Online microservices. Currently available services are:

• Coral
• Splatnet 3

Caution

502 response codes should be treated with caution! It means something went wrong while trying to authenticate with Nintendo.
Please read the section handling 502 responses for more information.

Authorization

Session Token string required

Uses the session token generated from the generate token endpoint

API Key string required

Request

Parameters

Service string required

Name of the service you want to query

Headers

X-Agent string required

Name of your application. Should either be in the format {appName}/{version} or provide contact information

X-Language string

Language for the query results (unused)

Body required

Requires an array of simple and/or complex queries that you want to perform on the given service

Example

{
  "simpleQueries": [
    ""
  ],
  "detailedQueries": [
    {}
  ]
}

Minimum request time: 0 seconds

Schema

Object

• simpleQueries*[string]String array of simple queries you want to perform on the given service
• detailedQueries*[object]Object array of complex queries you want to perform on the given service

Test

Fill Example

Reset

Response

200

Success

Example

{
  "error": false,
  "data": [
    {
      "error": false,
      "data": {}
    },
    {
      "error": true,
      "message": "Failed to fetch query"
    }
  ]
}

Schema

Object

• errorboolean
• [object]

  • errorboolean
  • datastring

400

Bad Request

Example

{
  "error": true,
  "message": "Invalid service"
}

Schema

Object

• errorboolean
• messagestring

401

Unauthorized

Example

{
  "error": true,
  "message": "Invalid authorization"
}

Schema

Object

• errorboolean
• messagestring

409

Conflict

Example

{
  "error": true,
  "message": "Another process is already running"
}

Schema

Object

• errorboolean
• messagestring

429

Too Many Requests

Example

{
  "error": true,
  "message": "Rate limit exceeded"
}

Schema

Object

• errorboolean
• messagestring

500

Internal Server Error

Example

{
  "error": true,
  "message": "Failed to generate tokens"
}

Schema

Object

• errorboolean
• messagestring

502

Bad Gateway

Example

{
  "error": true,
  "message": {
    "step": "0/7 (getting user access token)",
    "nintendoResponse": {
      "error_description": "The provided grant is invalid",
      "error": "invalid_grant"
    }
  }
}

Schema

Object

• errorboolean
• object

  • stepstringThe authentication step which caused the error
  • object

    • error_descriptionstring
    • errorstring

Handling 502 Responses

When something goes wrong while trying to authenticate with Nintendo, you will receive a 502 response code, alongside a JSON object with information about where the process failed. It is important to understand how to handle these responses correctly.

Caution

Refrain from repeating the request with the same data until the issue is resolved!

Understanding The Steps

The JSON object you receive will contain a step field inside of the message object, which will tell you more about where and why the process failed.

Some steps will contain a status field inside the nintendoResponse object, which will give you more information about the error.

• 0/7 (getting user access token)

  The provided session token is invalid or expired. Generate a new session token and try again.

• 1/7 (getting user info)

  This step should never fail unless something went wrong on Nintendos side. If it does, report it to me immediately.

• 2/7 (getting first fToken)

  This step can sometimes fail if the fToken endpoint is unavailable. This is a server-side issue and should be reported to me.

  The status of the fToken API can be found on the imink status website.

• 3/7 (getting web service access token)

  • Nintendo response status 9407

    The account associated with the session token is not linked to a Nintendo console. This is a client-side issue and should be reported to the user.

  • Nintendo response status 9427 and 9403

    The NSO app has received an update and the version number used by the API is outdated. This is a server-side issue and should be reported to me.

• 4/7 (getting second fToken)

  Same as step two.

• 5/7 (getting gToken)

  • Nintendo response status 9450

    The account associated with the session token does not have a valid NSO membership. This is a client-side issue and should be reported to the user.

• 6/7 (getting service parameters)

  The account associated with the session token does not own or has not used the service you are trying to query. This is a client-side issue and should be reported to the user.

• 7/7 (storing parameters)

  Uncommon step to fail. It means something went wrong while trying to store the service parameters in the database. This is a server-side issue and should be reported to me.

  You can find out more about what, how and why the services parameters are stored on the Parameter Storage page.

Rate Limiting

This endpoint enforces very strict rate limiting to prevent excessive loads on Nintendos servers and to prevent abuse of the API.

The rate limits are set up in a way that less requests are made than when using the NSO app itself.

• Base limit

  2 request every 10 seconds per session token.

• Process limit

  1 running process per session token.

  You can not send a new request until the previous one has finished.

• Speed limit

  2 seconds between every query in a request.

  When passing multiple queries in a single request, the server will wait for 2 seconds between every query.

• Size limit

  25 queries per request.

Despite these limits, you should still do your best to minimize the amount of requests you make to the API. Our goal is to provide a service that is both useful to users and respectful to Nintendo.

Session tokens get hashed before being used for rate limiting as to not temporarily store their raw value in the database.

Note

It is recommended to split a query up into multiple requests if the single request would take longer than 20 seconds to complete.

Once a query is started, it can not be aborted, locking the session token for the duration of the query.

Aditional Notes

• Responses are sanitized from any links pointing at resources such as images or videos. Nintendo is not a CDN and should not be used as one.
  If you require these resources, you can fetch them from Leannys GitHub repository instead.

• Service parameters need to be regenerated every 2 hours. This will add a small delay of around 5-8 seconds. If a query is taking longer than usual, this might be the reason why.