eRepublik API documentation v0.

eRepublik Labs Limited, 2010-05-15

Official documentation
version 0.6
2010-05-15

Page 1/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

Table of contents
1 Introduction........................................................................................................................ 3 1.1 Welcome to the eAPI! ................................................................................................ 3 1.2 About the eAPI............................................................................................................ 3 1.2.1 History.................................................................................................................. 3 1.2.2 Uses.....................................................................................................................3 1.2.3 OAuth................................................................................................................... 4 1.3 Getting help.................................................................................................................4 2 Getting started....................................................................................................................4 2.1 Data formats............................................................................................................... 4 2.2 Errors.......................................................................................................................... 5 2.3 Feeds.......................................................................................................................... 5 2.3.1 General changes from eAPI v1........................................................................... 5 2.3.2 Citizen..................................................................................................................5 XML output................................................................................................................ 6 Changes.................................................................................................................... 6 2.3.3 Compressed Citizens ......................................................................................... 6 2.3.4 Country................................................................................................................ 7 XML output................................................................................................................ 7 Changes.................................................................................................................... 7 2.3.5 Region................................................................................................................. 7 XML output................................................................................................................ 8 Changes.................................................................................................................... 8 2.3.6 Regions by country..............................................................................................8 2.3.7 Wars by country...................................................................................................9 2.3.8 Citizens by Region............................................................................................... 9 2.3.9 Company............................................................................................................. 9 XML output.............................................................................................................. 10 Changes.................................................................................................................. 10 2.3.10 Exchange Market............................................................................................ 10 XML output.............................................................................................................. 10 Changes.................................................................................................................. 11 2.3.11 Market.............................................................................................................. 11 XML output.............................................................................................................. 11 2.3.12 Industries......................................................................................................... 11 2.3.13 War.................................................................................................................. 12 XML output.............................................................................................................. 12 Changes.................................................................................................................. 12 2.3.14 Battle............................................................................................................... 12 XML output.............................................................................................................. 13 2.3.15 Battle by war....................................................................................................13 2.3.16 Battle combatants............................................................................................13 2.4 Authorized calls.........................................................................................................13 2.4.1 Registering your application.............................................................................. 14 2.4.2 Application states............................................................................................... 15 2.4.3 OAuth URLs...................................................................................................... 16 2.4.4 Return Types..................................................................................................... 16 2.4.5 Citizen info.........................................................................................................16

Page 2/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

1 Introduction
1.1 Welcome to the eAPI!
Welcome to the eRepublik Application Programming Interface (API) documentation! 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 and also offers functions to interact with the game's ecosystem. For comments or suggestions, write an email to api at eRepublik.com.

1.2 About the eAPI

1.2.1 History
The eAPI exists since January 2009 and has been changed and extended a lot since then. Its continuous improvement was put on hold in the middle of 2009. In 2010, the eAPI was completely updated to reflect the changes of a major update to the eRepublik's economy. The eAPI has become an important part of eRepublik and is used in an increasing number of extraordinary applications, developed by the active eRepublik community. Version 0.6 2010-05-15 Documentation of the new eAPI which reflects all changes of eRepublik V2. Version 0.5 2009-01-22 Last documentation about the former eAPI which was used until the release of eRepublik V2.

1.2.2 Uses
The eAPI is a language and platform agnostic set of http services that can be used to build third party applications around eRepublik. The current eAPI can be separated into 3 major categories: Data retrieval: 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. User authentication: eRepublik users can authenticate themselves to your application using their eRepublik citizen account credentials without having to hand out these credentials. You can therefore build secure applications which require its users to authenticate them as eRepublik citizens.

1.2.3 OAuth
For functions where security plays an important role, like the user authentication process, the eAPI uses a mechanism called OAuth in version 1.0a. OAuth is a renowned standard for secure authentication which is used by many sites on the Internet. If you are familiar with OpenID, you pretty much already know how to use OAuth.

Page 3/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

There are ready-to-use modules and libraries for OAuth for most programming languages out there, so instead of telling you how to implement OAuth yourself, we'd like to point you to http://oauth.net/code/ for a list of these modules and encourage you to use them. For more (or all) information on OAuth, visit the official webpage at http://oauth.net/. Note: in contrast to the first version of the eAPI, the current eAPI uses a newer and more secure version of the OAuth mechanism. It requires your application to receive an optional token verif ier at the callback URL and pass it to the exchange request token for access token OAuth call.

