Skip to main content

A python wrapper for the PUBG developer API

Project description


pypi wheel

A python wrapper for the PUBG Developer API

PUBG Developer API Official Documentation


To install the wrapper, simply use pip

pip install pubg-python

or pipenv

pipenv install pubg-python


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


A sample of matches can be retrieved as a starting point

sample = api.samples().get()
for match in sample.matches:

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:


Retrieving a single player

player = api.players().get('account.3654e255b77b409e87b10dcb086ab00d')

for match in player.matches:
    match_data = api.matches().get(

Retrieving a list of players filtering by names

players = api.players().filter(player_names=['Name1', 'Name2'])

for player in players:
    player_id =

Retrieving a list of players filtering by ids

players = api.players().filter(player_ids=['account.3654e255b77b409e87b10dcb086ab00d'])

for player in players:
    player_name =


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 = [
matches = api.matches().filter(match_ids=match_ids)
for match in matches:


Processing a match Telemetry data

match = api.matches().get('276f5bcb-a831-4e8c-a610-d2073692069e')
asset = match.assets[0]
telemetry = api.telemetry(asset.url)

>> 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.


Retrieving a single tournament

tournament = api.tournaments().get('na-ppc')

Retrieving a list of tournaments

tournaments = api.tournaments()
for tournament in tournaments:


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'

It's also possible to retrieve lifetime stats, instead of a season_id:

players_seasons = api.seasons(
    season_id='lifetime', game_mode='solo'

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

Retrieving a weapon mastery data

players = api.players().filter(player_names=['epickitten'])[0]
player = players[0]
wm = api.weapon_mastery(


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]

>> [<Match bd6aae34-be05-4094-981c-083285c7e861>, <Match 276f5bcb-a831-4e8c-a610-d2073692069e>, ..]

match = api.matches().get(player.matches[0].id)

>> 'solo'

>> 1899

>> [<Roster d542eaee-cd02-4f4e-ad7f-ed5ea71a17cf>, <Roster e9f0962a-ebd4-4d86-b134-95783b713800>, ..]

roster = match.rosters[0]

>> [<Participant 7cc76d1b-a80e-4997-8eb8-d4b3c1ed4f44>]

participant = roster.participans[0]
>> 'urdaddyYO'

>> 291.08

>> 2

>> 3204.53467

>> 2262.81714

>> 1367

>> account.edb9910f1e9c4f3b9addb87d9329b57c

player = api.players().get(participant.player_id)

>> account.edb9910f1e9c4f3b9addb87d9329b57c

>> [<Match b3dcd7e8-2270-4fdd-8389-af77acf2d6c2>, <Match 2ebb1a9c-ab5e-4264-971f-df77a00918a9>, ..]


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:
        print('Processing samples...')
    except RateLimitError as error:
        sleep_seconds = (error.rl_reset -
        if sleep_seconds > 0:
            print('Reached my limit! sleeping for {}'.format(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)


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)


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'])


Use next() for the next page and prev() for the previous one:

matches = api.matches()
next_matches =
previous_matches = matches.prev()


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pubg-python-0.12.5.tar.gz (20.4 kB view hashes)

Uploaded source

Built Distribution

pubg_python-0.12.5-py3-none-any.whl (20.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page