AI_BASE



Echo basic information about how to interact with the API here:

USING THE API:

There are TWO methods of using this API:

Method 1) send everything as POST variables to /api/function

Method 2) send JSON's
In this case send api_function='function' & api_payload={a json string} to /api

Examples:

Method 1:
http://www.earthempires.com/api/server?username=qzjul&ai_key=fake_api_key&server=ai

Method 2:
http://www.earthempires.com/api?api_function=server&api_payload={"username":"qzjul","ai_key":"fake_api_key","server":"ai"}

IF the flag 'compat=1' is not set, the server will now respond with a pure json response.

FUNCTIONS:

info     => user information
            Fields:
                username,
                ai_key

server   => server information
            (note, turn rate is seconds per turn; times are unix time)
            Fields:
                username,
                ai_key,
                server (server=ai for ai server)
                THESE THREE FIELDS WILL BE HEREAFTER REFERRED TO AS "U/A/S"

create   => create a country
            Fields:
                U/A/S,
                cname (country name);
            Response:
                cnum

main     => country info basics
            Fields:
                username,
                ai_key,
                server (server=ai for ai server),
                cnum (country number);
                THESE FOUR FIELDS WILL BE HEREAFTER REFERRED TO AS "U/A/S/C"
            Response:
                basic stats

advisor  => country info
            Fields:
                U/A/S/C;
            Response:
                advisor stats + some additional info

                networth
                land
                pop
                money
                pci
                food
                oil
                b_ent
                b_res
                b_indy
                b_mb
                b_lab
                b_farm
                b_rig
                b_cs
                m_spy
                m_tr
                m_j
                m_tu
                m_ta
                t_mil
                t_med
                t_bus
                t_res
                t_agri
                t_war
                t_ms
                t_weap
                t_indy
                t_spy
                t_sdi
                empty
                nw_mil
                nw_tech
                nw_land
                nw_other
                nw_market
                foodpro
                foodcon
                foodnet
                oilpro
                tpt
                taxes
                expenses
                corruption
                expenses_alliance
                expenses_land
                expenses_mil
                expense_spy
                expense_tr
                expense_j
                expense_tu
                expense_ta
                income
                cashing
                tot_j
                t_tot
                pt_mil
                pt_med
                pt_bus
                pt_res
                pt_agri
                pt_war
                pt_ms
                pt_weap
                pt_indy
                pt_spy
                pt_sdi
                cname
                govt
                taxrate
                ps_tr
                ps_j
                ps_ta
                bpt
                build_cost
                cnum
                explore_rate
                turns
                turns_stored
                turns_played
                g_tax
                protection
                pro_spy
                pro_tr
                pro_j
                pro_tu
                pro_ta


pm_info  => private market info
            Fields:
                U/A/S/C;
            Response:
                buy_price,
                available,
                sell price => components:
                            m_spy (only sell),
                            m_tr,
                            m_j,
                            m_tu,
                            m_ta,
                            m_bu,
                            m_oil (only if oil allowed on PM)

govt     => change government!
            Fields: U/A/S/C,
                    govt;
            Response:
                    govt

cash     => cash turns!
            Fields: U/A/S/C,
                turns;
            Response:
                turns

explore  => explore turns!
            Fields:
                U/A/S/C,
                turns;
            Response:
                new_land,
                build_cost,
                explore_rate,
                turns,
                tpt

build    => build stuff!
            Fields:
                U/A/S/C,
                build (array) => (optional) components:
                    ent,
                    res,
                    indy,
                    mb,
                    lab,
                    farm,
                    rig,
                    cs
            Response:
                built (array),
                cost,
                bpt,
                turns,
                tpt
destroy    => destroy buildings!
                Fields:
                    U/A/S/C,
                    destroy (array) => (optional) components:
                        ent,
                        res,
                        indy,
                        mb,
                        lab,
                        farm,
                        rig,
                        cs,
                        land
                Response:
                    built (array),
                    cost,
                    empty,
                    bpt,
                    turns,
                    tpt

