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.


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

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:

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
Action Name Action params
  • citizenId (positive)
Action Name Action params
  • countryId (positive)
Action Name Action params
Action Name Action params
  • regionId (positive)
  • page (positive)
Action Name Action params
Action Name Action params
Action Name Action params
  • battleId (positive)
Action Name Action params
  • warId (positive)


1. PHP

function apiCall($resource, $action, $query = false) {
$private = '{private key}';
$public = '{public key}';

$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);

2. Python

import argparse
import hashlib
import hmac
import requests
from datetime import datetime

def api_call(resource, action, query=None):
    private_key = ''
    public_key = ''
    date = datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S +0000')
    message = f"{resource.lower()}:{action}"
    if query:
        message += f":{requests.compat.urlencode(query)}"
    message += f":{date}"
    digest = hmac.new(private_key.encode(), message.encode(), hashlib.sha256).hexdigest()
    headers = {
        "Date": date,
        "Auth": f"{public_key}/{digest}"
    url = f"https://api.erepublik.com/{resource}/{action}"
    if query:
        url += f"?{requests.compat.urlencode(query)}"

    response = requests.get(url, headers=headers)

    return response.text

def main():
    parser = argparse.ArgumentParser(description='Make API calls to eRepublik.')
    parser.add_argument('resource', type=str, help='Resource to call')
    parser.add_argument('action', type=str, help='Action to perform on the resource')
    parser.add_argument('--query', nargs='*', help='Query parameters')

    args = parser.parse_args()

    query_params = {}
    if args.query:
        for param in args.query:
            key, value = param.split('=')
            query_params[key] = value

    result = api_call(args.resource, args.action, query_params)

if __name__ == "__main__":