Difference between revisions of "Darkcanuck/RRServer/Query"

From Robowiki
Jump to navigation Jump to search
m (forgot "test" query)
m (add nav bar)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
{{Darkcanuck/RRServer/Navigation}}
 +
 
Ok, the API query interface is now in beta testing.  Here are the details.
 
Ok, the API query interface is now in beta testing.  Here are the details.
  
 
== Basic Access ==
 
== Basic Access ==
  
−
The basic URL to use is [http://darkcanuck.net/rumble/APIQuery].  You will need to pass it several parameters, either as a GET or a POST request.  All queries require the following parameters:
+
The basic URL to use is http://darkcanuck.net/rumble/APIQuery
 +
 
 +
You will need to pass it several parameters, either as a GET or a POST request.  All queries require the following parameters:
  
 
* <code>user</code> - API user name
 
* <code>user</code> - API user name
Line 32: Line 36:
  
 
Sample output:
 
Sample output:
−
   {"1":{"bot_id":"1249","battles":"223","score_pct":84.62,"score_dmg":57.072,"score_survival":64.98,
+
<pre>
−
  "rating_classic":2087.518,"rating_glicko":1779.861,"rd_glicko":8.575,"rating_glicko2":1787.828,
+
data: [
−
  "rd_glicko2":21.07,"vol_glicko2":21.068,"pairings":"17","count_wins":"16","timestamp":"2009-08-15 05:07:55",
+
   { bot_id: "1249",
−
  "state":"1","name":"ags.lunartwins.LunarTwins 1.2","created":"2009-08-13 12:45:33"},
+
    battles: "223",
−
   "2":{"bot_id":"1239","battles":"242","score_pct":74.88,"score_dmg":60.257,"score_survival":64.899,
+
    score_pct: 84.62,
−
   "rating_classic":1921.199,"rating_glicko":1674.245,"rd_glicko":7.242,"rating_glicko2":1677.517,
+
    score_dmg: 57.072,
−
  "rd_glicko2":18.413,"vol_glicko2":18.414,"pairings":"17","count_wins":"17","timestamp":"2009-08-15 05:07:46",
+
    score_survival: 64.98,
−
  "state":"1","name":"kc.twins.GeminiTeam 2.1","created":"2009-08-13 08:09:52"}}
+
    rating_classic: 2087.518,
 +
    rating_glicko: 1779.861,
 +
    rd_glicko: 8.575,
 +
    rating_glicko2: 2040.37684,
 +
    rd_glicko2: 21.07,
 +
    vol_glicko2: 21.068,
 +
    pairings: "17",
 +
    count_wins: "16",
 +
    timestamp: "2009-08-15 05:07:55",
 +
    state: "1",
 +
    name: "ags.lunartwins.LunarTwins 1.2",
 +
    created: "2009-08-13 12:45:33",
 +
    rank: 1
 +
   },
 +
   ...
 +
]
 +
</pre>
  
 
== <code>query=participant</code> ==
 
== <code>query=participant</code> ==
Line 50: Line 70:
  
 
Sample output:
 
Sample output:
−
   {"1":{"bot_id":"1149","battles":"2124","score_pct":77.197,"score_dmg":68.547,"score_survival":87.431,
+
<pre>
−
  "rating_classic":1713.775,"rating_glicko":1752.005,"rd_glicko":0.566,"rating_glicko2":1751.004,
+
data: [
−
  "rd_glicko2":2.797,"vol_glicko2":2.796,"pairings":"724","count_wins":"691","timestamp":"2009-06-25 19:49:35",
+
   { bot_id: "1149",
−
  "state":"R","name":"darkcanuck.Holden 1.02","created":"2009-06-23 07:05:22"}}
+
    battles: "2124",
 +
    score_pct: 77.197,
 +
    score_dmg: 68.547,
 +
    score_survival: 87.431,
 +
    rating_classic: 1713.775,
 +
    rating_glicko: 1752.005,
 +
    rd_glicko: 0.566,
 +
    rating_glicko2: 1751.004,
 +
    rd_glicko2: 2.797,
 +
    vol_glicko2: 2.796,
 +
    pairings: "724",
 +
    count_wins: "691",
 +
    timestamp: "2009-06-25 19:49:35",
 +
    state: "R",
 +
    name: "darkcanuck.Holden 1.02",
 +
    created: "2009-06-23 07:05:22"
 +
  }
 +
]
 +
</pre>
 +
 
 +
== <code>query=details</code> ==
 +
 
 +
Returns the pairings details for the specified game type and bot.
 +
 
 +
Requires:
 +
* <code>game</code> - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
 +
* <code>name</code> - name of bot to query (can be active or retired)
 +
 
 +
Sample output:
 +
<pre>
 +
data: [
 +
  { gametype: "X",
 +
    bot_id: "1265",
 +
    vs_id: "861",
 +
    vs_name: "ags.micro.Carpet 1.1",
 +
    battles: "1",
 +
    score_pct: 90.496,
 +
    score_dmg: 78.815,
 +
    score_survival: 100,
 +
    count_wins: "1",
 +
    timestamp: "2009-08-16 20:07:19",
 +
    state: "1"
 +
  },
 +
  ...
 +
]
 +
</pre>
  
 +
== <code>query=pairing</code> ==
 +
 
 +
Returns the pairing data for the specified game type and two bots.
 +
 +
Requires:
 +
* <code>game</code> - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
 +
* <code>name</code> - name of first bot to query (can be active or retired)
 +
* <code>vs</code> - name of second bot to query (can be active or retired)
 +
 +
Sample output:
 +
<pre>
 +
data: [
 +
  { gametype: "R",
 +
    bot_id: "861",
 +
    bot_name: "ags.micro.Carpet 1.1",
 +
    vs_id: "1265",
 +
    vs_name: "jk.mini.CunobelinDC 0.4",
 +
    battles: "1",
 +
    score_pct: 9.503,
 +
    score_dmg: 21.184,
 +
    score_survival: 0,
 +
    count_wins: "0",
 +
    timestamp: "2009-08-16 20:07:18",
 +
    state: "1"
 +
  }
 +
]
 +
</pre>
 +
 +
== <code>query=battles</code> ==
 +
 
 +
Returns the battle details for the specified game type and two bots.
 +
 +
Requires:
 +
* <code>game</code> - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
 +
* <code>name</code> - name of first bot to query (can be active or retired)
 +
* <code>vs</code> - name of second bot to query (can be active or retired)
 +
 +
Sample output:
 +
<pre>
 +
data: [
 +
  { user: "GrubbmGait_154",
 +
    ip_addr: "xxx.xxx.xxx.xxx",
 +
    version: "1",
 +
    timestamp: "2008-12-30 20:52:16",
 +
    millisecs: "642",
 +
    gametype: "Y",
 +
    state: "2",
 +
    created: "2008-12-30 20:53:52",
 +
    bot_id: "617",
 +
    bot_score: "1658",
 +
    bot_bulletdmg: "1225",
 +
    bot_survival: "6",
 +
    vs_id: "346",
 +
    vs_score: "4250",
 +
    vs_bulletdmg: "2137",
 +
    vs_survival: "29"
 +
  }
 +
]
 +
</pre>
  
 
== <code>query=test</code> ==
 
== <code>query=test</code> ==
 
    
 
    
 
Testing query that just returns some simple data.  Use for testing your client app before pulling real data.
 
Testing query that just returns some simple data.  Use for testing your client app before pulling real data.

Latest revision as of 05:59, 17 August 2009

Navigation: About | Updates | Ratings | Query API | Roadmap | Design | Develop | Known Issues

Ok, the API query interface is now in beta testing. Here are the details.

Basic Access

The basic URL to use is http://darkcanuck.net/rumble/APIQuery

You will need to pass it several parameters, either as a GET or a POST request. All queries require the following parameters:

  • user - API user name
  • apikey - unique API key assigned to user
  • query - query to execute

The first two are used to control access to the API so that the server doesn't get overloaded with unnecessary requests. Send me an email (darkcanuck81 at GMail) if you want access and I'll hook you up with a user name and API key. Note that this interface limits the number of requests per minute (currently 10) and per hour (currently 60). Please remember to play nice, as heavy usage of the API impacts rumble uploads and folks trying to view the rankings.

The third parameter controls the type of query, described in the following sections.

All output is sent in JSON format. Currently this takes the form of an associative array with the following keys:

  • params - associative array containing parameters key/value pairs received by the server
  • query - query type executed; does not exist on error
  • data - data set returned by the query (normally an associative array, possibly nested); set to null on error
  • error - set to 1 if an error occurred; does not exist if query was successful
  • message - message with details on the query results; most useful for errors

query=rankings

Returns the full rankings data for the specified game type (similar to rankings table view).

Requires:

  • game - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)