1.3 Getting help

If you have any problems or questions regarding the eAPI, here are some places you can find help: The official eAPI google group at http://groups.google.com/group/eapi-private-beta/ The eAPI page (where this document is hosted) at http://api.erepublik.com/ And, if you still didn't find help, send us a mail to api at eRepublik.com

2 Getting started
The eAPI consists of two types of calls: feeds and authorized calls. Feeds are simple resources that can be requested directly without any authorization. Example: point your browser to
http://api.erepublik.com/v2/feeds/countries

to get an XML list of all countries. In order to use authorized calls like citizen authorization, you first need to register your application with the eAPI at http://api.erepublik.com/apps (for more information, see Authorized calls). You will get an OAuth key and OAuth secret to securely sign these types of requests.

2.1 Data formats

The eAPI can transparently output XML (which is the default) or JSON data formats. By default, the response will be formatted in XML. For most calls, the data format can simply be chosen by appending .xml or .json to the call. Example:
http://api.erepublik.com/v2/feeds/countries/1 http://api.erepublik.com/v2/feeds/countries/1.xml

both return information about Romania (country-id 1) in xml.

http://api.erepublik.com/v2/feeds/countries/1.json

returns information about Romania (country-id 1) in json.

Page 4/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

All the below examples will deal with XML data because it's more human readable. Feel free to always use the JSON format if you prefer it!

2.2 Errors
When the eAPI encounters an error, it will usually return an error element containing a time and a message element. Calling the following url
http://api.erepublik.com/v2/feeds/countries/10000

will result in the following error

<error> <time>2010-05-04T18:12:24+02:00</time> <message>invalid id '10000'</message> </error>

These errors are meant for debugging purposes only, so if the eAPI returns such a response, the only information for your application should be there was an error - do not use the message for anything other than reading it yourself.

2.3 Feeds
The eAPI data feeds let you retrieve various information about the game. No registration or authentication is required to use the feeds. To use a feed, simply make an HTTP GET request to the appropriate url.

2.3.1 General changes from eAPI v1

Various changes have been made to the feeds compared to eAPI v1 to improve overall consistency. As quite a lot of developers built their applications on top of the eAPI v1, these changes are documented in the feed descriptions to ease migration to the new eAPI.

2.3.2 Citizen
Returns information about one citizen. The citizen can be retrieved by either his/her id or his/her citizen name. The name parameter of the citizen_by_name call is not case sensitive. Note that for the citizen_by_name call, you have to specify the format (either xml or json) before the name parameter. URLs:
http://api.erepublik.com/v2/feeds/citizens/<id> http://api.erepublik.com/v2/feeds/citizen_by_name/<format>/<name>

Examples:
http://api.erepublik.com/v2/feeds/citizens/1450324

returns information about the citizen with the id 1450324 in xml format.

http://api.erepublik.com/v2/feeds/citizen_by_name/json/calaveradeluxe

returns information about the citizen with the name calaveradeluxe in json data format. The format parameter is not optional. Page 5/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

Note that citizen names can contain special characters, you should therefore always URL escape the name before making the request, replacing all special characters with their corresponding URL escape code. The name fresh!==!dude would become fresh %21%3D%3D%21dude. Otherwise, the eAPI will not recognize some names. XML output
<citizen> <residence> <citizenship> <is-general-manager> <party> <medals> <medal> </medals> ... </citizen>

describes the location where this citizen currently remains describes the country this citizen belongs to contains true if the citizen owns a company describes the party(name, id and is-president) this citizen belongs to Empty if not in a party contains the type of the medal and the amount of medal that have been acquired

Note that this is only an excerpt of the citizen feed.

Changes Changed citizenship to contain a region tag and a country tag. Added residence tag, containing a country and a region tag. Removed country, country-id, region and region-id. This information is now found in the residence tag. Moved fights, damage and military-rank into the military tag. Renamed military-rank to rank. Renamed fights to fight-count. Changed skills to contain the skill id, the skill name and the points in that skill. Removed friends tag.

2.3.3 Compressed Citizens

Returns information about all the citizens of a country. The citizens can be retrieved by either his/her country id. Only xml format is available for now. URLs:
http://api.erepublik.com/v2/feeds/countries/<id>/citizens.xml.gz