pm       => buy/sell stuff on PM!
            Fields:
                U/A/S/C,
                buy,
                sell => components (both):
                    m_spy (only sell),
                    m_tr,
                    m_j,
                    m_tu,
                    m_ta,
                    m_bu,
                    m_oil (only if oil allowed on PM)
            Response:
                cost (buy),
                money (sell),
                goods (as above)

tech     => research tech!
            Fields:
                U/A/S/C,
                tech (array) => (optional) components:
                    mil,
                    med,
                    bus,
                    res,
                    agri,
                    war,
                    ms,
                    weap,
                    indy,
                    spy,
                    sdi
            Response:
                teched (array),
                turns,
                tpt

market   => public market info!
            Fields:
                U/A/S/C
            Response:
                buy_price,
                available,
                so_price => components:
                    m_tr,
                    m_j,
                    m_tu,
                    m_ta,
                    m_bu,
                    m_oil,
                    mil,
                    med,
                    bus,
                    res,
                    agri,
                    war,
                    ms,
                    weap,
                    indy,
                    spy,
                    sdi

onmarket => goods on public market info!
            Fields:
                U/A/S/C
            Response:
                goods => components:
                    array of goods on market => components:
                        type,
                        price,
                        quantity,
                        time



market_search => get historical information on market sales for a single market good, excludes auto sales
            Fields:
                U/A/S/C
                good - name of the market good. acceptable examples: m_tr, food, mu_bu, oil, m_oil, bus, t_bus
                look_back_hours - number of hours to look back from 1 to 72.
                    for example, a value of 2 means the search runs over the past 2 hours
            Response:
                'low_price' => the lowest sold price of the good over the search period
                'high_price' => the highest sold price of the good over the search period
                'total_units_sold' => the total number of units sold of the good over the search period
                'total_sales' => the sales total (price * volume) of the good over the search period
                'avg_price' => the average sold price of the good over the search period
                'no_results' - true if no sales were during the search period. if true, all other outputs will be null


buy      => buy goods!
            Fields:
                U/A/S/C,
                buy => (optional) array components:
                    m_tr,
                    m_j,
                    m_tu,
                    m_ta,
                    m_bu,
                    m_oil,
                    mil,
                    med,
                    bus,
                    res,
                    agri,
                    war,
                    ms,
                    weap,
                    indy,
                    spy,
                    sdi => components:
                        price,
                        quantity
            Response:
                bought => components:
                    array of goods bought
            Sometimes:
                if tech was bought, returns new tech percentage

sell     => sell goods!
            Fields:
                U/A/S/C,
                price    => (optional) components:
                    m_tr,
                    m_j,
                    m_tu,
                    m_ta,
                    m_bu,
                    m_oil,
                    mil,
                    med,
                    bus,
                    res,
                    agri,
                    war,
                    ms,
                    weap,
                    indy,
                    spy,
                    sdi
                quantity => (optional) components:
                    m_tr,
                    m_j,
                    m_tu,
                    m_ta,
                    m_bu,
                    m_oil,
                    mil,
                    med,
                    bus,
                    res,
                    agri,
                    war,
                    ms,
                    weap,
                    indy,
                    spy,
                    sdi
                (optional) tonm (Time on Market) =>  (optional) components:
                    m_tr,
                    m_j,
                    m_tu,
                    m_ta,
                    m_bu,
                    m_oil,
                    mil,
                    med,
                    bus,
                    res,
                    agri,
                    war,
                    ms,
                    weap,
                    indy,
                    spy,
                    sdi
            Response:
                sell (array),
                turns;


market_recall => recall market goods or tech
            Fields:
                U/A/S/C,
                type    => "GOODS" or "TECH"


indy     => change indtustrial production percentages! (should add to 100%)
            Fields:
                U/A/S/C,
                pro => (optional) compoments:
                    pro_spy,
                    pro_tr,
                    pro_j,
                    pro_tu,
                    pro_ta;
            Response:
                pro (?)
