Usage

To use erepapi in a project first set up api keys then you can use any of the classes described below:

Setting API keys

To use erepublik api you must obtain private and public api keys.

To set those keys import api from erepapi:

from erepapi import api
api.public_key=<your public key>
api.private_key=<your private key>

Citizen Class

To use citizen class just import it from erepapi:

from erepapi import Citizen

You can’t instantiate empty Citizen object, Citizen class takes citizen ID when initializing as only argument.

Example of getting citizen name and some other info:

#Ask for Citizen ID from user then show citizen info
#Python 2.7, change raw_input to input for 3.x version

from erepapi import api, Citizen

api.public_key="your public key goes here"
api.private_key="your private key goes here"

while True:
    entered_id=raw_input("Enter citizen id:\n>>>")
    try:
        citizen_info=Citizen(entered_id)
        print("Username:{}\nStrength:{}\nMilitary Rank:{}\n{}".format(citizen_info.name,
                                                        citizen_info.strength,
                                                        citizen_info.rank_value,
                                                        "*"*20))
        if citizen_info.in_unit:
            print("Unit name:{}\nPlayer is unit leader:{}\n".format(citizen_info.unit_name,
                                                                    citizen_info.unit_leader))

        print("Citizen has following achievements:")
        for achievement,ammount in citizen_info.achievements:
            print("{}:{}".format(achievement,ammount))
    except ValueError:
        print("The ID you supplied is not a valid one, try again.")


#Output

# Enter citizen id:
# >>>1649964
# Username:Unihorn
# Strength:37153.371
# Military Rank:64
# ********************
# Unit name:Tesla Troopers
# Player is unit leader:False
#
# Citizen has following achievements:
# Ambassador:1
# Hero:25
# Super trooper:148
# Hard worker:50
# Mercenary:1
# Congressman:6
# Media mogul:2
# True patriot:26
# Resistance hero:2
# Campaign hero:1
# President:1
# Total:264
# Society builder:1
# Enter citizen id:
# >>>

Citizen object variables

Variable name	Description	Type
id	supplied user ID	string
name	Profile name	string
is_alive	Is user profile alive	boolean
has_avatar	Whether user has custom avatar or not	boolean
experience_points	Current number of experience points user has	integer
level	Current level number	integer
birthday	Date of profile creation, string. MMM DD, YYYY	string
national_rank	Current national rank number	integer
profile_url	full URL to user profile based on ID	string
strength	current number of strength points	float
rank_points	number of rank points	integer
rank_stars	number of rank stars	integer
rank_icon	URL to rank icon file	string
achievements	Dictionary of achievements k,v = name,quantity	dictionary
citizenship_country_id	self explanatory	integer
citizenship_country_name	self explanatory	string
citizenship_country_initials	self explanatory	string
citizenship_region_id	self explanatory	integer
citizenship_region_name	self explanatory	string
residence_country_id	self explanatory	integer
residence_country_name	self explanatory	string
residence_country_initials	self explanatory	string
residence_region_id	self explanatory	integer
residence_region_name	self explanatory	string
party_member	true if player is part of political party otherwise false.	boolean
party_id	id of the party (if in one)	integer
party_name	name of the party	string
is_president	True if selected player is party president, otherwise False	boolean
in_unit	true if player is part of political party otherwise false	boolean
unit_id	id of the military unit (if in unit)	integer
unit_name	name of the unit	string
unit_leader	true if player is leader of the military unit, otherwise False	boolean
owns_newspaper	True if player owns newspapers otherwise False	boolean
newspaper_id	id of the newspapers (if one exists)	integer
newspaper_name	name of the newspapers	string

Allies dictionary structure; country names are keys(strings):

{
    country_name:{"id":country_id,
                  "initials":country_initials},

    country_name:{"id":country_id,
                  "initials":country_initials},
    [...]
}

Error types raised

ValueError if provided ID is not valid or doesn’t exist.

Battle Class

To use citizen class just import it from erepapi:

from erepapi import Battle

You can’t instantiate empty Battle object, Battle class takes battle ID when initializing as only argument.

Example of getting battle info from ID:

#Ask for battle/resistance ID from user then show battle info
#Python 2.7, change raw_input to input for 3.x version

from erepapi import api, Battle

api.public_key="your public key goes here"
api.private_key="your private key goes here"

