Conquer Club API

[chipv]

Conquer club now has a vastly improved API (XML output) , thanks to lack for a lot of hard work:

http://www.conquerclub.com/api.php

This page lists all inputs and outputs but I'll go through a simple description here with an example.

There are four modes - map, maplist, player,and gamelist

mode=map

Gives XML with information about a specific map.

Input Parameters:

• map - map name
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=map&mp=Africa - gets the Africa map

Output:

Code: Select all

<api>
   <map>
      <title>Africa</title>
      <xml>Africa.xml</xml>
      <small>Africa.S.jpg</small>
      <large>Africa.L.jpg</large>
      <thumbnail>Africa.thumb.png</thumbnail>

      <topic>674</topic>
      <status>N</status>
      <small_width>575</small_width>
      <small_height>524</small_height>
      <large_width>768</large_width>
      <large_height>700</large_height>

      <territories>45</territories>
   </map>
</api>


• <title> - the map title
• <xml> - the xml filename
• <small> - the small graphic filename
• <large> - the large graphic filename
• <thumbnail> - the thumbnail graphic filename
• <topic> - the id of discussion topic url i.e. forum/viewtopic.php?t=#
• <status> - "N" = Normal, "B" = Beta, "C" = Closed, "R" = Random
• <small_width> - the small graphic width
• <small_height> - the small graphic height
• <large_width> - the large graphic width
• <large_height> - the large graphic height
• <territories> - the number of territories

mode=maplist

Gives an XML with information on all maps

Code: Select all

http://www.conquerclub.com/api.php?mode=maplist

The output is a subset of the tags for an individual map.

mode=player

Gives XML with information about a specific player.

Input Parameters:

• u- user id
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=player&u=103452 - gets the user with id 206478

• un- user name
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=player&un=chipv - gets the user chipv

Output:

Code: Select all

<api>
   <player>
      <userid>206478</userid>
      <username>chipv</username>
      <score>2531</score>
      <games_completed>549</games_completed>
      <games_won>251</games_won>

      <rank>Colonel</rank>
      <rating>4.9</rating>
      <country>United Kingdom</country>
      <attendance>100</attendance>
      <medals>12</medals>
   </player>

</api>


• <userid> - the user id #
• <username> - the username
• <score> - the score
• <games_completed> - the number of games completed
• <games_won> - the number of games won
• <rank> - the rank
• <rating> - the rating
• <country> - the country
• <attendance> - the % attendance
• <medals> - the number of medals

mode=gamelist

Returns a single game or a set of games.

Input Parameters (all are optional URL query parameters so you can use any combination of them):
The base URL is http://www.conquerclub.com/api.php?mode=gamelist
So add any number of parameters by adding &parameter=value

Code: Select all

e.g. http://www.conquerclub.com/api.php?mode=gamelist&it=E&po=S&gt=S&bc=2&ft=C gives all Automatic Sequential Standard Escalating Chained games

• gn - game #
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&gn=103452 - gets game # 103452

• p1 - player 1 user id #
• p2 - player 2 user id #
• p3 - player 3 user id #
• p4 - player 4 user id #
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&p1=103452 - gets all games for player 1 with user id 103452

• p1un - player 1 username
• p2un - player 2 username
• p3un - player 3 username
• p4un - player 4 username
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&p1un=chipv - gets all games for chipv

• np - # of players
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&np=6 - gets all 6 player games

• gt - game type (S)tandard, (C)Terminator, (A)ssassin, (D)oubles, (T)riples, (Q)uadruples or (P)olymorphic
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&gt=A - gets all Assassin games

• mp - map name
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&mp=Asia - gets all Asia games

• it - initial troops (E)Automatic or (M)anual
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&it=M - gets all Manual games

• po - player order (S)equential or (F)reestyle
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&po=S&gt=A - gets all Sequential Assassin games

• bc - spoils (1)No Spoils, (2)Escalating, (3)Flat Rate or (4)Nuclear
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&bc=4&mp=Feudal War - gets all Nuclear Feudal games

