pubgkt

Official PUBG API client offering modular endpoints—player lookup, match details, leaderboards, clans, mastery, and lifetime/season/ranked stats—plus ergonomic collection interop and simple API-key usage.

#web
#typescript
#service-sdk
#sdk
#kotlin-coroutines
#client
#apple

Suggest an edit

Android JVMJVMKotlin/Native

GitHub stars3

Authorstheodorosidmar

Open issues0

LicenseMIT License

Creation datealmost 3 years ago

Last activity3 days ago

Latest release1.0.1 (9 days ago)

Homepage GitHub repository GitHub pages

pubgkt

Kotlin Multiplatform client for the official PUBG API.

Installation

Obtain an API key

Getting Started By Platform

JVM (Kotlin and Java)

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation(platform("dev.pubgkt:bom:1.0.1"))
    implementation("dev.pubgkt:core") // all modules
    // or pick individual modules
    implementation("dev.pubgkt:players")
    implementation("dev.pubgkt:stats")
}

Gradle Groovy

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation platform('dev.pubgkt:bom:1.0.1')
    implementation 'dev.pubgkt:core' // all modules
    // or pick individual modules
    implementation 'dev.pubgkt:players'
    implementation 'dev.pubgkt:stats'
}

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.pubgkt</groupId>
            <artifactId>bom</artifactId>
            <version>1.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- All modules -->
    <dependency>
        <groupId>dev.pubgkt</groupId>
        <artifactId>core-jvm</artifactId>
    </dependency>
    <!-- Or pick individual modules -->
    <dependency>
        <groupId>dev.pubgkt</groupId>
        <artifactId>players-jvm</artifactId>
    </dependency>
</dependencies>

Note: Maven artifacts use the -jvm suffix (e.g. players-jvm). Gradle Kotlin DSL resolves the correct variant automatically.

iOS/watchOS (Swift)

Swift Package Manager

Add the dependency in your Package.swift:

.package(url: "https://github.com/theodorosidmar/pubgkt.git", from: "1.0.1")

Then add the product to your target:

.product(name: "pubgkt", package: "pubgkt")

Import in your Swift code:

import PubgKt

Note: The Apple distribution is a single umbrella XCFramework exported from core that includes all modules.

Android

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation(platform("dev.pubgkt:bom:1.0.1"))
    implementation("dev.pubgkt:core") // all modules
    // or pick individual modules
    implementation("dev.pubgkt:players")
    implementation("dev.pubgkt:stats")
}

Gradle Groovy

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation platform('dev.pubgkt:bom:1.0.1')
    implementation 'dev.pubgkt:core' // all modules
    // or pick individual modules
    implementation 'dev.pubgkt:players'
    implementation 'dev.pubgkt:stats'
}

Note: Gradle resolves the correct -android variant automatically via Kotlin Multiplatform metadata. No -android suffix needed in the dependency declaration.

Node.js (JavaScript/TypeScript)

npm install @pubgkt/common @pubgkt/players @pubgkt/stats

Available packages:

npm package	Contents
`@pubgkt/common`	`PubgApi`, `Platform`, `PlatformRegion`, `GameMode`, seasons
`@pubgkt/players`	Player lookup by name or ID
`@pubgkt/clans`	Clan information
`@pubgkt/matches`	Match details with participants and stats
`@pubgkt/leaderboards`	Leaderboard rankings
`@pubgkt/mastery`	Weapon and survival mastery
`@pubgkt/stats`	Lifetime, season, and ranked stats

Note: Kotlin List<T> is exposed as KtList — call .asJsReadonlyArrayView() to get a standard ReadonlyArray<T>, or use KtList.fromJsArray() to convert a JS array into a KtList.

Quick Start

Kotlin

import dev.pubgkt.PubgApi
import dev.pubgkt.Platform
import dev.pubgkt.players.getPlayersByNames
import dev.pubgkt.stats.lifetime.getLifetimeStatsByAccountId

val api = PubgApi(apiKey = "your-api-key")

// Find players by display name
val players = api.getPlayersByNames("sparkingg", "TGLTN")

// Get lifetime stats
val stats = api.getLifetimeStatsByAccountId(players.first().id)
println("Squad FPP — ${stats.squadFpp.wins} wins, ${stats.squadFpp.kills} kills")

Java

import dev.pubgkt.PubgApi;
import dev.pubgkt.Platform;
import dev.pubgkt.players.GetPlayersByNameKt;
import dev.pubgkt.players.Player;
import kotlinx.coroutines.BuildersKt;
import kotlin.coroutines.EmptyCoroutineContext;

PubgApi api = new PubgApi("your-api-key");

