Animal Crossing API ?

[AntoineTurmel]

Is it possible to use Animal Crossing features ?

[theogravity]

Here's what I've found so far:

Base URL: https://web.sd.lp1.acbaa.srv.nintendo.net/api/sd/v1

Headers:

• Accept: application/json, text/plain, */*
• (where required) Cookie: _gtoken=<web service access token - see next issue comment on the endpoint>

List AC Chracters tied to the account

Session cookie is required.

Method: GET
Path: /users

Response format:

{
	"users": [{
                 // character id
		"id": string,
                 // character name
		"name": string,
                 // character passport image URL
		"image": string,
                 // island info
		"land": {
                         // island id
			"id": string,
                         // island name
			"name": string,
                         // not sure what this is, but the value was "2" for me at the time
			"displayId": number
		}
	}]
}
}

Get auth token

• Session cookie is required
• Header: Origin: https://web.sd.lp1.acbaa.srv.nintendo.net

Method: POST
Path: /auth_token

Response format:

{
        // opaque value
	"token": string,
       // unix timestamp, looks like 1 hr expiry is set
	"expireAt": number
}

Get user passport

• cookie not required
• Authorization: Bearer <auth token> header was set

Method: GET
Path: /users/:user_id/profile?language=en-US

• :user_id: character id

Response:

{
        // unsure, was 30723
	"mVer": number,
         // en-US was my value
	"mLanguage": string,
        // character name
	"mPNm": string,
        // your birthdate set in game
	"mBirth": {
		"month": number,
		"day": number
	},
        // your passport title
        // mine is "Untossable Trash"
	"mHandleName": string,
        // the custom comment you set in your passport
	"mComment": string,
        // unsure what this is, but it was set to true for me
	"mIsLandMaster": bool,
        // unsure what this is, but it was set to 2020-3-23
	"mTimeStamp": {
		"year": number,
		"month": number,
		"day": number
	},
        // unsure what this is, but the value is empty
	"mMyDesignAuthorId": "string
        // passport profile pic
	"mJpeg": string,
        // unsure, was an 0xYYYYYYYYYYYYYY value
	"contentId": string,
         // checksum?
	"digest": string,
	"createdAt": number,
         // name of your island
	"landName": string
}

Get island data and island inhabitants

• cookie not required
• Authorization: Bearer <auth token> header was set

Method: GET
Path: /lands/:land_id/profile?language=en-US

• :land_id: land id

Response:

{
        // unsure, was 30723
	"mVer": number,
        // en-US
	"mLanguage": string,
       // unsure, was 2
	"mVRuby": number,
       // island name
	"mVNm": string,
         // island native fruit
	"mFruit": {
                 // fruit id?
		"id": number,
                 // fruit name - mine was "Peaches"
		"name": string
	},
         // animal villagers
	"mNormalNpc": [{
		"name": "Renée",
		"image": "...",
		"birthMonth": 5,
		"birthDay": 28
	}],
        // active non-npcs on the island?
       // the only entry was my char, but I did not have any visitors at this time
	"mVillager": [{
                 // my character's name
		"mPNm": string,
                 // my character's passport photo
		"mJpeg": string,
                 // character id
		"userId": number
	}]
}

[frozenpandaman]

cc @Thulinma who will find the above helpful :)

[Thulinma]

perks up
Oooh, useful indeed! Has anyone taken a look at the pattern upload stuff yet?

[theogravity]

Here are some other endpoints that I noticed were different from the Splatoon 2 one:

Base Url: https://api-lp1.znc.srv.nintendo.net

Register Device

edit: There's a reference for this endpoint already:

https://github.com/ZekeSnider/NintendoSwitchRESTAPI/blob/master/SwitchBlueprint.md#register-device-v1notificationregisterdevice

Get web service token v2

Headers:

• Authorization: Bearer <access token from webApiServerCredential from /v1/Account/login>
• X-ProductVersion: 1.6.1.2
• X-Platform: iOS
• User-Agent: com.nintendo.znca/1.6.1.2 (iOS/13.4)
• Accept-Language: en-us
• Content-Type: application/json; charset=utf-8
• Accept: application/json

Method: POST
Path: /v2/Game/GetWebServiceToken

Input:

{
	"parameter": {
                 // game id?
		"id": number,
                 // registration token from /v1/Notification/RegisterDevice
		"registrationToken": string,
                 // not sure how it's generated, value is in form of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
		"requestId": string,
                 // timestamp in ms when the request is to be made?
		"timestamp": number,
                 // unsure, some kind of checksum?
                // noticed its also found in /v1/Account/Login input, but the value is different
		"f": string
	}
}

For the "f" param - see this issue on what it is - the method of generation may differ compared to what is done with Splatoon, though:

#6

Response:

{
	"result": {
                 // JWT value
		"accessToken": string,
                 // expires in seconds, was 7200
		"expiresIn": number
	},
         // some kind of id used for logging maybe?
	"correlationId": string,
         // status value was 0
	"status": number
}

[Thulinma]

Ooooh. They left sourcemaps in. You can see the entire source code. 🤤

[Thulinma]

I will leave this here for others to play with.
BlancoClient.txt

[frozenpandaman]

cc @cgbuen as well (you had reached out to me about this in part)

[cgbuen]

For the "f" param - see this issue on what it is - the method of generation may differ compared to what is done with Splatoon, though

Everything up to and including GetWebServiceToken is fortunately exactly the same with Splatoon. The way it gets used once you get to the ACNH-specific address (web.sd.lp1.acbaa.srv.nintendo.net) is a bit different though.

A few notes for what I had found (particularly about auth / passport / keyboard):

1. It's more appropriate now than ever to use @frozenpandaman 's s2s / Nexus's flapg to gather your WebServiceToken, which would be used to refresh the ACNH-specific access token (from the auth_token endpoint), since it expires every 2 hours. (I say this as opposed to the option of using an MitM proxy to pick off the access token, as I used to for Splatoon's iksm cookie, since its 3-day expiration was seldom enough for me.)
2. There's a tiny gotcha in the passport endpoint data:
   • /api/sd/v1/users contains user IDs + island IDs
   • /api/sd/v1/lands/${islandId}/profile contains island info, including the list of user IDs
   • /api/sd/v1/users/${userId}/profile contains user info, but not the island ID that the user belongs to
3. The keyboard is pretty interesting:
   • In the game and in the app, it appears that there are validations to ensure a "fluid" max character limit, i.e. your message has to literally look like it fits in the in-game / in-app keyboard message boxes (given that the ACNH fonts used are not monospace). However, this validation is only on the front end - so if you're using the POST endpoint for it, the hard max is actually 32 (it responds with an error if you go over). Meaning there are certain cases where you can actually have "longer" messages than what's allowed in-game/in-app.
   • For example, you can only type in "123456789012345678901234" (length 24) in-game/in-app, but you can actually POST "12345678901234567890123456789012" (length 32) programmatically.. what ends up happening in-game is that it condenses/squishes the text so that the message fits inside the message box.
   • Odd symbols will respond with a success (so long as the message length is <= 32), some of which will even display fine on-screen. I've even tried that creepy Zalgo text and nothing fully broke (still got a successful response), but it came on-screen as mostly question marks and line breaks that pushed the question marks outside of the message box.
   • There are in-game moments when you POST keyboard data and you won't see a speech bubble and instead get a no-keyboard symbol in the upper left, but this was evident even non-programmatically (e.g. you can just try sending an app message when exiting through a doorway). It should still appear in your in-game message history though.
4. Personally haven't touched any of the other app features (best friends, patterns, etc.) yet, but the BlancoClient.txt file that @Thulinma posted above looks helpful.
5. Here are my resources:
   • ACNH-specific endpoint requests, including auth
   • Implementation for getting WebServiceTokens using s2s / flapg

[theogravity]

I'm really stoked that this thread has gotten so many contributions in such a short period of time! Thanks everyone.

Re: GetWebServiceToken

For GetWebServiceToken, the interface and route is is different.

According to this:
https://github.com/ZekeSnider/NintendoSwitchRESTAPI/blob/master/Splatoon2Blueprint.md#-get-homepage-get

Splatoon calls /v1/Game/GetWebServiceToken

But, AC is calling /v2/GameGetWebServiceToken with a different input.

Unless you mean it's still valid to call the v1 endpoint and use the token value for the subsequent calls

[cgbuen]

@theogravity It looks like that documentation may not be up-to-date (blame/history shows those sections were written in mid-2017).

The app currently (at the time of this writing) calls /v2/Game/GetWebServiceToken for both Splatoon and ACNH, with the following request body:

{
  id: [identifier for either Splatoon or ACNH as it appears from /v1/Game/ListWebServices],
  registrationToken: [value generated by app; corresponds with "p1" from 2nd flapg "app" call],
  timestamp: [value generated by app; corresponds with "p2" from 2nd flapg "app" call, which was passed through as an input into the flapg call],
  requestId: [value generated by app; corresponds with "p3" from 2nd flapg "app" call, which was passed through as an input into the flapg call],
  f: [value generated by app; corresponds with "f" from 2nd flapg "app" call]
}

[xSke]

Played around with this a bit - seems like they're pretty solid at authorization. You can only access your own or your best friends' passport/profile data, and you can only access your own island data. Your friends' island IDs are listed in the /friends endpoint, but looking them up gets you a 403.

As for those APIs:

GET https://web.sd.lp1.acbaa.srv.nintendo.net/api/sd/v1/friends

{
  "friends": [{
    "userId": "[ID of friend, this CAN be looked up at /users/<id>/profile]",
    "name": "[name of friend]",
    "image": "[URL to passport photo]",
    "land": {
      "id": "[ID of their island, this can't be looked up]",
      "name": "[name of their island]",
      "displayId": 2
    }
  }, { ... }]
}

This will only return "best" friends, not your full friend list. Unsure what land.displayId is, it's 2 for every friend on my end too.

---

GET https://web.sd.lp1.acbaa.srv.nintendo.net/api/sd/v1/friends/presences

{
  "presences": [{
    "userId": "[user ID of friend]",
    "state": 2
  }]
}

"State" here is the friend's online status - 1 is online, 2 is away, 0 is offline (but offline friends aren't included in the response).

Both require Authorization: Bearer <token> header, with the token from /auth_token. No HTTP bodies or any other query parameters.

[xSke]

Here's a working example of a Python script that hits all of the above APIs and prints information it can access, going through the entire login process automatically given an OAuth redirect URL: https://gist.github.com/xSke/8a4f06f9499a17b3e28cedfc094f57ca

[frozenpandaman]

@xSke Looks great, nice! To answer your comment there:

# I'm not entirely sure what this API does but it gets you a code that you need to move on.

You can find the documentation here: https://github.com/frozenpandaman/splatnet2statink/wiki/api-docs

As splatnet2statink is open-source, when the NSO app became necessary to emulate via an Android server (which NexusMine's flapg API is used for interacting with), we thought it'd be best to keep any sensitive hash-generation functionality (originally done on Nintendo's end) behind an API for the sake of privacy/security. So now the two APIs are used in conjunction. :)

We originally developed these for Splatoon 2 (plus, this was the only game originally integrated with the NSO app) but I'm fine with usage for cool ACNH stuff as well (but it might be helpful to have users specify which service/game you're using it for now, hmm… maybe just another optional parameter would be best for backwards compatibility). I can reach out to NexusMine about this as well (and link this thread) just as a heads up depending on what people intend to build with this.

[xSke]

@frozenpandaman Can you explain what that hash your API generates is for? On the app's end it goes directly from the token/request ID/timestamp to the f parameter and doesn't involve an intermediate step, how come the hash is necessary, and how come it can't be generated locally rather than through your API?

Also, do you know what progress has been made on understanding f parameter generation in the app (libvoip.so/gen_audio_h)? I'm messing with it myself and it's... a tough one, for sure. Could you just run the function in isolation without pulling in the rest of the app?

[giraffesyo]

Hi guys, I'd love to get involved in any of the projects you have in mind for ACNH. If you are working on something and need additional help lets get in contact!