Making Requests

Content Negotiation

Clients using the API should specify that they accept responses using the application/vnd.api+json format. For convenience, we will also accept application/json since it is the default for many popular client libraries.

The Server will respond with a Content-Type header that mirrors the format requested by the client.

Setting Headers

To specify the headers, use this code:

Shell

curl "endpoint-url" \
-H "Authorization: Bearer <api-key>"
-H "Accept: application/vnd.api+json"

Java

import java.io.*;
import java.net.*;

URL url = new URL("endpoint-url");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization","Bearer <api-key>");
conn.setRequestProperty("Accept", "application/vnd.api+json");

conn.getInputStream()

Python

import requests

url = "endpoint-url"

header = {
  "Authorization": "Bearer <api-key>",
  "Accept": "application/vnd.api+json"
}

r = requests.get(url, headers=header)

Go

import "net/http"

client := &http.Client{}
req, _ := http.NewRequest("GET","endpoint-url",nil)
req.Header.Set("Authorization", "Bearer <api-key>")
req.Header.Set("Accept", "application/vnd.api+json")
res, _ := client.Do(req)

URL Parameters

the platform shard

shards/$platform

The PUBG API shards data by platform, and therefore requires a shard to be specified in the URL for most requests. In most cases, only the platform is required for the shard. However, the platform-region shard is required when making requests for PC and PSN players’ season stats for seasons prior to division.bro.official.2018-09, and for Xbox season stats for seasons before division.bro.official.2018-08. For more information about shards, please see Platforms and Regions.

the platform-region shard

shards/$platform-region

The platform-region shard should be used for making requests for season stats for seasons before the Survival Title system was launched:

  • PC and PSN season stats for seasons before and including division.bro.official.2018-09.

  • Xbox season stats for seasons before and including division.bro.official.2018-08.

For more information about shards, please see Platforms and Regions.

Game Mode

gameMode/$gameMode

Skip to Game Modes for more information about $gameMode values.

Match ID

matches/$matchId

Match IDs are used to get match data and telemetry. They are listed within the responses from the players, samples, and season stats endpoints. Review Getting a Match for more information.

Season ID

seasons/$seasonId

Season IDs are used for Getting Player Season Stats. They are available in responses from the Season Stats endpoint. Some stats are only available after the Survival Title system went live. For each platform, the first Survival Title season is:

  • pc: division.bro.official.pc-2018-01

  • psn: division.bro.official.playstation-01

  • xbox: division.bro.official.xbox-01

  • stadia: N/A, first season: division.bro.official.console-07

Lifetime Season ID

seasons/lifetime

The lifetime season ID can be used to get “lifetime” stats for a player. These are the same stats that are available in-game by choosing “Overall” while viewing your season stats. They include data beginning from when the Survival Title system was launched:

  • PC lifetime stats begin with season division.bro.official.pc-2018-01

  • Playstation lifetime stats begin with season division.bro.official.playstation-01

  • Xbox lifetime stats begin with season division.bro.official.xbox-01

  • Stadia lifetime stats begin with season division.bro.official.console-07

Player Account ID

players/$playerId

Use this filter to specify which player accounts to search for.

Player Account IDs Filter

filter[playerIds]=$playerId

Use this filter to specify which player accounts to search for. You can search for up to 10 players at a time by separating their account IDs with commas.

Player Account Names Filter

filter[playerNames]=$playerName

Use this filter to specify which players to search for. You can search for up to 10 players at a time by separating their player names (in-game names) with commas.

Gamepad Filter

filter[gamepad]=$isGamepad

A filter specifying whether gamepad stats should be searched for instead of mouse/keyboard stats when using the stadia shard.

Stadia players have separate season stats for when they use a keyboard and mouse, and for when they use a gamepad. Gamepad stats can be queried for by using the console shard, or by using the gamepad filter with the stadia shard. When querying for these stats, $isGamepad should have the value true. This filter should be omitted otherwise. The API will respond with keyboard/mouse stats to queries for stats using the stadia shard without this filter.