Optional:

  • order - ordering to use (eg. score_pct, score_survival, rating_glicko2, etc.); score_pct is the default

Sample output: 

data: [
  { bot_id: "1249",
    battles: "223",
    score_pct: 84.62,
    score_dmg: 57.072,
    score_survival: 64.98,
    rating_classic: 2087.518,
    rating_glicko: 1779.861,
    rd_glicko: 8.575,
    rating_glicko2: 2040.37684,
    rd_glicko2: 21.07,
    vol_glicko2: 21.068,
    pairings: "17",
    count_wins: "16",
    timestamp: "2009-08-15 05:07:55",
    state: "1",
    name: "ags.lunartwins.LunarTwins 1.2",
    created: "2009-08-13 12:45:33",
    rank: 1
  },
  ...
]

query=participant

Returns the rankings data for the specified game type and bot.

Requires:

  • game - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
  • name - name of bot to query (can be active or retired)

Sample output: 

data: [
  { bot_id: "1149",
    battles: "2124",
    score_pct: 77.197,
    score_dmg: 68.547,
    score_survival: 87.431,
    rating_classic: 1713.775,
    rating_glicko: 1752.005,
    rd_glicko: 0.566,
    rating_glicko2: 1751.004,
    rd_glicko2: 2.797,
    vol_glicko2: 2.796,
    pairings: "724",
    count_wins: "691",
    timestamp: "2009-06-25 19:49:35",
    state: "R",
    name: "darkcanuck.Holden 1.02",
    created: "2009-06-23 07:05:22"
  }
]

