Poke API - A Ruby API gem for Pokémon GO.

Poke API is a port for Ruby from pgoapi and also allows for any automatic parsing of a requests and responses.

Unofficial, please use at your own RISK.
Use a throwaway account if possible.

Features

Supports new SIGNATURE generation!
Allows you to set optional signature information for every request (:android_gps_info, :sensor_info, :device_info,:activity_status and :location_fix)
Proxy support!
Automatic access token/ticket refresh upon expiry!
S2 Geometry cells are now supported (natively)!
PTC & Google Authentication supported (use full e-mail address for Google)
Google refresh token support
Parses geolocation using Geocoder (parses addresses, postcodes, ip addresses, lat/long, etc)
Ability to chain requests and receive response in a single call
Logger available, you can also specify your own log formatter and/or log level
Lots of RPC calls, they are listed under lib/poke-api/pogoprotos/pogoprotos_networking_requests.rb

Installation

You can use bundler and refer directly to this repository

gem 'poke-go-api',
    git: "https://github.com/nabeelamjad/poke-api.git",
    tag: '0.2.1'

Or, alternatively you can download the repository and run gem build poke-api.gemspec followed with gem install poke-api-0.2.1.gem

The gem is also available by using gem install poke-go-api (poke-api was taken as a name already).

NOTE - This gem relies on header files for Ruby to install the google-protobuf gem.

Windows: You will need the Ruby DevKit applied to your Ruby, please see RubyInstaller
Linux:
- Debian based: sudo apt-get install ruby-dev
- RPM based: sudo yum install ruby-devel
- SuSe based: sudo zypper install ruby-devel

Example Usage

Running provided example.rb with your own credentials

2016-08-09T02:54:03+01:00]: INFO  > Poke::API::Client         --: [+] Given location: New York, NY, USA
2016-08-09T02:54:03+01:00]: INFO  > Poke::API::Client         --: [+] Lat/Long: 40.7127837, -74.0059413
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Client         --: [+] Provider access token is valid for 03:00:00
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Adding 'GET_HATCHED_EGGS' to RPC request
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Using provider access token
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Executing RPC request
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Response       --: [+] Decoding Main RPC responses
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Response       --: [+] Using auth ticket instead
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Response       --: [+] Decoding Sub RPC responses
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Client         --: [+] Cleaning up RPC requests
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Client         --: [+] Login with PTC Successful
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Client         --: [+] File <<signature>> has been set for signature generation
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Adding 'GET_MAP_OBJECTS' to RPC request with ar ents
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Adding 'GET_PLAYER' to RPC request
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Adding 'GET_INVENTORY' to RPC request
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Auth::Ticket   --: [+] Auth ticket is valid for 00:30:01
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Signature      --: [+] Loaded Signature module
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::RequestBuilder --: [+] Executing RPC request
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Response       --: [+] Decoding Main RPC responses
2016-08-09T02:54:06+01:00]: INFO  > Poke::API::Response       --: [+] Decoding Sub RPC responses
2016-08-09T02:54:07+01:00]: INFO  > Poke::API::Client         --: [+] Cleaning up RPC requests
<Poke::API::Response:0x000000032f96a0
@request=
 [{:GET_MAP_OBJECTS=>
    {:latitude=>40.7127837,
     :longitude=>-74.0059413,
     :since_timestamp_ms=>
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
     :cell_id=>
      [9926595610352287744,
       9926595612499771392,
       9926595614647255040,
       9926595616794738688,
       9926595618942222336,
       9926595621089705984,
       9926595623237189632,
       9926595625384673280,
       9926595627532156928,
       9926595629679640576,
       9926595631827124224,
       9926595633974607872,
       9926595636122091520,
       9926595638269575168,
       9926595640417058816,
       9926595642564542464,
       9926595644712026112,
       9926595646859509760,
       9926595649006993408,
       9926595651154477056,
       9926595653301960704]}},
  :GET_PLAYER,
  :GET_INVENTORY],
