View Project


Pokemon GO Java API

Build Status

Javadocs : CLICK ME

See this guide for adding functionality:

See this spreadsheet for RPC endpoints and progress :

:exclamation: :exclamation: :exclamation:

This API may have issues when the PokemonGO servers are under high load or down, in this case please wait for the official to get back up. You can check the official servers status on or

This API doesnt fake the official client perfectly, niantic may know that you aren't using the official app, we encourage you to use an alternate account to play with this API.

If you are using this lib to catch pokemon and loot pokestop, take care that you aren't teleporting, the servers may issue a softban against your client (its temporary, between 10 and 30 minutes in general).

:exclamation: :exclamation: :exclamation:

How to import

allprojects {
  repositories {

dependencies {
  compile 'com.pokegoapi:PokeGOAPI-library:0.X.X'

Replace X.X with the version below: Download


Import JAR with gradle


Import JAR in Eclipse

Build from source

PS : for users who want to import the api into Eclipse IDE, you'll need to :

Usage example (mostly how to login) :

OkHttpClient httpClient = new OkHttpClient();

* Google: 
* You will need to redirect your user to GoogleUserCredentialProvider.LOGIN_URL
* Afer this, the user must signin on google and get the token that will be show to him.
* This token will need to be put as argument to login.
GoogleUserCredentialProvider provider = new GoogleUserCredentialProvider(httpClient);

// in this url, you will get a code for the google account that is logged
System.out.println("Please go to " + GoogleUserCredentialProvider.LOGIN_URL);
System.out.println("Enter authorization code:");
// Ask the user to enter it in the standard input
Scanner sc = new Scanner(;
String access = sc.nextLine();
// we should be able to login with this token
PokemonGo go = new PokemonGo(httpClient);

* After this, if you do not want to re-authorize the google account every time, 
* you will need to store the refresh_token that you can get the first time with provider.getRefreshToken()
* ! The API does not store the refresh token for you !
* log in using the refresh token like this :
PokemonGo go = new PokemonGo(httpClient);
go.login(new GoogleUserCredentialProvider(httpClient, refreshToken));

* PTC is much simpler, but less secure.
* You will need the username and password for each user log in
* This account does not currently support a refresh_token. 
* Example log in :
PokemonGo go = new PokemonGo(httpClient);
go.login(new PtcCredentialProvider(httpClient, username, password));

// After this you can access the api from the PokemonGo instance :
go.getPlayerProfile(); // to get the user profile
go.getInventories(); // to get all his inventories (Pokemon, backpack, egg, incubator)
go.setLocation(lat, long, alt); // set your position to get stuff around (altitude is not needed, you can use 1 for example)
go.getMap().getCatchablePokemon(); // get all currently Catchable Pokemon around you

// If you want to go deeper, you can directly send your request with our RequestHandler
// For example, here we are sending a request to get the award for our level
// This applies to any method defined in the protos file as Request/Response)

LevelUpRewardsMessage msg = LevelUpRewardsMessage.newBuilder().setLevel(yourLVL).build(); 
ServerRequest serverRequest = new ServerRequest(RequestType.LEVEL_UP_REWARDS, msg);

// and get the response like this :

LevelUpRewardsResponse response = null;
try {
    response = LevelUpRewardsResponse.parseFrom(serverRequest.getData());
} catch (InvalidProtocolBufferException e) {
    // its possible that the parsing fail when servers are in high load for example.
    throw new RemoteServerException(e);


Parameters for a capture now use a CatchOptions or AsyncCatchOptions object

This object allows setting all parameters at once, or modifying them on-the-fly

import com.pokegoapi.api.settings.AsyncCatchOptions;


import com.pokegoapi.api.settings.CatchOptions;


CatchOptions options = new CatchOptions(go);



AsyncCatchOptions options = new AsyncCatchOptions(go);


Each option has a default and the most relevant option will override others with similar functionality (for example, usePokeBall will set the minimum of useBestBall, a maximum by using it alone, or the specific value with noFallback). See the javadocs for more info.

##Android Dev FAQ

You're running the sample code on the UI thread. Strict mode policy will throw an exception in that case and its being caught by the network client and treating it as a login failed exception. Run the sample code on a background thread in AsyncTask or RXJava and it will work.

This library is meant to be a Java implementation of the API. Google Volley is specific to Android and should not be introduced in this library. However, if you still want to refactor it, you should create it as a separate project.

You can't. The Google Identity Platform uses the SHA1 fingerprint and package name to authenticate the caller of all sign in requests. This means that Niantic would need to add your app's SHA1 fingerprint and package name to their Google API Console. If you ever requested a Google Maps API key, you went through the same process. An alternative would be using a WebView to access the web based OAuth flow. This will work with the client ID and secret provided by this library.



You can join us in the slack channel #javaapi on the (you can get invited here)


Languages used: Java