Welcome to the eAPI!

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.

About the eAPI

1. Uses

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.

2. REST

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.

3. Getting help

If you have any problems or questions regarding the eAPI, send us a mail to api@erepublik.com

Getting started

The eAPI calls are simple authorized requests to a specific url. The url has a structure similar to this:

http://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:

http://api.erepublik.com/citizen/profile?citizenId=123
In this example citizenId is a parameter accepted by the profile action in 'citizen' resource.

1. Authorization

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:

http://api.erepublik.com/citizen/profile?citizenId=123
Based 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}.

2. Data formats

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'

List of resources

The following list shows a full list of current implemented resources and each resource's actions with the correct parameters.

Resource Action name
citizen
Action Name Action params
profile
  • citizenId (positive)
country
Action Name Action params
regions
  • countryId (positive)
countries
Action Name Action params
index
region
Action Name Action params
citizens
  • regionId (positive)
  • page (positive)
map
Action Name Action params
data
industries
Action Name Action params
index
battle
Action Name Action params
index
  • battleId (positive)
war
Action Name Action params
battles
  • warId (positive)

Examples

1. PHP

<?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, 'http://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);