@response=
 {:GET_MAP_OBJECTS=>
   {:map_cells=>
     [{:s2_cell_id=>9926595631827124224,
       :current_timestamp_ms=>1470707648730,
       :forts=>
        [{:id=>"44a31b1c990547f49537ca74617bf557.12",
          :last_modified_timestamp_ms=>1470707647002,
          :latitude=>40.712891,
          :longitude=>-74.004869,
          :owned_by_team=>:BLUE,
          :guard_pokemon_id=>:GYARADOS,
          :guard_pokemon_cp=>0,
          :enabled=>true,
          :type=>:GYM,
          :gym_points=>1604,
          :is_in_battle=>true,
          :active_fort_modifier=>"",
          :lure_info=>nil,
          :cooldown_complete_timestamp_ms=>0,
          :sponsor=>:UNSET_SPONSOR,
          :rendering_type=>:DEFAULT},
          ...

RPC call requests and responses

An RPC request can be made on its own or with multiple calls, it also provides the ability to specify arguments. You can find all the supported requests in lib/poke-api/pogoprotos/pogoprotos_networking_requests.rb. Please note that you will need to check if any of these requests require arguments, these can be found in lib/poke-api/pogoprotos/pogoprotos_networking_requests_messages.rb using the same naming convention.

Let's assume we want to delete a few great balls from our inventory
If you open Requests we can see that there's an entry for :RECYCLE_INVENTORY_ITEM. We now know that our call is recycle_inventory_item, next we have to find out if there're any arguments to this call. We can find any possible arguments inside Messages for our call. This shows two argments: item_id and count. Furthermore we can see that item_id directly links to POGOProtos.Inventory.Item.ItemId, this is a file you can open as well with the item ids specified inside. In here we can see the Item ID for a great ball is 2.

Our example request could be as follows:

require 'poke-api'

# Instantiate our client
client = Poke::API::Client.new

# Both PTC/Google available as authentication provider
client.store_location('New York')
client.login('username@gmail.com', 'password', 'google')

# Activate the encryption method to generate a signature (only required for map objects)
client.activate_signature('/path/to/encrypt/file')

# Add RPC calls
client.recycle_inventory_item(item_id: 2, count: 2)

# You can inspect the client before performing the call
puts client.inspect
=> #<Poke::API::Client @auth=#<Poke::API::Auth::GOOGLE> @reqs=[{:RECYCLE_INVENTORY_ITEM=>{:item_id=>2, :count=>2}}] @lat=4630926632231391130 @lng=13858280158942612615 @alt=0>

# Perform your RPC call
call = client.call

# A <Poke::API::Response> object is returned and decorated with your request and response in a Hash format
# Request
puts call.request.inspect
[
  {
    :RECYCLE_INVENTORY_ITEM => {
      :item_id=>2,
      :count=>2
    }
  }
]

# Response
puts call.response.inspect
{
  :RECYCLE_INVENTORY_ITEM = >{
    :result=>:SUCCESS, 
    :new_count=>14
  },
  :status_code => 1,
  :api_url => "",
  :error => ""
}

Optional Signature Information

You can specify :android_gps_info, :sensor_info, :device_info,:activity_status and :location_fix for every request that is made. Here's an example how this is possible:

require 'poke-api'

client = Poke::API::Client.new
client.activate_signature('/path/to/encrypt/file')
client.store_location('New York')
client.login('username', 'password', 'ptc')

# Set your optional requests here
client.location_fix = {provider: 'foo'}
client.android_gps_info = {satellites_prn: [1]}
client.sensor_info = {magnetometer_x: 1.2}
client.device_info = {device_model: 'some-device'}
client.activity_status = {cycling: false}

cell_ids = Poke::API::Helpers.get_cells(client.lat, client.lng)

client.get_map_objects(
  latitude: client.lat,
  longitude: client.lng,
  since_timestamp_ms: [0] * cell_ids.length,
  cell_id: cell_ids
)

client.call

Please refer to networking_envelopes for more information as to which arguments are supported.

Google Refresh Token

A Google refresh token can be set on Poke::API::Client, this token will automatically be used first to generate an access token if available. You do not need to pass in any username or password if you provide a refresh token. To support backwards compatibility you will still have to call client.login('', '', 'google'), however, you can leave the username and password as blank strings instead.

require 'poke-api'

client = Poke::API::Client.new
client.refresh_token = 'my-refresh-token'
client.login('', '', 'google')

In a future revamp release the login method will change to accept keyword arguments such as client.login(provider: 'google') allowing you to ignore the rest.

To generate a Google refresh token please have a look at this issue, a refresh token will last indefinitely.

Proxy support

If you wish to use a proxy then you can do so by providing your own HTTPClient instantation with your preferred setup to Poke::API::Client using http_client setter/getter.

require 'poke-api'

client = Poke::API::Client.new
client.http_client = HTTPClient.new('http://localhost:8080')
client.http_client.set_proxy_auth(user, password)
...
# Proceed as normal

Logger settings

If you wish to change the log level you can do so before instantiating the client by using Poke::API::Logging.log_level = :INFO where :INFO is the desired level, possible values are: :DEBUG, :INFO, :WARN, :FATAL and UNKNOWN

The log formatter format can also be customised, a default one is provided. You can provide a proc to Poke::API::Logging.formatter to change it. More information can be found at Class#Logger

Example:

require 'poke-api'

# Use :DEBUG for extra verbosity if required to troubleshoot
Poke::API::Logging.log_level = :DEBUG
Poke::API::Logging.formatter = proc do |severity, datetime, progname, msg|
  "My custom logger - #{msg}\n"
end

client = Poke::API::Client.new
client.store_location('London')
#=> My custom logger - [+] Given location: London, UK
#=> My custom logger - [+] Lat/Long: 51.5073509, -0.1277583

Generating S2 Cell Ids

You can use this helper method to generate cells, please note that not all S2 Geometry calls are supported as this has been ported over to native Ruby (without binding). Available instance methods on a S2CellId are parent, level, next and prev.

Example Usage

require 'poke-api'

client = Poke::API::Client.new
client.store_location('New York')

[2016-08-09T02:52:10+01:00]: INFO  > Poke::API::Client         --: [+] Given location: New York, NY, USA
[2016-08-09T02:52:10+01:00]: INFO  > Poke::API::Client         --: [+] Lat/Long: 40.7127837, -74.0059413

Poke::API::Helpers.get_cells(client.lat, client.lng)
=> [9926595610352287744, 9926595612499771392, 9926595614647255040,
    9926595616794738688, 9926595618942222336, 9926595621089705984,
    9926595623237189632, 9926595625384673280, 9926595627532156928, 
    9926595629679640576, 9926595631827124224, 9926595633974607872, 
    9926595636122091520, 9926595638269575168, 9926595640417058816, 
    9926595642564542464, 9926595644712026112, 9926595646859509760, 
    9926595649006993408, 9926595651154477056, 9926595653301960704]

Contribution

Any contributions are most welcome, I don't have much time to spend on this project so I appreciate everything.

Credits

tejado - Pretty much everything as this repository is a direct 'conversion' to the best of my ability
AeonLucid - Protobufs
xssc - GPSOauth (Google Login)

poke-go-api

Runtime

Poke API - A Ruby API gem for Pokémon GO.

Features

Installation

Example Usage

RPC call requests and responses

Optional Signature Information

Google Refresh Token

Proxy support

Logger settings

Generating S2 Cell Ids

Example Usage

Contribution

Credits