• ft - reinforcements (C)hained, (O)Adjacent , (M)Unlimited , (P)arachute or (N)one
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&ft=C&mp=England - gets all Chained England games

• wf - fog of war (Y)es or (N)o
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&wf=Y&mp=Montreal - gets all Fog Montreal games

• gs - game state (W)aiting, (A)ctive or (F)inished
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&un=chipv&gs=F - gets all Finished games for chipv


• to - tournament name
• lb - tournament label
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&to=1,000 miles - gets all games in the tournament "1,000 miles"


• sg - speed game (Y)es or (N)o
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&un=chipv&sg=N gets all non-speed games for chipv


• pt - joinability Private (Y)es, (N)o or T(ournament)
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&un=chipv&pt=Y gets all private games for chipv


• page - page # (output is split into pages so use this for chaining results from several pages)
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&un=chipv&page=2 gets page 2 for chipv

• names - Text (Y)es or User Id (N)o (default)
  

  Code: Select all

  e.g. http://www.conquerclub.com/api.php?mode=gamelist&un=chipv&names=Y gets all games for chipv, using text names for players


• events - Show Log events (Y)es or (N)o (default)
  

  Code: Select all

  http://www.conquerclub.com/api.php?mode=gamelist&un=chipv&gs=F&events=Y gets all finished games for chipv plus log events

So let's look at a typical output.

Using

Code: Select all

http://www.conquerclub.com/api.php?mode=gamelist&p1un=chipv

Root tag is <api>

Code: Select all

<api>
   <page>1 of 2</page>
   <games total="244">


Each page contains a maximum of 200 games.
So here since the total games is 244 we already know we need 2 pages.

Now we have a set of games each looking like this:

Code: Select all

      <game>
         <game_number>2326879</game_number>
         <tournament></tournament>
         <private>N</private>
         <speed_game>N</speed_game>

         <map>Classic Shapes</map>
         <game_type>S</game_type>
         <play_order>S</play_order>
         <bonus_cards>2</bonus_cards>
         <fortifications>C</fortifications>
         <war_fog>N</war_fog>
         <round>7</round>
         <time_remaining>0</time_remaining>

         <players>
                     <player state="Lost">88215</player>
                     <player state="Lost">152099</player>
                     <player state="Won">154809</player>
                     <player state="Lost">198136</player>
                     <player state="Lost">206478</player>

                     <player state="Lost">149268</player>
                  </players>
         <events>
                     <event timestamp="1210347992">3 eliminated 4 from the game</event>
                     <event timestamp="1210348135">3 eliminated 1 from the game</event>
                     <event timestamp="1210348299">3 eliminated 5 from the game</event>
                     <event timestamp="1210348405">3 eliminated 2 from the game</event>

                     <event timestamp="1210348451">3 eliminated 6 from the game</event>
                     <event timestamp="1210348451">3 won the game</event>
                     <event timestamp="1210348451">1 loses 33 points</event>
                     <event timestamp="1210348451">2 loses 26 points</event>
                     <event timestamp="1210348451">4 loses 15 points</event>
                     <event timestamp="1210348451">5 loses 15 points</event>

                     <event timestamp="1210348451">6 loses 13 points</event>
                     <event timestamp="1210348451">3 gains 102 points</event>
                  </events>
      </game>


We can split the info into 3 sections : General Info, Player Info, and Log (Event) Info.

General Info

Code: Select all

         <game_number>2658300</game_number>
         <tournament></tournament>
         <private>N</private>
         <speed_game>N</speed_game>
         <map>Classic Shapes</map>
         <game_type>A</game_type>
         <initial_troops>E</initial_troops>
         <play_order>S</play_order>
         <bonus_cards>3</bonus_cards>
         <fortifications>M</fortifications>
         <war_fog>N</war_fog>
         <round>5</round>
         <time_remaining>0</time_remaining>


General Info lists the properties of the game given by <game_number>.