Examples:
http://api.erepublik.com/v2/feeds/countries/1/citizens.xml.gz

returns information about the country citizens with the country id 1 in xml format.

Page 6/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

XML output
<citizens> <citizen> <residence> <citizenship> <is-general-manager> <party> <medals> <medal> </medals> ... </citizen> </citizens>

describes the location where this citizen currently remains describes the country this citizen belongs to contains true if the citizen owns a company describes the party(name, id and is-president) this citizen belongs to Empty if not in a party contains the type of the medal and the amount of medal that have been acquired

Note that this is only an excerpt of the citizen feed.

2.3.4 Countries
Returns information about all countries. URL:
http://api.erepublik.com/v2/feeds/countries

Returns a list of all countries in eRepublik.

Changes Instead of just a brief summary, this call now returns a list of fully fetched countries. For the v2 changes made to one country, see the country call.

2.3.5 Country
Returns information about one country by its country id. For detailed information about the regions of a country, see regions by country. For detailed information about the wars a country is involved in, see wars by country. URL:
http://api.erepublik.com/v2/feeds/countries/<id>

Example:
http://api.erepublik.com/v2/feeds/countries/1

Returns information about the country with the id 1.

Page 7/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

XML output
<country> <region-count> <regions> <region> </regions> <citizen-count> <citizen-fee> </country>

the number of regions this country has contains a short description of all regions this country has contains the name and id of the region the number of alive citizens in this country the amount of money a new citizen gets, see http://wiki.erepublik.com/index.php/Citizen_fee for more information

Note that this is only an excerpt of the country feed.

Changes Removed permalink. Renamed total-citizens to citizen-count. Removed permalink from regions. Removed new-citizens-today. Renamed initials to code. Renamed number-of-regions to region-count.

2.3.6 Region
Returns information about one region by its globally unique region id. To get information about the citizens/inhabitants of a region, see citizens by region. URL:
http://api.erepublik.com/v2/feeds/regions/<id>

Example:
http://api.erepublik.com/v2/feeds/regions/9

Returns information about the region with the id 9.

XML output
<region> <buildings> <defense-systems> <defense-system> </defense-systems> <hospitals> <hospital> </hospitals> </buildings> <citizen-count> </region>

contains info about all defense-systems in the region contains info about one defensive-system with area-of-effect, durability, defense-bonus and customization-level contains info about all hospitals in the region contains info about one hospital with area-of-effect, wellness-budget, maxheal-per-citizen and customization-level the number of alive citizens in the region

Page 8/17

eRepublik API documentation v0.6 Note that this is only an excerpt of the region feed.

eRepublik Labs Limited, 2010-05-15

Changes Removed citizens, for information about the citizens of a region, see citizens by region. Renamed population to citizen-count. Renamed constructions to buildings. Removed name and permalink from neighbours. Removed permalink.

2.3.7 Regions by country

Returns detailed information about the regions of a country. Each region looks exactly like a region returned by the Region call. URL:
http://api.erepublik.com/v2/feeds/countries/<id>/regions

Example:
http://api.erepublik.com/v2/feeds/countries/1/regions

Returns all regions of the country with the id 1.

2.3.8 Wars by country

Returns information about the wars a country is involved in. Each war looks exactly like a war returned by the War feed. URL:
http://api.erepublik.com/v2/feeds/countries/<id>/wars

Example:
http://api.erepublik.com/v2/feeds/countries/1/wars

Returns all wars that the country with the id 1 is involved in.

2.3.9 Citizens by Region

Returns the citizen-ids of all the citizens living in this region. This list can get very large and is therefore paginated. The current page, total number of pages and total number of citizens in this region are returned on each page. Note that the page numbers are zeroindexed. URL:

Page 9/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

http://api.erepublik.com/v2/feeds/regions/<id>/citizens/<page>

Example:
http://api.erepublik.com/v2/feeds/regions/9/citizens/0

Returns page 1 (first page) of the list of citizen-ids that are living in the region with id 9.

2.3.10 Company
Returns information about one company. URL:
http://api.erepublik.com/v2/feeds/companies/<id>

Example:
http://api.erepublik.com/v2/feeds/companies/182533

Returns information about the company with the id 182533.

