The purpose of the document is to give you an overview of the features of the eRepublik API (hereafter referred to as eAPI). The eAPI can be used to retrieve data from the erepublik.com game in application-friendly formats like XML and JSON. For comments or suggestions, write an email to api@erepublik.com.
The eAPI is a language and platform agnostic set of http services that can be used to build third party applications around eRepublik. You can retrieve information about citizens, companies, wars and similar entities on eRepublik. The data will be returned in either XML or JSON data formats. These functions are available to the public and may be used without any authorization or registration.
The eAPI uses REST as a software architecture style and every entity like citizen, war or company will be treated as a resource. The user needs to send in the request headers information about a public key (unique for each api caller) and a digest calculated with a certain algorithm that will be described later on. Once authenticated, the caller can access any resource that suits the permission level of his public key.
If you have any problems or questions regarding the eAPI, send us a mail to api@erepublik.com
The eAPI calls are simple authorized requests to a specific url. The url has a structure similar to this:
https://api.erepublik.com/{resource}/{action}?{param1}&{param2}&....
Currently we have a number of 8 resources: citizen, country, countries, region, map, industries, battle, war
. Each resource has a list of possible actions and each action has a list of accepted parameters, mandatory or optional
and is able to return JSON or XML response (default is JSON).
For example, if we need to access action profile
from citizen
resource, we need to do an authorized request to this url:
https://api.erepublik.com/citizen/profile?citizenId=123In this example
citizenId
is a parameter accepted by the profile
action in 'citizen' resource.
Each user has a pair of keys: a public key and a private key also named as secret key. The secret key needs to be totally secret and you should not send it via api request. Erepublik will never request your secret key and you should never give this key to anyone.The authorization needs two headers sent via eAPI request: Date and Auth.
The Date header needs to be the current date and time of the request (e.g. Tue, 04 Sep 2012 15:57:48)
The Auth header is actually a key that will validate your request in our system. Its structure is {public_key}/{digest}
where {public_key}
is your public key provided by eRepublik
and {digest}
is a hash that represents an encrypted value of a concatenated string formed from {resource}
, {action}
, {params}
(if they exist), and {date}
(the same value Date header has).
For example, let's say that your resource is citizen
, your action is profile
and profile
action takes citizenId
parameter this means that the request url looks like this:
https://api.erepublik.com/citizen/profile?citizenId=123Based on the formula explained above, the concatenated string should look like this:
citizen:action:citizenid=123:Tue, 04 Sep 2012 15:57:48
(every part should be converted to lower case with the exception of date).
Now the Auth header can be simply calculated by generating a hash value using HMAC method and sha256 algorithm based on your {secret_key}
.
By default the eAPI responds using JSON data format. If you need XML response then another header should be added in the request, 'Accept' header, with the value of 'application/xml'
The following list shows a full list of current implemented resources and each resource's actions with the correct parameters.
Resource | Action name | ||||
---|---|---|---|---|---|
citizen |
|
||||
country |
|
||||
countries |
|
||||
region |
|
||||
map |
|
||||
industries |
|
||||
battle |
|
||||
war |
|
<?php function apiCall($resource, $action, $query = false) { $private = ''; $public = ' '; date_default_timezone_set('UTC'); $date = gmdate(DATE_RFC1123); $digest = hash_hmac('sha256', strtolower($resource.':'.$action.($query ? ':'.http_build_query($query) : '')).':'.$date, $private); $headers = array( "Date: $date", "Auth: $public/$digest", //"Accept: application/xml" ); $ch = curl_init(); curl_setopt( $ch, CURLOPT_URL, 'https://api.erepublik.com/'.$resource.'/'.$action.(($query) ? '?'.http_build_query($query): "")); curl_setopt( $ch, CURLOPT_HTTPHEADER, $headers ); curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); $result = curl_exec( $ch ); curl_close( $ch ); return $result; } $result = apiCall('citizen', 'profile', array('citizenId' => 1234)); echo $result; //if xml //echo simplexml_load_string($xml);