playerlist

URL: http://api.bf3stats.com/[Platform]/playerlist/
[Platform] can be pc, 360 or ps3

POST parameters:

• players * is a required list of player names.
  The list can be comma separated, or a JSON Array or a URI encoded array
• opt is a list of [playerOutputOptions]
  See below for a list of [playerOutputOptions].

Return parameters:

• status can contain ok or error
• error is only returned if status is error with one of following error codes:
  invalid_platform, no_players_given, no_valid_players, index_database_error, data_database_error, too_many_players, private
• list is the list of players data with index name equal your requested name. Every item has status with following codes:
  pifound only the index data of the player was found
  data complete data of the player was found
  
• failed is a list of failed players with index name equal your requested name. An item has at least error with one of the following codes: invalid_name, notfound

player

URL: http://api.bf3stats.com/[Platform]/player/
[Platform] can be pc, 360 or ps3

POST parameters:

• player name of a player
• opt is a list of [playerOutputOptions]
  See below for a list of [playerOutputOptions].

Return parameters:

• status can contain pifound, data, notfound or error
pifound only the index data of the player was found
  data complete data of the player was found
  
• error is only returned if status is error with one of following error codes:
  invalid_platform, invalid_name, private

dogtags

URL: http://api.bf3stats.com/[Platform]/dogtags/
[Platform] can be pc, 360 or ps3

POST parameters:

• player name of a player

Return parameters:

• status can contain dogtags, pifound, notfound or error
dogtags dogtags found successfully
  pifound only the index data of the player was found
  
• error is only returned if status is error with one of following error codes:
  invalid_platform, invalid_name, private

server

URL: http://api.bf3stats.com/[Platform]/server/
[Platform] can be pc, 360 or ps3

POST parameters:

• id 36 chars length id code of the server history set to 1 to receive history data

Return parameters:

• status can contain found, notfound or error
  
• error is only returned if status is error with one of following error codes:
  invalid_platform, invalid_id

onlinestats

URL: http://api.bf3stats.com/[Platform]/onlinestats/
[Platform] must be global

POST parameters:

none

Return parameters:

• status can contain ok, nodata or error
ok online data is available
  nodata data is not available
  
• error is only returned if status is error with one of following error codes:
  invalid_platform
• pc count of online players on PC
• 360 count of online players on 360
• ps3 count of online players on PS3

The data is refreshed every 10 seconds.

playerupdate *(for registered apps)

URL: http://api.bf3stats.com/[Platform]/playerupdate/
[Platform] can be pc, 360 or ps3

playerupdate is a signed request.
Use this request to update a player. This means we request the current data from EA for this player.
If the player was not in our database, we do automatically a lookup and add the player.

signed request parameters:

• time timestamp in seconds
• ident Unique ident of your app
• player name of a player

Return parameters:

• status can contain error, added, notfound, pifound, nobackend, timedout, noplatform, noname, nopid, noworker, exists, full, task, notask
  
• error is only returned if status is error and can contain invalid_platform, invalid_time, invalid_name, over_update_limit, no_update_right, noresponse, invalid_request, invalid_ident, ident_not_found, ident_locked, signature_wrong, invalid_json_data
  
• pos if the status is added or exists this is the queue position. If the update is in progress or finished, pos will be negative.
  
• task is only returned if status is added, task or exists
  
  • task.state can contain queued, started, finished
  • task.result can contain after task.state is finished: notfound, found

Limiting

This request is limited for your app key.
Only requests which result in status=added are counted towards your update limit.
The limit is counted per hour. The counter gets reseted 60 minutes after your first request.

How playerupdate can be used

If you requested a player from DataGroup player or playerlist and the stats are too old you can call playerupdate. If you get status=added you can call playerupdate every 10 seconds to get the current status of your update. You can stop if task.state is finished. Then check task.result. If found, the update was successful.

playerlookup *(for registered apps)

URL: http://api.bf3stats.com/[Platform]/playerlookup/
[Platform] can be pc, 360 or ps3

playerlookup is a signed request.
Use this request to lookup a player. This means we request the current index data(playerid, name, country) from EA for this player.
You can use this to search a player if the player is not in our database. So use player datagroup first to look if the player is in our database.
On a lookup always follows automatically an update of the player. This means you don't need to use playerupdate after playerlookup.

signed request parameters:

• time timestamp in seconds
• ident Unique ident of your app
• player name of a player

Return parameters:

• status can contain error, added, notfound, pifound, nobackend, timedout, noplatform, noname, noworker, exists, full, task, notask
  
• error is only returned if status is error and can contain invalid_platform, invalid_time, invalid_name, over_update_limit, no_update_right, noresponse, invalid_request, invalid_ident, ident_not_found, ident_locked, signature_wrong, invalid_json_data
  
• pos if the status is added or exists this is the queue position. If the lookup is in progress or finished, pos will be negative.
  
• task is only returned if status is added, task or exists
  
  • task.state can contain queued, started, finished
  • task.result can contain after task.state is finished: notfound, found

Limiting

This request is limited for your app key.
Only requests which result in status=added are counted towards your lookup limit.
The limit is counted per hour. The counter gets reseted 60 minutes after your first request.

How playerlookup can be used

