Darkcanuck/RRServer/Query

From Robowiki
Jump to navigation Jump to search

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.