eapi-docs

eRepublik API documentation v0.6 eRepublik Labs Limited, 2010-05-15

Official documentationversion 0.6

2010-05-15

/17


Table of contents1 Introduction........................................................................................................................ 3

1.1 Welcome to the eAPI! ................................................................................................ 31.2 About the eAPI............................................................................................................3

1.2.1 History.................................................................................................................. 31.2.2 Uses.....................................................................................................................31.2.3 OAuth................................................................................................................... 4

1.3 Getting help.................................................................................................................42 Getting started....................................................................................................................4

2.1 Data formats............................................................................................................... 42.2 Errors.......................................................................................................................... 52.3 Feeds.......................................................................................................................... 5

2.3.1 General changes from eAPI v1........................................................................... 52.3.2 Citizen..................................................................................................................5

XML output................................................................................................................ 6Changes.................................................................................................................... 6

2.3.3 Compressed Citizens ......................................................................................... 62.3.4 Country................................................................................................................ 7

XML output................................................................................................................ 7Changes.................................................................................................................... 7

2.3.5 Region................................................................................................................. 7XML output................................................................................................................ 8Changes.................................................................................................................... 8

2.3.6 Regions by country..............................................................................................82.3.7 Wars by country...................................................................................................92.3.8 Citizens by Region............................................................................................... 92.3.9 Company............................................................................................................. 9

XML output.............................................................................................................. 10Changes.................................................................................................................. 10

2.3.10 Exchange Market............................................................................................ 10XML output.............................................................................................................. 10Changes.................................................................................................................. 11

2.3.11 Market.............................................................................................................. 11XML output.............................................................................................................. 11

2.3.12 Industries......................................................................................................... 112.3.13 War.................................................................................................................. 12

XML output.............................................................................................................. 12Changes.................................................................................................................. 12

2.3.14 Battle............................................................................................................... 12XML output.............................................................................................................. 13

2.3.15 Battle by war....................................................................................................132.3.16 Battle combatants............................................................................................13

2.4 Authorized calls.........................................................................................................132.4.1 Registering your application..............................................................................142.4.2 Application states............................................................................................... 152.4.3 OAuth URLs...................................................................................................... 162.4.4 Return Types..................................................................................................... 162.4.5 Citizen info.........................................................................................................16

/17


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 HistoryThe 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-15Documentation of the new eAPI which reflects all changes of eRepublik V2.

Version 0.5 – 2009-01-22Last documentation about the former eAPI which was used until the release of eRepublik V2.

1.2.2 UsesThe 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 OAuthFor 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.

/17


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 verifier” at the callback URL and pass it to the “exchange request token for access token” OAuth call.

1.3 Getting helpIf 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 startedThe 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 formatsThe 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.

/17

http://oauth.net/code/

http://api.erepublik.com/apps

http://api.erepublik.com/

http://groups.google.com/group/eapi-private-beta/

http://oauth.net/


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 ErrorsWhen the eAPI encounters an error, it will usually return an error element containing a time and a message element. Calling the following url


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 FeedsThe 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 v1Various 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 CitizenReturns 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.

/17


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> describes the location where this citizen currently remains <citizenship> describes the country this citizen belongs to <is-general-manager> contains true if the citizen owns a company <party> describes the party(name, id and is-president) this citizen belongs to

Empty if not in a party <medals>

<medal> contains the type of the medal and the amount of medal that have been acquired </medals> ...</citizen>

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 CitizensReturns 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.

/17


XML output

<citizens>

<citizen>

<residence> describes the location where this citizen currently remains <citizenship> describes the country this citizen belongs to <is-general-manager> contains true if the citizen owns a company <party> describes the party(name, id and is-president) this citizen belongs to

Empty if not in a party <medals>

<medal> contains the type of the medal and the amount of medal that have been acquired </medals> ...</citizen>

</citizens>

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

2.3.4 CountriesReturns 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 CountryReturns 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:


Returns information about the country with the id 1.

/17


XML output

<country>

<region-count> the number of regions this country has <regions> contains a short description of all regions this country has <region> contains the name and id of the region </regions>

<citizen-count> the number of alive citizens in this country <citizen-fee> the amount of money a new citizen gets, see

http://wiki.erepublik.com/index.php/Citizen_fee for more information</country>

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 RegionReturns 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> contains info about all defense-systems in the region <defense-system> contains info about one defensive-system with area-of-effect, durability,

defense-bonus and customization-level </defense-systems>

<hospitals> contains info about all hospitals in the region <hospital> contains info about one hospital with area-of-effect, wellness-budget, max-

heal-per-citizen and customization-level </hospitals> </buildings>

<citizen-count> the number of alive citizens in the region</region>

/17

http://wiki.erepublik.com/index.php/Citizen_fee


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

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 countryReturns 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 countryReturns 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 RegionReturns 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 zero-indexed.

URL:

/17


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 CompanyReturns 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> contains the attributes that the products of this company modify. The attributes are dependent on the industry the company is working in

<employees> contains all citizens that are employed at this company <employee> contains the name, id and country(citizenship) of the citizen </employees>

<job-offers> contains all job-offers of this company <job-offer> contains info about one job offer with the number-of-jobs, skill-id, required-skill,

salary and industry </job-offers></company>

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

/17


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> contains info about one exchange offer <amount> the a amount of money that is offered <exchange-rate> the exchange-rate of the two currencies. This is what you would need to pay for

one unit of the offered money <seller> contains either a citizen or a company with their name and id </offer></offers>

Changes

• This feed has been revised completely.

2.3.12 MarketThe 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>/<attr_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.

/17


XML output

<offers>

<offer> contains info about one market offer <customization> contains the attributes that this product modifies. The attributes are dependent on

the industry this product belongs to </offers></offers>

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

2.3.13 IndustriesReturns 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 WarReturns 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.

/17


XML output

<war> <progress>

<started-at> contains the date when the war was started. Is always set <finished-at> contains the date that the war finished, empty if the war is still in progress <finished-reason> contains the reason why the war ended. Can be “PEACE_DECLARED”

or “CONQUERED”, empty if the war is still in progress </progress>

<proclaimed-to> contains name, id and code of the country that this war was declared to <allies> contains a list of allies the country has <ally> describes an ally with id, name and code </allies>

</proclaimed-to> contains name, id and code of the country that declared the war <proclaimed-by>

<allies> contains a list of allies the country has <ally> describes an ally with id, name and code <allies> </proclaimed-by>

<battles> contains a list battles with their id</war>

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

Changes

• This feed was revised completely.

2.3.15 BattleReturns 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.

/17


<battle> <progress>

<started-at> contains the date when the battle was started. Is always set <finished-at> contains the date when this battle finished. Empty if the battle is still in

progress <finished-reason> 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 warReturns all battles that were or are fought in a specific 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 combatantsReturns 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 callsAlongside 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/getting-started/ is a good starting point.

/17

http://oauth.net/documentation/getting-started/

http://oauth.net/documentation/getting-started/

http://oauth.net/code/

http://oauth.net/core/1.0a/


2.4.1 Registering your applicationBefore 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 verifier)

/17

http://api.erepublik.com/login


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 statesIn 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.

/17

http://api.erepublik.com/apps


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 URLsThe 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 TypesLike 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 infoThe 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.

/17

eapi-docs

Documents