If you requested a player from DataGroup player or playerlist and the stats are not found call playerlookup. If you get status=added you can call playerlookup every 10 seconds to get the current status of your lookup. You can stop if task.state is finished. Then check task.result. If found, the lookup was successful.

setupkey *(for registered apps)

URL: http://api.bf3stats.com/[Platform]/setupkey/
[Platform] must be global

setupkey is a signed request.
If your app has the right to generate keys, you can do it with this request.
You should use this if a software runs at the users device like mobile apps, or desktop applications. So you can generate an individual key for every installation. This is important, because you should never give your secret key out to another system.

signed request parameters:

• time timestamp in seconds
• ident Unique ident of your app
• clientident *(optional) New unique ident to create. If not given, we define a random string for this.
• name *(optional) name for the new key. Get's displayed in your key overview just for information.

Return parameters:

• status can contain error, ok
  
• error is only returned if status is error and can contain invalid_platform, invalid_time, no_genkey_right, invalid_clientident, invalid_name, clientident_in_use, db_save_error, invalid_request, invalid_ident, ident_not_found, ident_locked, signature_wrong, invalid_json_data
  
• ident Ident of your new key
• parent Parent ident(your app ident) of your new key
• key Your new key
• name Name of your new key
• locked Is the key locked, true or false. Will be always true for creation.
• canupdate Has right to update, true or false
• canlookup Has right to lookup, true or false
• update_limit count of allowed updates per hour
• lookup_limit count of allowed lookups per hour

getkey *(for registered apps)

URL: http://api.bf3stats.com/[Platform]/getkey/
[Platform] must be global

getkey is a signed request.
This request can be used to get information about a existing client key or your own key.

signed request parameters:

• time timestamp in seconds
• ident Unique ident of your app
• clientident Ident to lookup

Return parameters:

• status can contain error, ok
  
• error is only returned if status is error and can contain invalid_platform, invalid_time, invalid_clientident, clientident_notfound, clientident_notallowed, invalid_request, invalid_ident, ident_not_found, ident_locked, signature_wrong, invalid_json_data
  
• ident Ident of your key
• parent Parent ident(your app ident) of your key
• key Your key
• name Name of your key
• locked Is the key locked, true or false.
• canupdate Has right to update, true or false
• canlookup Has right to lookup, true or false
• update_limit count of allowed updates per hour
• lookup_limit count of allowed lookups per hour
• update_left count of allowed updates per hour left
• lookup_left count of allowed lookups per hour left

Presets

• clear sets all options to false
• index returns only index data, all other options are ignored
• all is the default option with nextranks:true and imgInfo:true
• noinfo sets all *Info options to false
• nounlocks sets all *Unlocks options to false

Options

• scores default: true
• global default: true
• nextranks default: false
• rank default: true
• imgInfo default: false
• lastseen default: false
• urls default: false
• keys default: false
• raw default: false
• nozero default: false
• coop default: true
• coopInfo default: true
• coopMissions default: true
• gamemodes default: true
• gamemodesInfo default: true
• weapons default: true
• weaponsName default: true
• weaponsInfo default: true
• weaponsOnlyUsed default: false
• weaponsUnlocks default: true
• weaponsRanking default: true (only works if ranking:true)
• weaponsStars default: true
• equipment default: true
• equipmentName default: true
• equipmentInfo default: true
• equipmentRanking default: true (only works if ranking:true)
• equipmentOnlyUsed default: false
• specializations default: true
• specializationsName default: true
• specializationsInfo default: true
• teams default: true
• kits default: true
• kitsName default: true
• kitsInfo default: true
• kitsStars default: true
• kitsUnlocks default: true
• vehicles default: true
• vehiclesName default: true
• vehiclesInfo default: true
• vehiclesRanking default: true (only works if ranking:true)
• vehiclesOnlyUsed default: false
• vehCats default: true
• vehCatsStars default: true
• vehCatsUnlocks default: true
• vehCatsGroup default: false (Groups both jet categories)
• vehCatsInfo default: true
• awards default: true
• awardsName default: true
• awardsInfo default: true
• awardsAwarded default: false
• ranking default: false
• rankingInfo default: true
• assignments default: false
• assignmentsInfo default: true
• assignmentsName default: true

Order how the options are executed

1. Options default values
2. presets
3. options

Value of opt POST parameter

The value of the opt POST parameter can be a comma separated list or a JSON object.
All options given in a comma separated list will be set to true.

Examples

• opt=clear,coop,imgInfo
• opt={"clear"%3Atrue%2C"coop"%3Atrue%2C"imgInfo"%3Atrue}

How to reduce traffic to a minimum

The options keys, raw, nozero help you to reduce the traffic per request to a minimum.
You only need one big request which contains the big data structure. You should do that with the player DataGroup.
Example: opt=all,keys

After that you can request one player or a playerlist with following opt:
Example: opt=clear,raw,nozero

Now you use the structure from the first request and replace all values which begin with stats. or coop. with the right values from the stats or coop object from the second request.
For stars and medals you also need to calc the needed value again with needed+count*needed

POST parameters

• data is a base64url encoded JSON object of signed request parameters
• sig is a base64url encoded SHA256 hmac signature of data and your secret key

Example

This PHP Example shows you all 4 types of signed requests you can do.
Note: The timestamp you give us with signed request parameters should not have more than 1 minute difference to current time. So the time on your server should be correct.