A python wrapper for the PUBG developer API
Project description
pubg-python
A python wrapper for the PUBG Developer API
PUBG Developer API Official Documentation
Installation
To install the wrapper, simply use pip
pip install pubg-python
or pipenv
pipenv install pubg-python
Usage
Specifying a shard
The PUBG API shards data by platform and region, and therefore requires a shard to be specified in the URL for most requests.
from pubg_python import PUBG, Shard api = PUBG('<api-key>', Shard.PC_NA)
A list of shards can be found here and the wrapper constants here
Samples
- Samples
A sample of matches can be retrieved as a starting point
sample = api.samples().get() for match in sample.matches: print(match.id)
Samples can also be filtered by a creation date
sample = api.samples().filter(created_at_start='2018-01-01T00:00:00Z').get() for match in sample.matches: print(match.id)
Players
- Players
Retrieving a single player
player = api.players().get('account.3654e255b77b409e87b10dcb086ab00d') for match in player.matches: match_data = api.matches().get(match.id)
Retrieving a list of players filtering by names
players = api.players().filter(player_names=['Name1', 'Name2']) for player in players: player_id = player.id
Retrieving a list of players filtering by ids
players = api.players().filter(player_ids=['account.3654e255b77b409e87b10dcb086ab00d']) for player in players: player_name = player.name
Matches
- Matches
Retrieving a single match
match = api.matches().get('276f5bcb-a831-4e8c-a610-d2073692069e')
Retrieving a list of matches filtering by ids
Still unavailable in the API
match_ids = [ '276f5bcb-a831-4e8c-a610-d2073692069e', 'fasf9082-21de-dkle-13ke-qlamd13nab3a', ] matches = api.matches().filter(match_ids=match_ids) for match in matches: print(match)
Telemetry
- Telemetry events
- Event objects
Processing a match Telemetry data
match = api.matches().get('276f5bcb-a831-4e8c-a610-d2073692069e') asset = match.assets[0] telemetry = api.telemetry(asset.url) print(len(telemetry.events)) >> 16871
Filtering specific events in a telemetry object
Sometimes you're interested in a set of very specific events, so there is a helper function to filter those for you:
match = api.matches().get('276f5bcb-a831-4e8c-a610-d2073692069e') asset = match.assets[0] telemetry = api.telemetry(asset.url) player_kill_events = telemetry.events_from_type('LogPlayerKill') player_position_events = telemetry.events_from_type('LogPlayerPosition')
Loading a local Telemetry file
If you want to load a previously downloaded telemetry file, there is a helper method to create a Telemetry object from it:
from pubg_python import Telemetry telemetry = Telemetry.from_json('telemetry.json', shard='pc')
shard
defaults to pc
but you need to specify if you're loading a xbox
telemetry file.
Tournaments
- Tournaments
Retrieving a single tournament
tournament = api.tournaments().get('na-ppc')
Retrieving a list of tournaments
tournaments = api.tournaments() for tournament in tournaments: print(tournament)
Seasons
- Seasons
Retrieving the list of seasons
seasons = api.seasons()
Retrieving seasons information for a list of players
players_seasons = api.seasons( season_id='division.bro.official.2018-09', game_mode='solo' ).filter(player_ids=['epickitten'])
It's also possible to retrieve lifetime stats, instead of a season_id:
players_seasons = api.seasons( season_id='lifetime', game_mode='solo' ).filter(player_ids=['epickitten'])
Retrieving season data for a specific player
season_data = api.seasons( 'division.bro.official.2018-09' , player_id='epickitten').get()
It's also possible to retrieve lifetime stats, instead of a season_id:
season_data = api.seasons( 'lifetime' , player_id='epickitten').get()
Weapon Mastery
- Weapon Mastery
Retrieving a weapon mastery data
players = api.players().filter(player_names=['epickitten'])[0] player = players[0] wm = api.weapon_mastery(player.id).get() print(wm.weapon_summaries)
Leaderboards
- Leaderboards
Retrieving a leaderboard
# Leaderboards stats are only available for PC players api.shard = Shard.STEAM solo_leaderboard = api.leaderboards(game_mode='solo').page(0).get() solo_fpp_leaderboard = api.leaderboards(game_mode='solo-fpp').page(0).get() duo_leaderboard = api.leaderboards(game_mode='duo').page(0).get() duo_fpp_leaderboard = api.leaderboards(game_mode='duo-fpp').page(0).get() squad_leaderboard = api.leaderboards(game_mode='squad').page(0).get() squad_fpp_leaderboard = api.leaderboards(game_mode='squad-fpp').page(0).get()
page
is always required, even when querying the first leaderboard page.
Playing around with data
An example of how you can manipulate the data: The domain is all specified here
players = api.players().filter(player_names=['epickitten']) player = players[0] player.matches >> [<Match bd6aae34-be05-4094-981c-083285c7e861>, <Match 276f5bcb-a831-4e8c-a610-d2073692069e>, ..] match = api.matches().get(player.matches[0].id) match.game_mode >> 'solo' match.duration >> 1899 match.rosters >> [<Roster d542eaee-cd02-4f4e-ad7f-ed5ea71a17cf>, <Roster e9f0962a-ebd4-4d86-b134-95783b713800>, ..] roster = match.rosters[0] roster.participants >> [<Participant 7cc76d1b-a80e-4997-8eb8-d4b3c1ed4f44>] participant = roster.participans[0] participant.name >> 'urdaddyYO' participant.damage_dealt >> 291.08 participant.kills >> 2 participant.ride_distance >> 3204.53467 participant.walk_distance >> 2262.81714 participant.time_survived >> 1367 participant.player_id >> account.edb9910f1e9c4f3b9addb87d9329b57c player = api.players().get(participant.player_id) player >> account.edb9910f1e9c4f3b9addb87d9329b57c player.matches >> [<Match b3dcd7e8-2270-4fdd-8389-af77acf2d6c2>, <Match 2ebb1a9c-ab5e-4264-971f-df77a00918a9>, ..]
Ratelimits
Each application has a limited amount of requests allowed per minute.
The ratelimit is managed through HTTP headers (X-Ratelimit-Limit
, X-Ratelimit-Reset
, etc..).
In order to facilitate heavy tasks, it is possible to retrieve those values from the RateLimitError
. The values available in the exception instance are rl_limit
(integer) and rl_reset
(datetime).
An example snippet that would use this information in favor of processing something big:
api = PUBG('my-super-secret-key', Shard.STEAM) while True: try: print('Processing samples...') api.samples().get() except RateLimitError as error: sleep_seconds = (error.rl_reset - datetime.now()).total_seconds() if sleep_seconds > 0: print('Reached my limit! sleeping for {}'.format(sleep_seconds)) time.sleep(sleep_seconds)
Limits and Offsets
Currently disabled from the official API
Offsetting 5 matches and limitting by 10
matches = api.matches().limit(10).offset(5)
Sorting
Currently disabled from the official API
sort
defaults to ascending, you can use ascending=False
for a descending sort
matches = api.matches().limit(10).sort('createdAt') matches = api.matches().limit(10).sort('createdAt', ascending=False)
Filtering
Some endpoints allow you to apply filters, for example, filtering players by names:
players = api.players().filter(player_names=['Name1', 'Name2'])
Or filtering players by ids:
players = api.players().filter(player_ids=['account.3654e255b77b409e87b10dcb086ab00d'])
Pagination
Use next()
for the next page and prev()
for the previous one:
matches = api.matches() next_matches = matches.next() previous_matches = matches.prev()
Changelog
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size pubg_python-0.12.4-py3-none-any.whl (20.5 kB) | File type Wheel | Python version py3 | Upload date | Hashes View |
Filename, size pubg-python-0.12.4.tar.gz (19.4 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for pubg_python-0.12.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 09e0ade41c5626864980883e2c728533b9fa058c279672be3808316e7c8579ee |
|
MD5 | 96fcd83a0725b674e4b201c623d6fb85 |
|
BLAKE2-256 | afde68493d4026b42c6829f324a6266fcfcc69a015d7b19845d1469fe4f895f3 |