• <game_number> Game Number
• <tournament> Tournament name
• <private> N (Public), Y (Private) , T (Tournament)
• <speed_game> N (Casual) , Y (Speed)
• <map> Map Name
• <game_type> S (Standard), C (Terminator), A (Assassin) , D (Doubles) , T (Triples) , Q (Quadruples) , P (Polymorphic)
• <initial_troops> E(Automatic), M(Manual)
• <play_order> S (Sequential) , F (Freestyle)
• <bonus_cards> 2 (Escalating) , 3 (Flat Rate) , 1 (No Spoils), 4(Nuclear)
• <fortifications> C (Chained) , O (Adjaecent) , M (Unlimited) , P (Parachute) , N (None)
• <war_fog> N (No Fog) or Y (Fog)
• <round> Round Number
• <time_remaining> hrs:min:sec until turn expires or 0 if game finished

Player Info

Code: Select all

         <players>
                     <player state="Lost">88215</player>
                     <player state="Lost">152099</player>
                     <player state="Won">154809</player>
                     <player state="Lost">198136</player>
                     <player state="Lost">206478</player>

                     <player state="Lost">149268</player>
                  </players>


Each player has a state indicating Ready, Waiting, Playing , Won or Lost (if eliminated state is "Lost").
The value of the tag depends on the player format so by default it is user id # but you can have text names using &names=Y

Log (Event) Info

Code: Select all

         <events>
                     <event timestamp="1210347992">3 eliminated 4 from the game</event>
                     <event timestamp="1210348135">3 eliminated 1 from the game</event>
                     <event timestamp="1210348299">3 eliminated 5 from the game</event>
                     <event timestamp="1210348405">3 eliminated 2 from the game</event>

                     <event timestamp="1210348451">3 eliminated 6 from the game</event>
                     <event timestamp="1210348451">3 won the game</event>
                     <event timestamp="1210348451">1 loses 33 points</event>
                     <event timestamp="1210348451">2 loses 26 points</event>
                     <event timestamp="1210348451">4 loses 15 points</event>
                     <event timestamp="1210348451">5 loses 15 points</event>

                     <event timestamp="1210348451">6 loses 13 points</event>
                     <event timestamp="1210348451">3 gains 102 points</event>
                  </events>


Events show eliminations and point gains/losses all with timestamps.
The numbers in these events correspond to the number of the player in the Players array in the <players> tag.
So for example 3 eliminated 2 corresponds to user 154809 eliminating user 152099
Timestamps are standard number of milliseconds since 1970.

Possible Events :

Code: Select all

<event timestamp="1210348451"># eliminated # from the game</event>
<event timestamp="1210348451"># was kicked out for missing too many turns</event>
<event timestamp="1210348451"># loses # points</event>
<event timestamp="1210348451"># gains # points</event>
<event timestamp="1210348451">#, #, #, # won the game</event>
<event timestamp="1210348451">#, #, # won the game</event>
<event timestamp="1210348451">#, # won the game</event>
<event timestamp="1210348451"># won the game</event>
<event timestamp="1210348451"># surrendered</event>
<event timestamp="1210348451"># was a deadbeat</event>
<event timestamp="1210348451"># held the objective</event>

[chipv]

Updated to add round #, time remaining and players states Ready, Waiting, and Playing.

[Foxglove]

Can we please have an addition to the API to take a single game number as input, and return the corresponding game object?

[Dako]

Yes, it is really a big need to be able to send game number and receive game object in return.

It limits many things and it is really easy to script - you already have all the functions and you just need to add 1 more parameter.

Please?

[sherkaner]

Yeah, I wouldn't mind that either actually.

[Foxglove]

I'd like to make another API request!

I'd like to be able to send an array of usernames and receive an array of user objects (containing rank, score, number of games completed and won, attendance, and rating).

I want to make a Conquer Club User Link script similar to my Game Link one - but right now it would be a crazy number of xmlhttprequest calls to constantly request the profile page for every user link in the forums.

[Travin]

Can someone explain to me why there was a massive modification to the XML feeds? The adjustment appears to be a stealth code adjustment with little or no community notification. Pretty much kills any automated scripts making use of the data and given the scope of the changes, will take a few days (at a minimum) to rework the support code.

[chipv]

The API has had a huge update, please see the head post for details, thanks very much to lackattack for responding to our requests!

