The Hi-Rez Studios API returns JSON (or XML) data with players' information including matches, friends, and stats.
If you are interested in creating an App that is paid and/or contains monetization features, please contact us at [email protected] to discuss a potential business relationship. All for-profit Apps must be pre-approved in writing by Hi-Rez (such approval to be granted or withheld in Hi-Rez's sole discretion). To the extent any for-profit Apps are approved in writing by Hi-Rez (in its sole discretion), you will be solely responsible for any and all taxes due in connection with the distribution of such App in any territory.
To access the API you'll need your own set of Credentials which consist of a Developer ID (dev_id) and an Authentication Key (auth_key).
Here are the Credentials for a sample account:
| dev_id | auth_key |
|---|---|
| 1004 | 23DF3C7E9BD14D84BF892AD206B6755C |
Use your personal Credentials to access the API via a Representational State Transfer (REST) Web Service hosted at https://api.{game}.com/{game}api.svc.
An
API Keythat will provide access to API. The process of obtainingAPI Keyshould be an one-time activity.
If you don't already have a dev_id and auth_key, please submit an application to gain access to the API.
If your application is accepted, you will receive an e-mail from Hi-Rez Studios containing your personal API Key within a few days.
NOTE: The same dev_id and auth_key combination should work for SmiteAPI, PaladinsAPI and RealmAPI, across all supported platforms. Do not request a new, if you already have a Credentials.
API keys should be treated as secret data and not exposed to users. To ensure the security of your API key, we strongly suggest that you make requests to the API server-side whenever possible.
Any requests to the API made via client-side present the risk of your API key being compromised. Most importantly, never include your api_key inline in your code. For additional security, don't have the key itself contained anywhere in your code, keep it in a variable stored in a privately scoped method.
To retrieve all information from the API, you will need to append all requests to the endpoint you want to retrieve data, and all requests must begin with the method you are wanting to access concatenated with the response type you are wanting.
- Paladins:
https://api.paladins.com/paladinsapi.svc - Realm Royale:
https://api.realmroyale.com/realmapi.svc - Rogue Company:
https://api.roguecompany.com/RoCoApi.svc - Smite:
https://api.smitegame.com/smiteapi.svc
base_url_endpoint/method_pattern[response_format]/params
The url format for calling a method from the api
| URI Parameter | Description | Example |
|---|---|---|
| base_url_endpoint | The URL prefix for the Endpoint that you want to use | https://api.paladins.com/paladinsapi.svc |
| method_pattern | The pattern for the method above, where [response_format] is replaced by the formatting that you want returned (either JSON or XML). | /CreateSessionJSON |
| params | The method params | /{dev_id}/{signature}/{timestamp} |
URI example: https://api.paladins.com/paladinsapi.svc/CreateSessionJSON/{dev_id}/{signature}/{timestamp}
The API rate limits in order to prevent abuse and over use of the API (either intentional, more likely unintentional “over use”). All API requests are subject to rate limits.
Rate limits are applied on a per-user basis — or more accurately described, per dev_id / auth_key combination. By “per-user”, we mean that rate limits are shared across different endpoints and all supported platforms using the same dev_id.
Here are the default initial limitations for API Developers:
| Concurrent Sessions | Daily Sessions | Session Time | Daily Request |
|---|---|---|---|
| 50 | 500 | 15 minutes | 7500 |
Once a rate limit is reached, the API will return a ret_msg containing details about the limit and any subsequent requests made by you will fail until the limit resets.
Most rate limiting issues are caused by extraneous API calls. For example, don’t try to call the API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.
Store API responses in your application or on your site if you expect a lot of use. You may cache data locally wherever possible.
An invalid or rate limited request to the API will return a non-null ret_msg. Please check all API responses for errors.
If your site keeps track of many player (for example, fetching their current status or statistics about their game stats), consider only requesting data for users who have recently signed into your site.
The API does not support requesting more than one resource with a single API call. However, many ids can be handled in one API call using the Get Player Batch, Get Player Batch From Match and Get Match Details Batch endpoints.
We strongly recommend specify multiple IDs in one API request when possible as this improves performance of your API responses.
The following table illustrates this concept.
| Example Request(s) | Number of API Calls |
|---|---|
|
/getplayer[response_format]/{dev_id}/{signature}/{session_id}/{timestamp}/{player_id1} /getplayer[response_format]/{dev_id}/{signature}/{session_id}/{timestamp}/{player_id2} /getplayer[response_format]/{dev_id}/{signature}/{session_id}/{timestamp}/{player_id3} |
3 |
| /getplayerbatch[response_format]/{dev_id}/{signature}/{session_id}/{timestamp}/{player_id1},{player_id2},{player_id3} | 1 |
To begin using the API, you will first need to establish a valid Session.
To Authenticating with the API, you may start a Session (via the CreateSession method) and receive a session_id. Sessions are used for authentication, security, monitoring, and throttling. Once you obtain a Session, you will pass it to other methods for authentication.
More details regarding Session creation are provided in CreateSession.
Sessions have expirations and must be recreated afterward, expirations do not affect existing Sessions.
Each session lasts for 15 minutes without activity (In other words, only when idle for 15 minutes).
Each API call “resets the clock” . Sessions return an timestamp field indicating when a Session was acquired.
However, you should build your applications in such a way that they are resilient to Session authentication failures. In other words, an application capable of refreshing Sessions should not need to know how long a Session will live. Rather, it should be prepared to deal with the Session becoming invalid at any time.
We recommend that you refresh your Sessions in response to being rejected by the server for bad authentication.
It is good practice to assume that your Session can expire or be revoked at any time, and refreshing reactively ensures that your application is prepared to deal with such situations as gracefully as possible. For this reason, refreshing in response to server rejection is preferable to refreshing proactively, on a fixed schedule.
When you make a request with expired or incorrect Session, the API returns a ret_msg error.
The API expose a field called “ret_msg” to represent an error or rate limit being encountered.
We recommend using this field value as an unique identifier for errors, with the exception of using the CreateSession method or when the request completes without any error, the ret_msg will be not null when the request was not successful.
| Message | Description | Recommendation |
|---|---|---|
| Approved | Indicates that a new Session has been created sucessful. | You may store the “session_id” is a local variable and use while it is valid. |
| dailylimit | Indicates that the dev_id used in the request has reached its rate limit and you may be unable to request new data. | You may wait until the limit ends. |
| Daily request limit reached | Indicates that the dev_id used in the request has reached its rate limit and you may be unable to request new data. | You may wait until the limit ends. |
| Exceeded daily session cap. | Indicates that the dev_id used in the request has reached its rate limit and you may be unable to request new data. | You may wait until the limit ends. |
| Error while comparing Server and Client timestamp | Indicates that the timestamp sent to the API was not determined to be valid. | |
| Exception while processing: Invalid date format | Indicates that the timestamp sent to the API was not determined to be valid. | |
| Exception - Timestamp | This error means that your timestamp sent to the API was not determined to be valid. | |
| Exception - Timestamp Your signature: {signature} Your timestamp: {timestamp} Your session ID: {session_id} | Indicates that the timestamp sent to the API was not determined to be valid. | |
| Exception while validating developer access.Invalid signature. | This error means that the method signature sent to the API was not determined to be valid. | |
| Failed to validate DeveloperId | This error means that your dev_id and/or auth_key sent to the API was not determined to be valid. | |
| Invalid date format | This error means that the date sent to the API was not determined to be valid format. | |
| Invalid session id. | This error means that the Session sent was invalid or not alive, you may start a new session. | Use an existent/alive or start a new Session. |
| Invalid signature. Details ---> action={method_name} timestamp={timestamp} clientHash= self.generateSignature({method_name}) serverHash={server_hash} source=ValidateSession developer_id={dev_id} auth_key=HIDDEN' | This error means that the method signature sent to the API was not determined to be valid. | |
| Invalid signature | This error means that the method signature sent to the API was not determined to be valid. | |
| Maximum number of active sessions reached. | Indicates that you have exceeded rate limits for Session creation and you may be unable to create a new. | You may wait until the limit ends. |
| No match_queue returned. It is likely that the match wasn't live when GetMatchPlayerDetails() was called. | ||
| No Match Details:{match_id} | The player was not found, has private account or haven't played any matches in the last 30 days | |
| Unauthorized Developer Id | ||
| Year, Month, and Day parameters describe an un-representable DateTime. | This error means that the date sent to the API was not determined to be valid format. |
- With the exception of using the
Ping, all calls count towards the rate limits.
- No. PC is the only endpoint guaranteed to work with all methods.
- If you don't already have a
API Key(dev_id and auth_key) for PaladinsAPI, SmiteAPI or even RealmAPI, click here. If you already have, you can use yourAPI Keyto connect to RealmAPI as well.
- If you've already requested your
API Key, check your e-mail. If you can't found your API Key, send an e-mail to Aaron.
- The API don't require a specific programming language to be used, so feel free to choose a language / tool that you are able to do
Http Requestsand readJSONand/orXMLresponses. If you want a wrapper, you can see them here.
I got “Endpoint not Found” when I go to https://api.{game}.com/{game}api.svc.
- You will receive
Endpoint not Foundif you are trying to access a non-existent endpoint, submitting a invalid Method Pattern or even trying to access it directly on your Web Browser.
I'm getting “Maximum number of active sessions reached”. Is there way to close those current Sessions?
- Nop, Sessions are divided into 15 minute intervals. You may store the session_id and use it while is valid.
I'm getting successful responses for the calls but the JSON / XML responses is null. What is happening?
- Did you already checked the ret_msg message? It's used to return a message error when the server-side catch an issue. You can check the ret_msg messages here. See also .
- If a player has “Hide My Profile” enabled in-game, methods will return a null dataset.
When using methods such as Get Match Details, some player info is missing. Why?
- If a player has “Hide My Profile” enabled in-game, some of their data will be unavailable for match history etc.
- The first recommendation would be to use something like page caching or saving the data to a Database so you can poll it from your own database as often as needed. But if you already are doing it and think that is needed to increase your limit, drop an e-mail to Aaron.
- Click here to check how you can get help!
The interface for each endpoint is identical. Therefore, a single application code-base should be able to support all supported platforms
However, since each endpoint is serviced by a unique Web Service, applications must create and maintain separate Sessions for each endpoint. In other words, you cannot use a Session ID created by the SmiteAPI endpoint (via the /createsession method) to make method calls to the PaladinsAPI endpoint.[1]