query=details

Returns the pairings details for the specified game type and bot.

Requires:

  • game - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
  • name - name of bot to query (can be active or retired)

Sample output: 

data: [
  { gametype: "X",
    bot_id: "1265",
    vs_id: "861",
    vs_name: "ags.micro.Carpet 1.1",
    battles: "1",
    score_pct: 90.496,
    score_dmg: 78.815,
    score_survival: 100,
    count_wins: "1",
    timestamp: "2009-08-16 20:07:19",
    state: "1"
  },
  ...
]

query=pairing

Returns the pairing data for the specified game type and two bots.

Requires:

  • game - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
  • name - name of first bot to query (can be active or retired)
  • vs - name of second bot to query (can be active or retired)

Sample output: 

data: [
  { gametype: "R",
    bot_id: "861",
    bot_name: "ags.micro.Carpet 1.1",
    vs_id: "1265",
    vs_name: "jk.mini.CunobelinDC 0.4",
    battles: "1",
    score_pct: 9.503,
    score_dmg: 21.184,
    score_survival: 0,
    count_wins: "0",
    timestamp: "2009-08-16 20:07:18",
    state: "1"
  }
]

query=battles

Returns the battle details for the specified game type and two bots.

Requires:

  • game - game type to query (eg. roborumble, meleerumble, teamrumble, twinduel, etc.)
  • name - name of first bot to query (can be active or retired)
  • vs - name of second bot to query (can be active or retired)

Sample output: 

data: [
  { user: "GrubbmGait_154",
    ip_addr: "xxx.xxx.xxx.xxx",
    version: "1",
    timestamp: "2008-12-30 20:52:16",
    millisecs: "642",
    gametype: "Y",
    state: "2",
    created: "2008-12-30 20:53:52",
    bot_id: "617",
    bot_score: "1658",
    bot_bulletdmg: "1225",
    bot_survival: "6",
    vs_id: "346",
    vs_score: "4250",
    vs_bulletdmg: "2137",
    vs_survival: "29"
  }
]

query=test

Testing query that just returns some simple data. Use for testing your client app before pulling real data.

Retrieved from "http://robowiki.net/w/index.php?title=Darkcanuck/RRServer/Query&oldid=10685"