New features include

• Maps - query API to get information on each map
• Maplist - gets information on all maps
• Player - gets profile information
• Single Game Queries
• Gamelist queries massively expanded to cover all game finder queries

[Foxglove]

The API has had a huge update, please see the head post for details, thanks very much to lackattack for responding to our requests!

New features include

• Maps - query API to get information on each map
• Maplist - gets information on all maps
• Player - gets profile information
• Single Game Queries
• Gamelist queries massively expanded to cover all game finder queries

Thanks, Lack! This is great.

...

...

...

Could we get one more tiny addition to the User query? It would also be fantastic to get a list of the user's groups!

[Dako]

I've found at least 3 bugs (or you can call them things that need to be updated improved) in the new API.

Still, it is better than nothing.

[chipv]

I've found at least 3 bugs (or you can call them things that need to be updated improved) in the new API.

Still, it is better than nothing.

It would be helpful if you can provide some detail please.

[Dako]

I've found at least 3 bugs (or you can call them things that need to be updated improved) in the new API.

Still, it is better than nothing.

It would be helpful if you can provide some detail please.

viewtopic.php?f=4&t=106398
viewtopic.php?f=4&t=106408
viewtopic.php?f=4&t=106397

Here you go.

[chipv]

I've found at least 3 bugs (or you can call them things that need to be updated improved) in the new API.

Still, it is better than nothing.

It would be helpful if you can provide some detail please.

viewtopic.php?f=4&t=106398
viewtopic.php?f=4&t=106408
viewtopic.php?f=4&t=106397

Here you go.

Acknowledged, thanks. Premium/Freemium would be just an addition.

Blocked one may be difficult to push through, but we'll see.

Clock problem will be investigated.

Thanks again for info, please put specifically API related posts in this thread (clock one probably did go in Suggs & Bugs).

[Dako]

Later, when I will use he API more (and right now I am listing players/games/maps) - I will post my experience. Right now the main problem is premium/freemiuim (really, right now I just display everyone as a premiuim...) and whether the game have finished or not (need to know it cause of different layout and different time_remaining [should be equal to zero]).

[mwhagedorn]

Did something change recently in the gamelist api? I am getting wierd values for the player ids

[chipv]

Did something change recently in the gamelist api? I am getting wierd values for the player ids

Depends on what you mean by recently, yes there was a big change recently.

Which page is showing up with weird values?

[mwhagedorn]

Great thanks for the rapid response.

The following query (now) produces garbage values for both usernames, and userids. Furthermore it doesnt seem to be returning the waiting games, rather it seems to be returning finished games.

http://www.conquerclub.com/api.php?mode=gamelist&un=<USERNAME>&gs=W

[mwhagedorn]

curl http://www.conquerclub.com/api.php?mode ... gn=6222685

also returns garbage, its not the details of that game

[chipv]

I can't see what is wrong with these, they appear to correspond with the game settings.

Which elements are garbage?

One change in the API is that you need &events=Y for events now.

[Dako]

Both requests work fine for me. Maybe check you raw response of the curl?

To check if they work - just type them into browser and see how the responding xml is formed.

[Foxglove]