List<Player> players = BuildersKt.runBlocking(
        EmptyCoroutineContext.INSTANCE,
        (_, cont) -> GetPlayersByNameKt.getPlayersByNames(api, List.of("sparkingg"), Platform.STEAM, cont)
);

Swift

import PubgKt

let api = PubgApi(apiKey: "your-api-key")

// Find players by display name
let players = try await api.getPlayersByNames(playerNames: ["sparkingg", "TGLTN"], platform: .steam)

// Get lifetime stats
let stats = try await api.getLifetimeStatsByAccountId(accountId: players.first!.id, platform: .steam)
print("Squad FPP — \(stats.squadFpp.wins) wins, \(stats.squadFpp.kills) kills")

Node.js / TypeScript

import { PubgApi, Platform, KtList } from "@pubgkt/common";
import { getPlayersByNames } from "@pubgkt/players";
import { getLifetimeStatsByAccountId } from "@pubgkt/stats";

const api = new PubgApi("your-api-key");

// Find players by display name
const players = await getPlayersByNames(api, KtList.fromJsArray(["sparkingg", "TGLTN"]), Platform.STEAM);
const list = players.asJsReadonlyArrayView();

// Get lifetime stats
const stats = await getLifetimeStatsByAccountId(api, list[0].id);
console.log(`Squad FPP — ${stats.squadFpp.wins} wins, ${stats.squadFpp.kills} kills`);

Note: All async API functions return Promise. Extension functions take the PubgApi instance as the first argument.

Modules

Module	Description	Docs
`common`	Core client, platform enums, seasons, rate limiting, retry	API
`players`	Player lookup by ID or name	API
`clans`	Clan information	API
`matches`	Match details with participants and stats	API
`leaderboards`	Leaderboard rankings	API
`mastery`	Weapon and survival mastery	API
`stats`	Lifetime, season, and ranked stats	API
`core`	All modules bundled together	API
`bom`	Bill of Materials for version alignment	—

Rate Limiting

The PUBG API enforces a default limit of 10 requests per minute per API key. pubgkt handles this automatically via the RateLimiter interface.

The default implementation (DelayRateLimiter) reads the X-RateLimit-Remaining and X-RateLimit-Reset response headers and delays subsequent requests when the limit is exhausted.

// Default — proactive delay when the limit is about to be hit
val api = PubgApi("your-api-key")

// No rate limiting — manage it yourself
val api = PubgApi("your-api-key", rateLimiter = RateLimiter.None)

// Thread-safe rate limiter for concurrent usage
val api = PubgApi("your-api-key", rateLimiter = ConcurrentDelayRateLimiter())

If the API returns HTTP 429 regardless (e.g. another instance shares your key), RateLimitExceededException is thrown with the reset timestamp.

Retry & Backoff

import dev.pubgkt.Retry
import dev.pubgkt.ExponentialBackoff

val api = PubgApi(
    apiKey = "your-api-key",
    retry = Retry(
        maxRetries = 5,
        backoff = ExponentialBackoff(
            base = 2.0,
            baseDelayMs = 1_000,
            maxDelayMs = 60_000,
        ),
    ),
)

API Documentation

Full API reference is available at theodorosidmar.github.io/pubgkt.

Samples

Kotlin / Java

./gradlew :samples:jvm:runPlayersKotlin -Pargs="<api-key>"
./gradlew :samples:jvm:runStatsKotlin -Pargs="<api-key>"
./gradlew :samples:jvm:runMatchesKotlin -Pargs="<api-key>"

./gradlew :samples:jvm:runPlayersJava -Pargs="<api-key>"
./gradlew :samples:jvm:runStatsJava -Pargs="<api-key>"
./gradlew :samples:jvm:runMatchesJava -Pargs="<api-key>"

Swift

./gradlew :samples:swift:runPlayersSwift -Pargs="<api-key>"
./gradlew :samples:swift:runStatsSwift -Pargs="<api-key>"
./gradlew :samples:swift:runMatchesSwift -Pargs="<api-key>"
./gradlew :samples:swift:runClansSwift -Pargs="<api-key>"
./gradlew :samples:swift:runLeaderboardsSwift -Pargs="<api-key>"
./gradlew :samples:swift:runMasterySwift -Pargs="<api-key>"

Node.js

# Build the npm packages first
./gradlew :core:assembleNpmPackages

# Install dependencies
cd samples/nodejs && npm install

# Run any sample
PUBG_API_KEY=your-key npm run players
PUBG_API_KEY=your-key npm run stats
PUBG_API_KEY=your-key npm run matches

Available modules: common, players, clans, matches, leaderboards, mastery, stats

Supported Platforms

