pogobuf, a Pokémon Go Client Library for node.js

Features

• Implements all known Pokémon Go API calls
• Uses ES6 Promises and Bluebird
• Includes Pokémon Trainer Club and Google login clients
• Optional batch mode to group several requests in one RPC call
• Automatic request throttling

Acknowledgements

• Uses the excellent POGOProtos (via node-pogo-protos)
• Based on prior work by tejado and others

Usage

Installation

npm install pogobuf --save

Basic Usage

Generally, every method that makes an API call returns an ES6 Promise that will be resolved with the response message object (or true if there was no response message).

Before using a pogobuf.Client instance to make API calls you need to supply it with an auth token (which you can get from the pogobuf.PTCLogin or pogobuf.GoogleLogin class) and call init() to make an initial request.

Example usage with PTC login:

const pogobuf = require('pogobuf');

var login = new pogobuf.PTCLogin(),
    client = new pogobuf.Client();

login.login('username', 'password')
.then(token => {
    client.setAuthInfo('ptc', token);
    client.setPosition(lat, lng);
    return client.init();
}).then(() => {
    // Make some API calls!
    return client.getInventory(0);
}).then(inventory => {
    // Use the returned data
});

Example usage with Google login:

const pogobuf = require('pogobuf');

var login = new pogobuf.GoogleLogin(),
    client = new pogobuf.Client();

login.login('username', 'password')
.then(token => {
    client.setAuthInfo('google', token);
    client.setPosition(lat, lng);
    return client.init();
}).then(() => {
    // Make some API calls!
    return client.getInventory(0);
}).then(inventory => {
    // Use the returned data
});

For more details, see the API documentation below or the example scripts.

Batch mode

The Pokémon Go API offers the ability to send multiple requests in one call. To do this you can use pogobuf's batch mode:

First call batchStart() to enable batch mode. When in batch mode, all API request methods will append the request to the current batch instead of immediately sending it to the server. Once you have all your requests, call batchCall() which submits them to the server, disables batch mode, and returns a Promise that will be resolved with an array of response messages corresponding to your requests.

When in batch mode, all API request methods (as well as batchStart()) return the Client instance so you can chain them.

Example batch usage:

client.batchStart()
    .getPlayer()
    .getHatchedEggs()
    .getInventory(0)
    .batchCall()
    .then(responses => {
        // responses is: [GetPlayerResponse, GetHatchedEggsResponse, GetInventoryResponse]
    });

API documentation

pogobuf.Client methods

setAuthInfo(authType, authToken)

Sets the authentication type and token (required before making API calls).

Param	Type	Description
authType	string	Authentication provider type (ptc or google)
authToken	string	Authentication token received from authentication provider

setPosition(latitude, longitude, [altitude])

Sets the player's latitude and longitude. Note that this does not actually update the player location on the server, it only sets the location to be used in following API calls. To update the location on the server you probably want to call updatePlayer.

Param	Type	Description
latitude	number	The player's latitude
longitude	number	The player's longitude
altitude	number	The player's altitude (optional)

init() ⇒ Promise

Performs the initial API call.

batchStart() ⇒ Client

Sets batch mode. All further API requests will be held and executed in one RPC call when batchCall is called.

batchClear()

Clears the list of batched requests and aborts batch mode.

batchCall() ⇒ Promise

Executes any batched requests.

setThrottleDelay(delayMs)

Sets the minimum time between API requests (500 ms by default).

Param	Type	Description
delayMs	integer	Time in ms, or 0 to turn off throttling

setProxy(proxy)

Sets a proxy address to use for the HTTPS RPC requests.

Param	Type
proxy	string

pogobuf.Client Pokémon Go API methods

addFortModifier(modifierItemID, fortID) ⇒ Promise

attackGym(gymID, battleID, attackActions, lastRetrievedAction) ⇒ Promise

catchPokemon(encounterID, pokeballItemID, normalizedReticleSize, spawnPointID, hitPokemon, spinModifier, normalizedHitPosition) ⇒ Promise

checkAwardedBadges() ⇒ Promise

checkCodenameAvailable(codename) ⇒ Promise

claimCodename(codename) ⇒ Promise

collectDailyBonus() ⇒ Promise

collectDailyDefenderBonus() ⇒ Promise

diskEncounter(encounterID, fortID) ⇒ Promise

downloadItemTemplates() ⇒ Promise

downloadRemoteConfigVersion(platform, deviceManufacturer, deviceModel, locale, appVersion) ⇒ Promise

downloadSettings(hash) ⇒ Promise

echo() ⇒ Promise

encounter(encounterID, spawnPointID) ⇒ Promise

encounterTutorialComplete(pokemonID) ⇒ Promise

equipBadge(badgeType) ⇒ Promise

evolvePokemon(pokemonID) ⇒ Promise

fortDeployPokemon(fortID, pokemonID) ⇒ Promise

fortDetails(fortID, fortLatitude, fortLongitude) ⇒ Promise

fortRecallPokemon(fortID, pokemonID) ⇒ Promise

fortSearch(fortID, fortLatitude, fortLongitude) ⇒ Promise

getAssetDigest(platform, deviceManufacturer, deviceModel, locale, appVersion) ⇒ Promise

getDownloadURLs(assetIDs) ⇒ Promise