I would like to make one more request (I know, I know..I'm never satisfied):

Can we get another addition to the game object to return either the length of the game chat or the number of lines it contains?

I wrote a new script to display a menu item containing a count of the number of games with new chat so that it's easy to identify when to go check out comments in games, but of course, this requires constant ajax calls to all of a user's active games.

Also - can we please get some kind of indication as to whether or not our requests are being considered? A yes, no, maybe, and perhaps even a time line would be super useful. I requested API extensions to include the user data back at the beginning of October, and no one posted in this thread until the end of December announcing the new API updates. It would have been nice to know whether or not my idea was being considered, whether it was already on the table for development, or what.

[chipv]

I would like to make one more request (I know, I know..I'm never satisfied):

Can we get another addition to the game object to return either the length of the game chat or the number of lines it contains?

I wrote a new script to display a menu item containing a count of the number of games with new chat so that it's easy to identify when to go check out comments in games, but of course, this requires constant ajax calls to all of a user's active games.

Also - can we please get some kind of indication as to whether or not our requests are being considered? A yes, no, maybe, and perhaps even a time line would be super useful. I requested API extensions to include the user data back at the beginning of October, and no one posted in this thread until the end of December announcing the new API updates. It would have been nice to know whether or not my idea was being considered, whether it was already on the table for development, or what.

Your request for single games was pushed forward and made it into the very next API release.
The user data suggestion is unlikely - how long do you think the URL is going to be if you request 50 user names. 100. 500. 1000?

An alternative might be to ask for blocks of users with a smaller parameter set. e.g. Users from A-C something like that anyway.

Length of game chat is possible, I will let you know.

If you are expecting everyone's requests to get a progress report in the forums,
then you may like to go to Suggs and Buggs to see how long some
people there have to wait. You are lucky to have got your first request met immediately
(if I hadn't pushed it through it wouldn't have happened, simple).
Considering you have me on MSN (the other script writers also) it may have been more gracious to have chatted about it.

Anyway I will endeavour to post updates on all of your individual requests if possible, but I also have a busy real life so perhaps exercise a modicum of patience in future like everyone else has done.

[Foxglove]

I would like to make one more request (I know, I know..I'm never satisfied):

Can we get another addition to the game object to return either the length of the game chat or the number of lines it contains?

I wrote a new script to display a menu item containing a count of the number of games with new chat so that it's easy to identify when to go check out comments in games, but of course, this requires constant ajax calls to all of a user's active games.

Also - can we please get some kind of indication as to whether or not our requests are being considered? A yes, no, maybe, and perhaps even a time line would be super useful. I requested API extensions to include the user data back at the beginning of October, and no one posted in this thread until the end of December announcing the new API updates. It would have been nice to know whether or not my idea was being considered, whether it was already on the table for development, or what.

Your request for single games was pushed forward and made it into the very next API release.

And I appreciated it - I posted right away and said so.

The user data suggestion is unlikely - how long do you think the URL is going to be if you request 50 user names. 100. 500. 1000?

An alternative might be to ask for blocks of users with a smaller parameter set. e.g. Users from A-C something like that anyway.

Yes, I suppose I didn't think that one through very carefully. I wanted it for my clan script, so I was anticipating using it for 20ish-50? users, but you're right, that would make a very long URL.

Length of game chat is possible, I will let you know.

Thank you.

If you are expecting everyone's requests to get a progress report in the forums, then you may like to go to Suggs and Buggs to see how long some people there have to wait.

I'm not "expecting" anything. I basically asked for an indication that ideas have been read - that's it. Maybe that is an excessively onerous request, maybe I didn't make my request in a friendly enough fashion, but it's something that I would find beneficial, so I asked.

You are lucky to have got your first request met immediately (if I hadn't pushed it through it wouldn't have happened, simple).

I did thank you at the time when we talked about it, and thank you again for making it happen. Maybe I didn't show enough gratitude, then or now? What else would you like from me?

Considering you have me on MSN (the other script writers also) it may have been more gracious to have chatted about it.

Aside from a few people, I don't even know how many script writers there are, and of those who do write scripts, I don't know what they are interested in or what their current projects might be. I thought maybe other people might be interested in the same features I'm asking for, and I thought that maybe other people might also like acknowledgment of their ideas/requests.

Anyway I will endeavour to post updates on all of your individual requests if possible, but I also have a busy real life so perhaps exercise a modicum of patience in future like everyone else has done.

I definitely understand that you have a busy life outside of CC. I don't quite understand at which point in this thread I displayed a complete dearth of patience (a modicum is such a small amount, and you say I had none at all?), but I will endeavor to exercise restraint, and cease my constant requests and ungrateful demands.

[ronsizzle]

i couldnt tell? was that a fitz post above this one?

[Dako]

Foxy and chip - please stay on topic. All your issues about honor and patience may be discussed in privacy over PM or MSN. We are not that interested in your "quarrel" as you might (or might not) think.

Thanks, Dako (just want this topic to be clear enough for others to read).