Platform	Status
JVM	✅
iOS	✅
watchOS	✅
Android	✅
JS/Node	✅

License

MIT

Android JVMJVMKotlin/Native

GitHub stars3

Authorstheodorosidmar

Open issues0

LicenseMIT License

Creation datealmost 3 years ago

Last activity3 days ago

Latest release1.0.1 (9 days ago)

Homepage GitHub repository GitHub pages

pubgkt

Kotlin Multiplatform client for the official PUBG API.

Installation

Obtain an API key

Getting Started By Platform

JVM (Kotlin and Java)

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation(platform("dev.pubgkt:bom:1.0.1"))
    implementation("dev.pubgkt:core") // all modules
    // or pick individual modules
    implementation("dev.pubgkt:players")
    implementation("dev.pubgkt:stats")
}

Gradle Groovy

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation platform('dev.pubgkt:bom:1.0.1')
    implementation 'dev.pubgkt:core' // all modules
    // or pick individual modules
    implementation 'dev.pubgkt:players'
    implementation 'dev.pubgkt:stats'
}

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.pubgkt</groupId>
            <artifactId>bom</artifactId>
            <version>1.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- All modules -->
    <dependency>
        <groupId>dev.pubgkt</groupId>
        <artifactId>core-jvm</artifactId>
    </dependency>
    <!-- Or pick individual modules -->
    <dependency>
        <groupId>dev.pubgkt</groupId>
        <artifactId>players-jvm</artifactId>
    </dependency>
</dependencies>

Note: Maven artifacts use the -jvm suffix (e.g. players-jvm). Gradle Kotlin DSL resolves the correct variant automatically.

iOS/watchOS (Swift)

Swift Package Manager

Add the dependency in your Package.swift:

.package(url: "https://github.com/theodorosidmar/pubgkt.git", from: "1.0.1")

Then add the product to your target:

.product(name: "pubgkt", package: "pubgkt")

Import in your Swift code:

import PubgKt

Note: The Apple distribution is a single umbrella XCFramework exported from core that includes all modules.

Android

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation(platform("dev.pubgkt:bom:1.0.1"))
    implementation("dev.pubgkt:core") // all modules
    // or pick individual modules
    implementation("dev.pubgkt:players")
    implementation("dev.pubgkt:stats")
}

Gradle Groovy

repositories {
    mavenCentral()
}

dependencies {
    // Using the BOM (recommended)
    implementation platform('dev.pubgkt:bom:1.0.1')
    implementation 'dev.pubgkt:core' // all modules
    // or pick individual modules
    implementation 'dev.pubgkt:players'
    implementation 'dev.pubgkt:stats'
}

Note: Gradle resolves the correct -android variant automatically via Kotlin Multiplatform metadata. No -android suffix needed in the dependency declaration.

Node.js (JavaScript/TypeScript)

npm install @pubgkt/common @pubgkt/players @pubgkt/stats

Available packages:

npm package	Contents
`@pubgkt/common`	`PubgApi`, `Platform`, `PlatformRegion`, `GameMode`, seasons
`@pubgkt/players`	Player lookup by name or ID
`@pubgkt/clans`	Clan information
`@pubgkt/matches`	Match details with participants and stats
`@pubgkt/leaderboards`	Leaderboard rankings
`@pubgkt/mastery`	Weapon and survival mastery
`@pubgkt/stats`	Lifetime, season, and ranked stats

Note: Kotlin List<T> is exposed as KtList — call .asJsReadonlyArrayView() to get a standard ReadonlyArray<T>, or use KtList.fromJsArray() to convert a JS array into a KtList.

Quick Start

Kotlin

import dev.pubgkt.PubgApi
import dev.pubgkt.Platform
import dev.pubgkt.players.getPlayersByNames
import dev.pubgkt.stats.lifetime.getLifetimeStatsByAccountId

val api = PubgApi(apiKey = "your-api-key")

// Find players by display name
val players = api.getPlayersByNames("sparkingg", "TGLTN")

// Get lifetime stats
val stats = api.getLifetimeStatsByAccountId(players.first().id)
println("Squad FPP — ${stats.squadFpp.wins} wins, ${stats.squadFpp.kills} kills")

Java

import dev.pubgkt.PubgApi;
import dev.pubgkt.Platform;
import dev.pubgkt.players.GetPlayersByNameKt;
import dev.pubgkt.players.Player;
import kotlinx.coroutines.BuildersKt;
import kotlin.coroutines.EmptyCoroutineContext;

PubgApi api = new PubgApi("your-api-key");