/war/prep   => Prepare an attack -- not required, but mimics the validation step in the UI
            Fields:
                U/A/S/C,
                type: string,
                target: integer,
                send => // units to send
                    m_tr,
                    m_j,
                    m_ta
            Response:
                completed: boolean;
                military =>
                    m_tr: number;
                    m_j: number;
                    m_ta: number;
                country_name: string;
                country_tag?: string;
                attacktype: string;
                target: number;
/war/attack   => Send an attack --  will actually attack the target if able to
            Fields:
                U/A/S/C,
                type: string,
                target: integer,
                send => // units to send
                    m_tr,
                    m_j,
                    m_ta
            Response:
                turns,
                attacktype,
                completed,
                success,
                attack_status => 
                    combined_mil_losses (big object!)
                    news =>
                        a_cname
                        a_cnum
                        a_tag
                        d_cname
                        d_cnum
                        d_tag
                        buildinggain
                        buildings
                        food
                        killed
                        land
                        landgain
                        military
                        money
                        oil
                        pop
                        success
                        tech
                        type
/spy   => Send a spy operation on a country
                Fields:
                    U/A/S/C,
                    op: integer,
                    target: integer,
                Response:
                    turns,
                    dead_spies,
                    success,
                    spyinfo =>
                        result1
                        result2

/clan/create   => Create a new clan
                Fields:
                    U/A/S/C,
                    CLANNAME: string,
                    CLANID: string, # tag
                    CLANWEB: string, # website, optional
                    CLANPW: string, # public pw
                    CLANADMINPW: string, # admin pw
                Response:
                    tag

/clan/join   => Join an existing clan
                Fields:
                    U/A/S/C,
                    CLANID: string, # tag
                    CLANPW: string, # public pw
                Response:
                    tag

                    explore  => explore turns!
                    Fields:
                        U/A/S/C,
                        turns;
                    Response:
                        new_land,
                        build_cost,
                        explore_rate,
                        turns,
                        tpt

get_optimal_tech_buying_info  => returns an array of optimal tech buying info
Fields:
    U/A/S/C,
    tech: the tech type ("t_agri" for example) - only t_agri, t_bus, t_res, t_mil, t_weap, and t_indy are supported currently
    min_cs: expected number of cs the country will maintain
    min_price: the lowest price to buy tech at
    max_price: the largest price to buy tech at
    ipa: base income per acre for production (5.3 * bushel_price for farmers, for example)
    tech_value: the perceived dollar value of 2 NW points
    extra_money_for_tech_impact: extra money to use for tech income calculations (for example, PM purchases in dollars for mil tech). mil tech only includes this when turn bucket >= 95
    turn_buckets: array with values that are the turn buckets to check: 10 is 10% of turns remaining in the set for example
Response:
    'optimal_tech' =  [
        10 => [1=> ['t'=>'t_agri', 'p' => $p1, 'q' => $q1], 2=> ['t'=>'t_agri', 'p' => $p2, 'q' => $q2], ... 10=> ['t'=>'t_agri', 'p' => $p10, 'q' => $q10]],
        20 => [1=> ['t'=>'t_agri', 'p' => $p1, 'q' => $q11], 2=> ['t'=>'t_agri', 'p' => $p2, 'q' => $q19], ... 10=> ['t'=>'t_agri', 'p' => $p10, 'q' => $q20]],
        ...
        100 => [1=> ['t'=>'t_agri', 'p' => $p1, 'q' => $q101]]
    ]



TURN RESPONSE ITEMS:
"event" => possibilities:
    'earthquake',
    'oilboom',
    'oilfire',
    'foodboom',
    'foodbad',
    'indyboom',
    'indybad',
    'pciboom',
    'pcibad'
"taxrevenue"
"foodproduced"
"earthquake"
"biocure"
"popgrowth"
"bioterror"
"foodconsumed"
"outoffood"
"expenses"
"outofmoney"
"oilproduced"
"troopsproduced"
"jetsproduced"
"turretsproduced"
"tanksproduced"
"spiesproduced"
"cmproduced"
"nmproduced"
"emproduced"