getGymDetails(gymID, gymLatitude, gymLongitude) ⇒ Promise

getHatchedEggs() ⇒ Promise

getIncensePokemon() ⇒ Promise

getInventory(lastTimestamp) ⇒ Promise

getMapObjects(cellIDs, sinceTimestamps) ⇒ Promise

getPlayer() ⇒ Promise

getPlayerProfile(playerName) ⇒ Promise

getSuggestedCodenames() ⇒ Promise

incenseEncounter(encounterID, encounterLocation) ⇒ Promise

levelUpRewards(level) ⇒ Promise

markTutorialComplete(tutorialsCompleted, sendMarketingEmails, sendPushNotifications) ⇒ Promise

nicknamePokemon(pokemonID, nickname) ⇒ Promise

playerUpdate() ⇒ Promise

recycleInventoryItem(itemID, count) ⇒ Promise

releasePokemon(pokemonID) ⇒ Promise

setAvatar(skin, hair, shirt, pants, hat, shoes, gender, eyes, backpack) ⇒ Promise

setContactSettings(sendMarketingEmails, sendPushNotifications) ⇒ Promise

setFavoritePokemon(pokemonID, isFavorite) ⇒ Promise

setPlayerTeam(teamColor) ⇒ Promise

sfidaActionLog() ⇒ Promise

startGymBattle(gymID, attackingPokemonIDs, defendingPokemonID) ⇒ Promise

upgradePokemon(pokemonID) ⇒ Promise

useIncense(itemID) ⇒ Promise

useItemCapture(itemID, encounterID, spawnPointID) ⇒ Promise

useItemEggIncubator(itemID, pokemonID) ⇒ Promise

useItemGym(itemID, gymID) ⇒ Promise

useItemPotion(itemID, pokemonID) ⇒ Promise

useItemRevive(itemID, pokemonID) ⇒ Promise

useItemXPBoost(itemID) ⇒ Promise

pogobuf.Client Events

The Client class is an EventEmitter that emits the following events (mostly for debugging purposes):

request(requestData)

Fires while building a RPC request envelope with subrequests.

Example requestData structure:

{
    request_id: 8145806132888207000,
    requests: [
        {
            name: 'Get Inventory',
            type: 4,
            data: {
                last_timestamp_ms: 0
            }
        }
    ]
}

raw-request(envelopeData)

Fires after building an RPC request envelope, just before it is encoded into a protobuf RequestEnvelope.

response(responseData)

Fires after receiving and successfully decoding an RPC request, just before the Promise is resolved.

Example responseData structure:

{
    status_code: 1,
    request_id: '8145806132888207360',
    responses: [
        {
            name: 'Get Inventory',
            type: 4,
            data: {
                /* inventory data */
            }
        }
    ]
}

endpoint-response(responseData)

Fires after the initial RPC response (including the URL of the endpoint to use for all further requests) has been received and decoded.

Example responeData structure:

{
    status_code: 53,
    request_id: '8145806132888207360',
    api_url: 'pgorelease.nianticlabs.com/plfe/403'
}

raw-response(responseEnvelope)

Fires when a RPC ResponseEnvelope has been received, just after it has been decoded.

parse-envelope-error(rawEnvelopeBuffer, error)

Fires when the RequestEnvelope structure could not be parsed (possibly due to erroneous .proto files). Can be used to dump out the raw protobuf response and debug using protoc.

parse-response-error(rawResponseBuffer, error)

Fires when one of the response messages received in an RPC response envelope could not be parsed (possibly due to erroneous .proto files). Can be used to dump out the raw protobuf response and debug using protoc.

pogobuf.GoogleLogin methods

login(username, password) ⇒ Promise

Performs the Google login process and returns a Promise that will be resolved with the auth token.

Param	Type
username	string
password	string

loginWithToken(username, token) ⇒ Promise

Performs the Google login by skipping the password step and starting with the Master Token instead. Returns a Promise that will be resolved with the auth token.

Param	Type
username	string
token	string

pogobuf.PTCLogin methods

login(username, password) ⇒ Promise

Performs the PTC login process and returns a Promise that will be resolved with the auth token.

Param	Type
username	string
password	string

pogobuf.Utils methods

getCellIDs(lat, lng, [radius]) ⇒ array (static)

Provides cell IDs of nearby cells based on the given coords and radius.

Param	Type	Description
lat	number	Latitude
lng	number	Longitude
radius	number	Radius of the square (optional)

splitInventory(inventory) ⇒ object (static)

Takes a getInventory() response and separates it into pokemon, items, candies, player data, eggs, and pokedex.

Param	Type	Description
inventory	object	API response message as returned by getInventory()

splitItemTemplates(templates) ⇒ object (static)

Takes a downloadItemTemplates() response and separates it into the individual settings objects. data, eggs, and pokedex.

Param	Type	Description
templates	object	API response message as returned by downloadItemTemplates()

getEnumKeyByValue(enumObj, val) ⇒ string (static)

Utility method that finds the name of the key for a given enum value and makes it look a little nicer.

Param	Type
enumObj	object
val	number

getIVsFromPokemon(pokemon) ⇒ object (static)

Utility method to get the Individual Values from Pokémon

Param	Type	Description
pokemon	object	A pokemon_data structure