List<Player> players = BuildersKt.runBlocking(
        EmptyCoroutineContext.INSTANCE,
        (_, cont) -> GetPlayersByNameKt.getPlayersByNames(api, List.of("sparkingg"), Platform.STEAM, cont)
);

Swift

import PubgKt

let api = PubgApi(apiKey: "your-api-key")

// Find players by display name
let players = try await api.getPlayersByNames(playerNames: ["sparkingg", "TGLTN"], platform: .steam)

// Get lifetime stats
let stats = try await api.getLifetimeStatsByAccountId(accountId: players.first!.id, platform: .steam)
print("Squad FPP — \(stats.squadFpp.wins) wins, \(stats.squadFpp.kills) kills")

Node.js / TypeScript

import { PubgApi, Platform, KtList } from "@pubgkt/common";
import { getPlayersByNames } from "@pubgkt/players";
import { getLifetimeStatsByAccountId } from "@pubgkt/stats";

const api = new PubgApi("your-api-key");

// Find players by display name
const players = await getPlayersByNames(api, KtList.fromJsArray(["sparkingg", "TGLTN"]), Platform.STEAM);
const list = players.asJsReadonlyArrayView();

// Get lifetime stats
const stats = await getLifetimeStatsByAccountId(api, list[0].id);
console.log(`Squad FPP — ${stats.squadFpp.wins} wins, ${stats.squadFpp.kills} kills`);

Note: All async API functions return Promise. Extension functions take the PubgApi instance as the first argument.

Modules

Module	Description	Docs
`common`	Core client, platform enums, seasons, rate limiting, retry	API
`players`	Player lookup by ID or name	API
`clans`	Clan information	API
`matches`	Match details with participants and stats	API
`leaderboards`	Leaderboard rankings	API
`mastery`	Weapon and survival mastery	API
`stats`	Lifetime, season, and ranked stats	API
`core`	All modules bundled together	API
`bom`	Bill of Materials for version alignment	—

Rate Limiting

The PUBG API enforces a default limit of 10 requests per minute per API key. pubgkt handles this automatically via the RateLimiter interface.

The default implementation (DelayRateLimiter) reads the X-RateLimit-Remaining and X-RateLimit-Reset response headers and delays subsequent requests when the limit is exhausted.

// Default — proactive delay when the limit is about to be hit
val api = PubgApi("your-api-key")

// No rate limiting — manage it yourself
val api = PubgApi("your-api-key", rateLimiter = RateLimiter.None)

// Thread-safe rate limiter for concurrent usage
val api = PubgApi("your-api-key", rateLimiter = ConcurrentDelayRateLimiter())

If the API returns HTTP 429 regardless (e.g. another instance shares your key), RateLimitExceededException is thrown with the reset timestamp.

Retry & Backoff

import dev.pubgkt.Retry
import dev.pubgkt.ExponentialBackoff

val api = PubgApi(
    apiKey = "your-api-key",
    retry = Retry(
        maxRetries = 5,
        backoff = ExponentialBackoff(
            base = 2.0,
            baseDelayMs = 1_000,
            maxDelayMs = 60_000,
        ),
    ),
)

API Documentation

Full API reference is available at theodorosidmar.github.io/pubgkt.

Samples

Kotlin / Java

./gradlew :samples:jvm:runPlayersKotlin -Pargs="<api-key>"
./gradlew :samples:jvm:runStatsKotlin -Pargs="<api-key>"
./gradlew :samples:jvm:runMatchesKotlin -Pargs="<api-key>"

./gradlew :samples:jvm:runPlayersJava -Pargs="<api-key>"
./gradlew :samples:jvm:runStatsJava -Pargs="<api-key>"
./gradlew :samples:jvm:runMatchesJava -Pargs="<api-key>"

Swift

./gradlew :samples:swift:runPlayersSwift -Pargs="<api-key>"
./gradlew :samples:swift:runStatsSwift -Pargs="<api-key>"
./gradlew :samples:swift:runMatchesSwift -Pargs="<api-key>"
./gradlew :samples:swift:runClansSwift -Pargs="<api-key>"
./gradlew :samples:swift:runLeaderboardsSwift -Pargs="<api-key>"
./gradlew :samples:swift:runMasterySwift -Pargs="<api-key>"

Node.js

# Build the npm packages first
./gradlew :core:assembleNpmPackages

# Install dependencies
cd samples/nodejs && npm install

# Run any sample
PUBG_API_KEY=your-key npm run players
PUBG_API_KEY=your-key npm run stats
PUBG_API_KEY=your-key npm run matches

Available modules: common, players, clans, matches, leaderboards, mastery, stats

Supported Platforms

Platform	Status
JVM	✅
iOS	✅
watchOS	✅
Android	✅
JS/Node	✅

License

MIT