while True:
    entered_id=raw_input("Enter battle id:\n>>>")

    battle_info=Battle(39841)

    try:
        print("{} (attacker) VS {} (defender)".format(battle_info.attacker_initials,
                                                      battle_info.defender_initials))
        print("Battle:{}; for {}\nResistance:{}\nStarted:{}\nEnded:{}".format(battle_info.id,
                                                                              battle_info.region_name,
                                                                              battle_info.is_resistance,
                                                                              battle_info.start,
                                                                              battle_info.end))
        print("Attacker allies (Name/ID):")
        for k,v in battle_info.attacker_allies.items():
            print "\t",k,v['id']

        print("Defender allies (Name/ID):")
        for k,v in battle_info.defender_allies.items():
            print "\t",k,v['id']

        print("-"*30)

    except ValueError:
        print("Invalid battle ID, try again...")


# Output

# Enter battle id:
# >>>39841
# TH (attacker) VS HR (defender)
# Battle:39841; for Andhra Pradesh
# Resistance:False
# Started:2013-03-29 08:55:12
# Ended:2013-03-30 02:53:05
# Attacker allies (Name/ID):
# 	Poland 35
# 	Indonesia 49
# 	Serbia 65
# 	Republic of Macedonia (FYROM) 79
# 	United Kingdom 29
# 	Slovenia 61
# 	Latvia 71
# 	Chile 64
# 	Hungary 13
# 	Japan 45
# 	Spain 15
# 	Bulgaria 42
# Defender allies (Name/ID):
# 	Canada 23
# 	Turkey 43
# 	Italy 10
# 	France 11
# 	Ireland 54
# 	Argentina 27
# 	Norway 37
# 	Israel 58
# 	Iran 56
# 	China 14
# 	Bosnia and Herzegovina 69
# 	Ukraine 40
# 	Netherlands 31
# 	Finland 39
# 	Sweden 38
# 	Republic of China (Taiwan) 81
# 	Russia 41
# 	Romania 1
# 	Albania 167
# 	Uruguay 74
# 	Colombia 78
# 	Greece 44
# ------------------------------
# Enter battle id:
# >>>

Battle object variables

Variable name	Description	Type
region_id	id of the on which the battle is being fought on	integer
region_name	name of the region	string
start	date and time of the battle start, YYYY-MM-DD HH:MM:SS format	string
end	date and time of the battle end YYYY-MM-DD HH:MM:SS format, otherwise None	string
finish_reason	reason for battle finish if the battle has ended	string
defender_id	id of the country that’s being attacked(defender)	integer
attacker_id	id of the country that’s attacking(attacker) defender	integer
defender_initials	initials of the country that’s being attacked(defender)	string
attacker_initials	initials of the country that’s attacking(attacker)	string
defender_allies	allies of the country that’s being attacked(defender)	dictionary
attacker_allies	allies of the country that’s attacking(attacker)	dictionary

Error types raised

ValueError if provided ID is not valid or doesn’t exist.

Country Regions Class

To use country regions class just import it from erepapi:

from erepapi import CountryRegions

You can’t instantiate empty CountryRegions object, CountryRegions class takes country ID when initializing as only argument.

Example usage:

#Ask for country ID from user then show all regions that belong to that country
# then prompt region name and display more info about it.
#Python 2.7, change raw_input to input for 3.x version

from erepapi import api, CountryRegions

api.public_key="your public key goes here"
api.private_key="your private key goes here"


while True:
    entered_id=raw_input("Enter Country id:\n>>>")
    try:
        regions_object=CountryRegions(entered_id)

        print("All regions:")
        for region in regions_object.regions:
            print("\t",region.name)

        info_region_name=raw_input("Enter region name to find out more about it:\n>>>")
        region_object=regions_object.get(info_region_name,None)

        if region_object is None:
            print("That region is not part of this country... exiting")
        else:
            print("Name:{}\nID:{}\nOwner ID:{}\nOriginal owner ID:{}\nURL:{}".format(region_object.name,
                                                                                     region_object.id,
                                                                                     region_object.owner_id,
                                                                                     region_object.original_owner_id,
                                                                                     region_object.url))

    except ValueError:
        print("Invalid country id")

#Enter Country id:
#>>>65
#All regions:
#('\t', u'Kosovo')
#('\t', u'Vojvodina')
#('\t', u'Belgrade')
#('\t', u'Sumadija')
#('\t', u'Eastern Serbia')
#('\t', u'Western Serbia')
#('\t', u'Raska')
#('\t', u'Southern Serbia')
#Enter region name to find out more about it:
#>>>Belgrade
#Name:Belgrade
#ID:635
#Owner ID:65
#Original owner ID:65
#URL:http://www.erepublik.com/en/main/region/Belgrade