XML output
<company> <customization> <employees> <employee> </employees> <job-offers> <job-offer> </job-offers> </company>

contains the attributes that the products of this company modify. The attributes are dependent on the industry the company is working in contains all citizens that are employed at this company contains the name, id and country(citizenship) of the citizen contains all job-offers of this company contains info about one job offer with the number-of-jobs, skill-id, required-skill, salary and industry

Note that this is only an excerpt of the company feed.

Changes Domain has been replaced by industry. Quality has been replaced by customization level. Added customization.

2.3.11 Exchange Market

The currency exchange market (or monetary market) feed provides information about monetary exchange offers. The currencies that you specify are not case sensitive. This call does only return the 10 best offers for the requested exchange. Note that each country (see Countries) has one currency and there's the GOLD currency in addition. URL:
Page 10/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

http://api.erepublik.com/v2/feeds/exchange/<buy_currency>/<sell_currency>

buy_currency: The currency that you want to buy. sell_currency: The currency that you want to sell. Example:
http://api.erepublik.com/v2/feeds/exchange/RON/GOLD

Returns the 10 best offers that sell you RON for GOLD.

XML output
<offers> <offer> <amount> <exchange-rate> <seller> </offer> </offers>

contains info about one exchange offer the a amount of money that is offered the exchange-rate of the two currencies. This is what you would need to pay for one unit of the offered money contains either a citizen or a company with their name and id

Changes This feed has been revised completely.

2.3.12 Market
The market feed provides information about product offers, filtered by their attributes. URL:
http://api.erepublik.com/v2/feeds/market/<industry_id>/<country_id>/<attr_1>/<attr_2>/<a ttr_3>/<attr_4>

industry_id: The id of the industry in which you want to look for products. See the industries feed for information about the industry ids. country_id: the id of the country in which you want to look for products. attr_1 attr_4: These correspond to the attributes of the product and state the minimum value the product should have at this attribute. Products have different number of attributes (0 to 4), and you must specify the correct number. The order of the attributes is the order they are returned in the industries feed. Example:
http://api.erepublik.com/v2/feeds/market/1/39/10/20

will return the best 10 offers of food (industry_id 1) in Finland (country_id 39) which has at least 10 wellness and 20 happiness. Adding a third attribute to the call would return an error because the food industry's products have only these 2 attributes.

Page 11/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

XML output
<offers> <offer> <customization> </offers> </offers>

contains info about one market offer contains the attributes that this product modifies. The attributes are dependent on the industry this product belongs to

Note that this is only an excerpt of the market feed.

2.3.13 Industries
Returns Information about all industries and their customizable attributes. The attributes are returned in the same order the market feed takes them. URL:
http://api.erepublik.com/v2/feeds/industries

Returns information about all industries and their attributes.

2.3.14 War
Returns information about one war. For detailed information on the battles fought in this war, see battle by war. URL:
http://api.erepublik.com/v2/feeds/wars/<id>

Example:
http://api.erepublik.com/v2/feeds/wars/91

Returns information about the war with the id 91.

Page 12/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

XML output
<war> <progress> <started-at> <finished-at> <finished-reason> </progress> <proclaimed-to> <allies> <ally> </allies> </proclaimed-to> <proclaimed-by> <allies> <ally> <allies> </proclaimed-by> <battles> </war>

contains the date when the war was started. Is always set contains the date that the war finished, empty if the war is still in progress contains the reason why the war ended. Can be PEACE_DECLARED or CONQUERED, empty if the war is still in progress contains name, id and code of the country that this war was declared to contains a list of allies the country has describes an ally with id, name and code contains name, id and code of the country that declared the war contains a list of allies the country has describes an ally with id, name and code contains a list battles with their id

Note that this is only an excerpt of the war feed.

Changes This feed was revised completely.

2.3.15 Battle
Returns information about a battle. For information on the combatants fighting in the battle, see combatants. URL:
http://api.erepublik.com/v2/feeds/battles/<id>

Example:
http://api.erepublik.com/v2/feeds/battles/1

Returns information about the battle with the id 1.

XML output
Note that this is only an excerpt of the battle feed.

Page 13/17

eRepublik API documentation v0.6

<battle> <progress> <started-at> <finished-at> <finished-reason>

eRepublik Labs Limited, 2010-05-15

