Using the Pokemon Go API

What is the Pokemon Go API?

The Pokemon Go API is the way that the Pokemon Go app communicates with the servers to send and receive data about the locations, items, players and pokemon in the game.

It's built on Protocol Buffers, a Google solution to serialising data. The raw .protos used by the API are available via AeonLucid's Github repo

The API itself is a wrapper around the .protos written by Tejado that allow for operations such as logging in, getting player information and pokemon easier.

The version I use is written in Python (as I prefer this language) although at the time of writing there are versions for Node.Js and C#.

What are the implications of using the API?

As the API is an unofficial one it's hard to say if there will be any implications for using the API.

Getting data out of Pokemon Go

Getting information from Pokemon Go requires the following steps:

  1. Login with a valid Pokemon Go account via Google or the Pokemon Trainer Club (The API supports both)
  2. Setup the API calls to be carried out
  3. Call the API calls and store the return dictionaries
  4. Do what you want with the returned data

Logging in

As mentioned, the Pokemon Go API supports both Google and Pokemon Trainer Club logins. This means along with the username and password you must also pass along the account type so it authenticates with the correct provider.

Once you have the needed information logging in is as simple as:

auth_type = 'google'  # or 'ptc' for Pokemon Trainer Club
username = 'email@gmail.com'  # or Pokemon Trainer Club username
password = 'password'
api = pgoapi.PGoApi()
if api.login(auth_type, username, password):
    # Do some foo, we can use if as api.login returns a boolean

It's worth noting that the values sent to api.login must be instances of str as it will raise an error if it receives unicode strings, e.g. u'password' will not work.

This was a gotcha I experienced when building my Pokemon Go Trainer Card web app as Flask would return unicode values from form submissions.

Setting up the API calls

Once the PGoAPI instance has been logged in we can set up some API calls. There are functions on the API object such as get_player() or get_inventory().

These functions can be chained so we only hit the server once to get data off the server instead of calling it every time we want data.

There are a number of calls available via the API, essentially if you lowercase the items on this API call list then you can add it to you API call chain.

Calling the API calls

After we've setup the chain of API calls we want to make the call to the server. This is done via the call() method on the API object.

Data returned by the API

The data comes back as a dictionary in the following structure:

{
    'auth_ticket': {}, // this is the authentication info
    'responses: {
        'GET_PLAYER': {} // or whatever API call you set up
    },
    'status_code': 2, // status of the call, 2 means it was successful
    'request_id': 012312411L,  // this the ID of the call to the server
    'api_url': 'pgorelease.niantic.com/plfr/420', // The endpoint used
}

Each endpoint will return it's own dictionary format so it's worth reading the POGOProtos repo to figure out how to get the data.

For example to get the player data you'll need to do:

api_call = api.get_player().call()
player_data = api_call.get('responses').get('GET_PLAYER').get('player_data')

So what can I do with the API?

There's a number of applications that can be made with the API; Some people have made spawn maps based on the location you enter and I made a web app to turn your player profile into a trainer card from Pokemon Red and Blue.

You can read the source code of my trainer card app on my Github.

I'm sure in the next few months we'll see an explosion of bots and other automated solutions popup as the ecosystem around Pokemon Go evolves and I'm hoping that an official API will be made available to developers so we can build these applications without knowing if we'll be on the receiving end of a take down notice any day soon.

What I would like from an official API

Currently, getting data about the player requires the user themselves to be logged in. As far as I can see there is no existing method to provide the API with a username and get details on the player.

This means that people will have to give up their details to use services like my trainer card app to use them, while I don't store this information on my app it's still a risk that most people aren't willing to take which stifles the creation of apps that repurpose this data in creative ways.

In a similar fashion getting information on Gyms, Pokemon and the like would also be a great resource to create a ecosystem of apps around.

Conclusion

The Pokemon Go API is a really cool wrapper around the Protocol Buffers used in the Pokemon Go app and you can create some really cool stuff with it, but until Niantic give developers the ability to get this data via an official API it's unknown how long the apps using this unofficial API will last.