- About
- Changelog
- Getting started
- Usage example: player last match
- Usage example: player aggregate stats
- Usage example: telemetry
- License
Unofficial TypeScript wrapper on the official PUBG API.
Main features:
- Simple to use
- Maps API resources to easier-to-use "Models" (i.e.
Player,Match,Participant, etc.) - Telemetry parsing
- OOP design
- Fully typed
Helps you win chicken dinners
See releases tab on github.
First, obtain an API key from PUBG Official API.
Then install the package with NPM:
npm install --save pubg-typescript-api
As an example, let's make a command line utility to display some quick stats on a player's last match.
Import the module and define API_KEY with your own API key obtained from the official website.
Obviously the required classes depend on what you're doing, but in this case we need these
import { Match, PlatformRegion, Player, PubgAPI } from 'pubg-typescript-api';
const API_KEY = 'YOUR_API_KEY_HERE';First, instantiate the PubgAPI object, responsible for making requests to the API authenticated with your API key
const api = new PubgAPI(API_KEY, PlatformRegion.PC_EU);here we used the Platform and Region PC_EU, but you're obviously free to change it to whatever you need. The possible values can be found in the PlatformRegion enum.
This object must be given to all methods that retrieve data from the API. For example, let's find the player corresponding to the username "martinsileno"
const players = await Player.filterByName(api, ['martinsileno']);
const player = players[0];
console.log(`Found player "${player.name}" with ID: ${player.id}`);here we're awaiting on the Promise returned by filterByName, a function that returns a (promise of a) list of Players with the given names.
Now that we have our player's data, let's find stats on his/her last played match
const lastMatchId = player.matchIds[0];
const match = await Match.get(api, lastMatchId);
console.log(`Last played match on ${match.dateCreated} and lasted ${Math.round(match.duration / 60)} minutes, with ID: ${match.id}`);here we extract the latest match ID from player.matchIds (it's sorted from newest to oldest) and then using it as argument for Match.get, a function that returns a promise of a Match object. So by awaiting on that, we get our match data.
The last step before running our simple example is to get the player's stats in this Match.
const participant = match.getParticipantByName('martinsileno');
if (!participant) {
console.error('Player not found in participants');
return;
}
console.log(`${participant.name} placed #${participant.winPlace} out of ${match.participants.length} on ${match.map}`);
console.log('his stats: ');
console.log(`kills ${participant.kills}`);
console.log(`damage ${participant.damageDealt}`);
console.log(`assists ${participant.assists}`);
console.log(`headshot kills ${participant.headshotKills}`);
console.log(`total distance ${participant.totalDistance}m`);to get a player's stats in a Match we use the method getParticipantByName, which returns the corresponding Participant object.
The Participant instances contain details on players in a Match, see the public getters in the class to find more.
And we're done, we can run our example to see if it works, the output should look like
$ node dist/main.js
Found player "martinsileno" with ID: account.a540a32a49784025939a975b45e86bfe
Last played match on Sun Apr 22 2018 00:33:20 GMT+0200 (W. Europe Daylight Time) and lasted 32 minutes, with ID: a6d8d8f7-a3c4-4b1c-9947-8df40c144283
martinsileno placed #1 out of 92 on Desert_Main
his stats:
kills 2
damage 376.501
assists 3
headshot kills 1
total distance 3915.62m
Since May 1st and version 1.3 of this wrapper we finally have aggregate data on a player for each season.
Getting this data is very easy,
const api = new PubgAPI(API_KEY, PlatformRegion.PC_NA);
const result = await Player.filterByName(api, ['shroud']);
const shroud = result[0];
const seasonData = await PlayerSeason.get(api, shroud.id, 'division.bro.official.2018-04');
const soloStats = seasonData.squadFPPStats;
console.log(`Player [${shroud.name}] stats for season [${seasonData.seasonId}]:`);
console.log(`Kills ${soloStats.kills} / Assists ${soloStats.assists} / Knock-outs ${soloStats.dBNOs}`);
console.log(`Played ${soloStats.roundsPlayed} matches`);
console.log(`Won ${soloStats.wins} (${(100 * soloStats.wins / soloStats.roundsPlayed).toFixed(2)}%)`);
console.log(`top10s ${soloStats.top10s} (${(100 * soloStats.top10s / soloStats.roundsPlayed).toFixed(2)}%)`);This results in
Player [shroud] stats for season [division.bro.official.2018-04]:
Kills 268 / Assists 50 / Knock-outs 200
Played 50 matches
Won 13 (26.00%)
top10s 20 (40.00%)
You can get the season names using the Season.list method,
const seasonsList = await Season.list(api);
seasonsList.forEach(s => console.log(s.id));(I suggest you cache the result as it's not likely to change often)
This package includes an easy-to-use and complete telemetry parsing utility.
As an usage example we will get a list of player kills, care package landings and a list of player positions for a player.
You can do much more with telemetry data, please read the documentation in the wiki for more details.
The first thing to do when working with telemetry is to download the corresponding object
const api = new PubgAPI(API_KEY, PlatformRegion.PC_EU);
const telemetry = await match.getTelemetry(api);telemetry.playerKillEvents.forEach(e => {
console.log(`[${e.dateTime.toLocaleDateString()} ${e.dateTime.toLocaleTimeString()} kill] ${e.killer.name} -> ${e.victim.name} | ${e.damageCauserName} ${e.damageTypeCategory} @ ${e.distance / 100}m`);
});example output:
...
[2018-4-28 19:16:28 kill] Ludosh -> martinsileno | PlayerMale_A_C Damage_Groggy @ 63.1690576171875m
[2018-4-28 19:16:28 kill] siperdekizurafa -> zaku6652 | PlayerMale_A_C Damage_Groggy @ 36.4665966796875m
[2018-4-28 19:16:28 kill] Ludosh -> Novanta | WeapHK416_C Damage_Gun @ 54.971845703125m
[2018-4-28 19:17:54 kill] Razzmatazzzzz -> WilliamTanz | WeapSCAR-L_C Damage_Gun @ 143.47111328125m
[2018-4-28 19:17:55 kill] Haspex -> LMNTRIXs | WeapAK47_C Damage_Gun @ 126.266767578125m
...
"damage groggy" means bleed out damage
telemetry.carePackageLandEvents.forEach(e => {
const itemsString = e.itemPackage.items.map(item => item.itemId).join(', ');
console.log(`[${e.dateTime.toLocaleDateString()} ${e.dateTime.toLocaleTimeString()} carePackage land] with ${itemsString}`);
});example output:
[2018-4-28 19:04:55 carePackage land] with Item_Weapon_M24_C, Item_Ammo_762mm_C, Item_Ammo_762mm_C, Item_Attach_Weapon_Upper_CQBSS_C, Item_Attach_Weapon_Upper_PM2_01_C, Item_Back_C_01_Lv3_C, Item_Heal_MedKit_C
[2018-4-28 19:11:27 carePackage land] with Item_Weapon_M24_C, Item_Ammo_762mm_C, Item_Ammo_762mm_C, Item_Attach_Weapon_Upper_CQBSS_C, Item_Head_G_01_Lv3_C, Item_Heal_FirstAid_C
[2018-4-28 19:15:11 carePackage land] with Item_Weapon_Groza_C, Item_Ammo_762mm_C, Item_Ammo_762mm_C, Item_Ammo_762mm_C, Item_Attach_Weapon_Upper_CQBSS_C, Item_Armor_C_01_Lv3_C, Item_Heal_MedKit_C
[2018-4-28 19:24:19 carePackage land] with Item_Weapon_M249_C, Item_Ammo_556mm_C, Item_Ammo_556mm_C, Item_Head_G_01_Lv3_C, Item_Heal_MedKit_C, Item_Ghillie_02_C
const martinPositions = telemetry.playerPositionEvents.filter(e => e.character.name === 'martinsileno');
martinPositions.forEach(e => {
const loc = e.character.location;
console.log(`[${e.dateTime.toLocaleDateString()} ${e.dateTime.toLocaleTimeString()} position] (${loc.x}, ${loc.y}, ${loc.z})`);
});example output:
...
[2018-4-28 19:12:44 position] (432451, 63057.02734375, 5437.40966796875)
[2018-4-28 19:12:54 position] (429667.1875, 61954.94921875, 4977.5)
[2018-4-28 19:13:04 position] (425153.90625, 65993.546875, 4900.1298828125)
[2018-4-28 19:13:14 position] (422108.46875, 71026.3671875, 5496.9599609375)
[2018-4-28 19:13:24 position] (419111.8125, 75035.40625, 5401.53759765625)
...
MIT