Page Filter

page[number]=$page

Leaderboards are separated into pages of 500 players each. Use the page filter to request additional pages. Pages are numbered beginning with 0. If this filter is omitted, the API will respond with the first page.

Platforms and Regions

The PUBG API shards data by either platform or platform-region depending on the request, and therefore requires a shard to be specified in the URL for most requests. The current shards are:

shards/$platform - the platform shard

  • kakao - Kakao

  • stadia - Stadia

  • steam - Steam

  • tournament - Tournaments

  • psn - PSN

  • xbox - Xbox

  • console - PSN/Xbox (used for the /matches and /samples endpoints)

shards/$platform-region - the platform-region shard

  • pc-as - Asia

  • pc-eu - Europe

  • pc-jp - Japan

  • pc-kakao - Kakao

  • pc-krjp - Korea

  • pc-na - North America

  • pc-oc - Oceania

  • pc-ru - Russia

  • pc-sa - South and Central America

  • pc-sea - South East Asia

  • pc-tournament - Tournaments

  • psn-as - Asia

  • psn-eu - Europe

  • psn-na - North America

  • psn-oc - Oceania

  • xbox-as - Asia

  • xbox-eu - Europe

  • xbox-na - North America

  • xbox-oc - Oceania

  • xbox-sa - South America

The shard is specified after the pubg domain and before the endpoint like this:

"...pubg.com/shards/steam/endpoint..."

Note: Use the platform shard when making requests for Stadia players’ season stats, PC and PSN players’ season stats for seasons after division.bro.official.2018-09, and for Xbox season stats for seasons after division.bro.official.2018-08. Use the platform-region shard for making any other requests for players’ season stats.

The platform shard should be used at all other endpoints that require a shard. The platform-region shard is deprecated.

Game Modes

For some requests, a game mode is also required to be speicifed in the request URL. Valid game modes are:

  • solo - 1 player per team, third person perspective

  • solo-fpp - 1 player per team, first person perspective

  • duo - up to 2 people per team, third person perspective

  • duo-fpp - up to 2 people per team, first person perspective

  • squad - more than 2 people per team, third person perspective

  • squad-fpp - more than 2 people per team, first person perspective

GZIP

Clients can specify the header Accept-Encoding: gzip, and the server will compress responses. Responses will be returned with Content-Encoding: gzip.

Given the size of matches, this can have significant performance benefits.

To specify the header Accept-Encoding, use this code:

Shell:

-H "Accept-Encoding: gzip"

Java:

conn.setRequestProperty("Accept-Encoding","gzip");

Python:

header = {"Accept-Encoding":"gzip"}

Go:

req.Header.Set("Accept-Encoding", "gzip")

Data Retention Period

The data retention period is 14 days. Match data older than 14 days will not be available. Match lists go back 14 days for the players endpoint, and the season stats enpoint will show up to the 32 most recent matches within 14 days.

Responses

All Server responses will be in JSON-API format and contain a root JSON object.

Each response will contain at least one of the following top-level members:

  • data : the response’s “primary data”

  • errors : an array of error objects

A response may contain any of these top-level members:

  • links: a links object related to the primary data.

  • included: an array of resource objects that are related to the primary data and/or each other (“included resources”).

  • meta: not currently used.

If a document does not contain a top-level data key, the included array will not be present either.

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation here.

Here’s a sample request sent from a browser hitting ‘example.com’:

Shell:

curl -i https://api.pubg.com/status -H "Origin: http://example.com"
HTTP/1.1 200 OK
...
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Length

This is what the CORS preflight request looks like:

curl -i https://api.pubg.com/status -H "Origin: http://example.com" -X OPTIONS
HTTP/1.1 200 OK
...
Access-Control-Allow-Headers: Origin,X-Title-Id,Authorization
Access-Control-Allow-Methods: GET,POST,OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 86400