contains the date when the battle was started. Is always set contains the date when this battle finished. Empty if the battle is still in progress contains the reason why the battle was finished. Can be TIME_LIMIT_REACHED, PEACE_DECLARED, HAS_WINNER, RETREAT or CONQUERED

</progress> </battle>

2.3.16 Battle by war

Returns all battles that were or are fought in a specif ic war. Each battle looks exactly like a battle from the Battle call. URL:
http://api.erepublik.com/v2/feeds/wars/<id>/battles

Example:
http://api.erepublik.com/v2/feeds/wars/639/battles

Returns all battles of the war with the id 639.

2.3.17 Battle combatants

Returns information about combatants of a battle. This feed is paged. The current page, total number of pages and total number of combatants in this battle are returned on each page. Note that the page numbers are zero-indexed. URL:
http://api.erepublik.com/v2/feeds/battles/<id>/combatants/<page>

Example:
http://api.erepublik.com/v2/feeds/battles/1/combatants/2

Returns page 3 of the combatants that fought in the battle with the id 1.

2.4 Authorized calls

Alongside the feeds, the eAPI provides authenticated calls for sensitive operations. For these calls, the OAuth mechanism in version 1.0a is used (http://oauth.net/core/1.0a/). The OAuth mechanism allows the user of your application to authorize the use of protected calls without actually telling you his/her password. For most programming languages there are plugins that will take care of the heavy lifting. A list of such plugins can be found at http://oauth.net/code/. We strongly recommend that you use such a plugin. If you want or need to write the OAuth code yourself, http://oauth.net/documentation/gettingstarted/ is a good starting point.

Page 14/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

2.4.1 Registering your application

Before you can start, you need to register your application with the eAPI. To do that, go to http://api.erepublik.com/apps and login with your eRepublik citizen name and password.

The eAPI login screen.

After you have logged in, click on register a new application. You'll need to provide: The name of your application A short description of what your application does The main URL of your application An optional support URL where your users can get help with your application A callback URL (after authorizing or denying your request, the user will be redirect to this url with the OAuth token and (new to v1 users!) the OAuth token verif ier)

Page 15/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

The application register screen.

After registering your application, you will see a detailed summary. Here you will find your consumer key and your consumer secret. You will need both of them to make authenticated calls to the eAPI. You can always see your consumer key and consumer secret later by logging to the eAPI at http://api.erepublik.com/apps and clicking on the name of your application. WARNING: Do not share the consumer secret with anyone. It allows everyone to forge requests on your behalf.

2.4.2 Application states

In order to allow eAPI developers to develop and test their applications without making any changes to the live environment (=eRepublik), applications have two states: sandboxed and live. Every new application will be in sandboxed state by default. In this state citizen authentication will work as expected. In sandboxed state, you can edit your application details as you wish. After you are finished developing an testing it, you can request live state. Before requesting live state by clicking Go Live in the table view of your applications, make sure that the application details (name, description, URLs) are correct because you won't be able to change them in live state.

Page 16/17

eRepublik API documentation v0.6

eRepublik Labs Limited, 2010-05-15

The application list with Go Live links.

Once you requested live state, the eAPI team will review your request and approve or reject your application. When approved, you may switch your application's state from sandboxed to live and also vice versa at any time. Note that if you switch back from live to sandboxed state and edit your application's details, any former approval will be revoked and your application needs to be approved again!

2.4.3 OAuth URLs

The URLs to get request and access tokens are as follows: To get a request token:
http://api.erepublik.com/oauth/request_token

To get an access token (change request token for access token):

http://api.erepublik.com/oauth/access_token

2.4.4 Return Types

Like feeds, authorized calls can either return XML (default) or JSON data formats. You can specify the format by appending either .xml or .json to the url.

2.4.5 Citizen info

The purpose of this service is to verify the identity of the user. You have to get a request token, let the user authorize it and then get am access token before you can call this service. For more information, see OAuth. Service URL: http://api.erepublik.com/citizen/info Scope: citizen/info Parameters: filter (optional): additional information you want to retrieve, as a comma separated list. Currently there are no additional information to be retrieved, so this parameter remains unused by now. Returns: Information about the citizen, identical to the return value of the citizen feed, except that you can add a filter to retrieve additional information. Note that the access token for this call expires after it has been used.
Page 17/17