Battle object variables

regions variable contains list of Region objects each with following variables:

Variable name	Description	Type
name	Name of the region	string
id	ID of the region	intger
owner_id	ID of the country that’s current owner	integer
original_owner_id	ID of the original owner country	integer
url	Full in game url for that region	string

Error types raised

ValueError if the supplied Country ID is invalid.

Region Class

To use region class just import it from erepapi:

from erepapi import Regions

This will return object with id and citizenIDs variables, the latter contains list of citizen IDs that live in that region.

Regions requries id parameter and accepts optional page param (as integer), the first one being the region ID the second page of the ids. 100 ids are displayed max per page.

If region has no citizens or the page is empty citizenIDs will be equal to None

Example usage:

from erepapi import api, Region

api.public_key="your public key"
api.private_key="your private key"

region=Region(635, page=2)

for citizenID in region.citizenIDs:
    #do something with citizenID (integer)

Error types raised

ValueError if the supplied ID or page number is invalid type.

Country Class

To use region class just import it from erepapi:

from erepapi import Country

Base class has None values assigned to variables below and all_countries variable that contains list of names for every country that’s available in game, list is fetched from API not hard coded

After initialization 2 functions can be used to update country variables, by_name and by_id these functions require country name or country ID, respectively, for information on which country data to fetch.

Variables stay equal to None if supplied id or name are invalid/ don’t exist.

Example usage:

#Ask for country ID, name or just print list of all countries
#Python 2.7, change raw_input to input for 3.x version

from erepapi import api, Country

api.public_key="your public key goes here"
api.private_key="your private key goes here"


country=Country()

while True:
    user_choice=int(raw_input("Enter option.\n1. List all countries\n"
                              "2. Print country info from name\n"
                              "3. Print country info from ID\n>>>"))

    if user_choice==1:
        for item in country.all_countries:
            print(item)

    elif user_choice==2:
        country_name=raw_input("Enter country name:\n>>>")
        country.by_name(country_name)
        if country.name is None:
            print("No country found by that name")
        else:
            print("Country:{}\nID:{}\nInitials:{}\nColor:{}\n"
                  "Continent ID:{}\nContinent Name:{}\n"
                  "Capital region ID:{}\nCapital region name:{}".format(
                country.name,country.id,country.initials,
                country.color,country.continent_id,
                country.continent_name,country.capital_region_id,
                country.capital_region_name
            ))

    elif user_choice==3:
        country_id=raw_input("Enter country ID:\n>>>")
        country.by_id(country_id)
        if country.name is None:
            print("No country found by that ID")
        else:
            print("Country:{}\nID:{}\nInitials:{}\nColor:{}\n"
                  "Continent ID:{}\nContinent Name:{}\n"
                  "Capital region ID:{}\nCapital region name:{}".format(
                country.name, country.id, country.initials,
                country.color, country.continent_id,
                country.continent_name, country.capital_region_id,
                country.capital_region_name
            ))

    else:
        print("Invalid input, try again")


# Output

#Enter option.
#1. List all countries
#2. Print country info from name
#3. Print country info from ID
#>>>1
#Albania
#Argentina
#Australia
#Austria
#[...]
#Enter option.
#1. List all countries
#2. Print country info from name
#3. Print country info from ID
#>>>2
#Enter country name:
#>>>Serbia
#Country:Serbia
#ID:65
#Initials:CS
#Color:FFB47F
#Continent ID:1
#Continent Name:None
#Capital region ID:743
#Capital region name:Kosovo
#Enter option.
#1. List all countries
#2. Print country info from name
#3. Print country info from ID
#>>>3
#Enter country ID:
#>>>65
#Country:Serbia
#ID:65
#Initials:CS
#Color:FFB47F
#Continent ID:1
#Continent Name:None
#Capital region ID:743
#Capital region name:Kosovo
#Enter option.
#1. List all countries
#2. Print country info from name
#3. Print country info from ID
#>>>

Country object variables

Variable name	Description	Type
id	Country ID	integer
name	Country name	string
initials	Country initials	string
color	Country color code	string
continent_id	Continent ID, this will always be equal to None but it exists...	string
continent_name	Continent name, always None	string
capital_region_id	Capital region ID of that country	integer
capital_region_name	Capital region name of that country	string

Error types raised

None