SharkScope

REST Web Services

API Reference Manual

This documentation describes the REST based

application programming interface (API)
published by the SharkScope site. It is
recommended that the reader has a reasonable
level of knowledge of web services, REST and
XML.

Version 1.0.74
12 May 2020
 SHARKSCOPE REST WEB SERVICES

CONTENTS
Contents.................................................................................................................................................2
Revision History....................................................................................................................................6
1. Request Format..............................................................................................................................7
1.1. URL Format...........................................................................................................................7
1.2. Authentication Parameters.....................................................................................................7
1.3. Headers..................................................................................................................................7
1.4. Password Encoding................................................................................................................7
2. Response Format...........................................................................................................................8
2.1. Basic Response Objects.........................................................................................................9
2.1.1. Response........................................................................................................................9
2.1.2. UserInfo.........................................................................................................................9
2.1.3. ErrorResponse................................................................................................................9
3. Resources.......................................................................................................................................9
3.1. Generic Resources...............................................................................................................10
3.1.1. Metadata......................................................................................................................10
3.2. Sharkscope Client Resources...............................................................................................10
3.2.1. DownloadResource......................................................................................................10
3.2.2. Version Check..............................................................................................................10
3.3. Player Resources..................................................................................................................10
3.3.1. Summary......................................................................................................................11
3.3.2. Completed Tournaments..............................................................................................12
3.3.3. Active Tournaments.....................................................................................................12
3.3.4. Statistics.......................................................................................................................12
3.3.5. Suggestions..................................................................................................................13
3.3.6. User note......................................................................................................................13
3.3.7. OptOut.........................................................................................................................13
3.3.8. OptIn............................................................................................................................13
3.3.9. Confirm Opt Change....................................................................................................14
3.3.10. Reset............................................................................................................................14
3.3.11. Graph...........................................................................................................................14
3.3.12. Profile..........................................................................................................................15
3.3.13. Timeline.......................................................................................................................15
3.3.14. Timeline Event.............................................................................................................15
3.4. PlayerGroup Maintenance Resources..................................................................................16
3.4.1. List...............................................................................................................................16
3.4.2. Retrieval.......................................................................................................................16
3.4.3. Modification................................................................................................................16
3.4.4. Adding players.............................................................................................................17
3.4.5. Modifying Members....................................................................................................17
3.4.6. Deleting Members........................................................................................................17
3.4.7. Deleting the group........................................................................................................17
3.5. Tournament Resources.........................................................................................................18
3.5.1. Tournament ID.............................................................................................................18
3.5.2. Registering Tournaments..............................................................................................18
3.5.3. Completed Tournaments..............................................................................................18
3.5.4. Bare Tournaments........................................................................................................19
3.5.5. Running Chips Tournaments........................................................................................19
3.6. Active Tournaments.............................................................................................................20
3.6.1. Players’ Active Tournaments........................................................................................20
3.7. Leaderboard Resources........................................................................................................21
3.7.1. Year..............................................................................................................................21
3.7.2. Private..........................................................................................................................21

API REFERENCE MANUAL Page 2 of 54

 SHARKSCOPE REST WEB SERVICES

3.7.3. Category.......................................................................................................................21
3.7.4. Subcategory.................................................................................................................21
3.7.5. Value Type...................................................................................................................22
3.8. Network Resources..............................................................................................................22
3.8.1. Coverage......................................................................................................................22
3.9. User Resources....................................................................................................................22
3.9.1. Login............................................................................................................................22
3.9.2. Preferences...................................................................................................................23
3.9.3. Blog URL.....................................................................................................................23
3.9.4. User Metadata..............................................................................................................23
3.9.5. Preferences Update......................................................................................................23
3.9.6. Payments......................................................................................................................23
3.9.7. Creation/Registration...................................................................................................24
3.9.8. Saved filters list...........................................................................................................24
3.9.9. Saved filter definition by name....................................................................................24
3.9.10. Save the filter...............................................................................................................25
3.9.11. Delete the saved filter..................................................................................................25
3.9.12. Change email address...................................................................................................25
3.9.13. Change user password..................................................................................................25
3.9.14. User-specific player classes.........................................................................................25
3.9.15. User-defined player classes..........................................................................................26
3.9.16. Create/modify user-defined player class......................................................................26
3.9.17. Delete user-defined player class...................................................................................26
3.9.18. Reseller Information....................................................................................................26
3.9.19. Add Reseller Payment..................................................................................................27
3.9.20. Set Application Permission..........................................................................................27
3.9.21. Get Application Permission..........................................................................................27
3.9.22. Delete Application Permission.....................................................................................28
3.9.23. User notes for players (bulk)........................................................................................28
3.9.24. Set Manager.................................................................................................................28
3.9.25. Delete Manager............................................................................................................28
3.10. Report resources..............................................................................................................29
3.10.1. Report resource (by region).........................................................................................29
3.10.2. Report resources (by network).....................................................................................29
3.10.3. Hourly Market Shares Report(by Region)....................................................................29
3.10.4. Hourly Market Shares Report(by Network).................................................................30
3.10.5. Daily Scheduled Tournaments Report (by Region)......................................................30
3.10.6. Daily Scheduled Tournaments Report (by Network)....................................................30
3.11. Filter................................................................................................................................31
3.11.1. Date constraint.............................................................................................................31
3.11.2. DayOfWeek constraint.................................................................................................31
3.11.3. Duration constraint.......................................................................................................32
3.11.4. Entrants constraint.......................................................................................................32
3.11.5. Type constraint.............................................................................................................32
3.11.6. Stake constraint............................................................................................................34
3.11.7. Rake constraint............................................................................................................34
3.11.8. Stake Plus Rake constraint...........................................................................................34
3.11.9. Guarantee constraint....................................................................................................34
3.11.10. Overlay constraint....................................................................................................35
3.11.11. Prize constraint.........................................................................................................35
3.11.12. PrizePool constraint.................................................................................................35
3.11.13. Class constraint........................................................................................................35
3.11.14. Player Class constraint.............................................................................................35
3.11.15. Limit constraint........................................................................................................36
3.11.16. Saved filter constraint..............................................................................................36

API REFERENCE MANUAL Page 3 of 54

 SHARKSCOPE REST WEB SERVICES

3.11.17. Versus player............................................................................................................36

3.11.18. Rebuys constraint.....................................................................................................36
3.11.19. Rakeback constraint.................................................................................................36
3.11.20. Tournament Name constraint...................................................................................36
3.11.21. ReEntries constraint.................................................................................................37
3.12. Missing Games resources.................................................................................................37
3.12.1. Missing Games By Game IDs......................................................................................37
3.12.2. Missing Games By Tournament Summary...................................................................37
3.13. Deal Resources................................................................................................................38
3.13.1. Activation....................................................................................................................39
3.14. Private Leaderboard Resources........................................................................................39
3.14.1. List...............................................................................................................................40
3.14.2. Create...........................................................................................................................40
3.14.3. Edit..............................................................................................................................40
3.14.4. Delete...........................................................................................................................40
3.14.5. Enable..........................................................................................................................41
3.14.6. Disable.........................................................................................................................41
3.14.7. Add Entrant..................................................................................................................41
3.14.8. RemoveEntrant............................................................................................................41
3.15. Stable resources...............................................................................................................42
3.15.1. Get Stable.....................................................................................................................42
4. Response Objects.........................................................................................................................42
4.1. Metadata..............................................................................................................................42
4.1.1. FilterDefinition............................................................................................................42
4.1.2. ConstraintDefinition....................................................................................................42
4.1.3. Regions........................................................................................................................42
4.1.4. Region..........................................................................................................................42
4.1.5. Networks......................................................................................................................42
4.1.6. Network.......................................................................................................................42
4.1.7. Currencies....................................................................................................................43
4.1.8. Currency......................................................................................................................43
4.1.9. PlayerStatisticsDefinitions...........................................................................................43
4.1.10. PlayerStatisticDefinition..............................................................................................43
4.1.11. PlayerStatisticalDataSetDefinition...............................................................................43
4.1.12. TournamentStatisticsDefinitions..................................................................................44
4.1.13. TournamentStatisticDefinition.....................................................................................44
4.1.14. PlayerStatisticalDataSetDefinition...............................................................................44
4.1.15. DefaultPlayerClasses...................................................................................................44
4.1.16. PlayerClass..................................................................................................................44
4.1.17. Rule..............................................................................................................................44
4.2. UserMetadata.......................................................................................................................44
4.2.1. UserFilters....................................................................................................................44
4.2.2. SavedFilter...................................................................................................................44
4.2.3. UserDefinedPlayerClasses...........................................................................................44
4.2.4. PlayerClass..................................................................................................................45
4.2.5. Rule..............................................................................................................................45
4.3. Player...................................................................................................................................45
4.3.1. PlayerView...................................................................................................................45
4.3.2. Filter............................................................................................................................45
4.3.3. Constraint.....................................................................................................................45
4.3.4. Player...........................................................................................................................45
4.3.5. Statistics.......................................................................................................................46
4.3.6. Statistic........................................................................................................................47
4.3.7. StatisticalDataSet.........................................................................................................47
4.3.8. PlayerSuggestions........................................................................................................47

API REFERENCE MANUAL Page 4 of 54

 SHARKSCOPE REST WEB SERVICES

4.4. Tournament..........................................................................................................................48
4.4.1. Statistics.......................................................................................................................48
4.4.2. TournamentEntry.........................................................................................................48
4.5. Leaderboards.......................................................................................................................48
4.5.1. Hierarchy:....................................................................................................................48
4.5.2. Leaderboard.................................................................................................................48
5. SharkScope-as-a-service (Sharkscope-push)...............................................................................50
6. Errors...........................................................................................................................................51
6.1. Description...........................................................................................................................51
6.2. Error Codes..........................................................................................................................51

API REFERENCE MANUAL Page 5 of 54

 SHARKSCOPE REST WEB SERVICES

REVISION HISTORY

Version 1.0.74 (12 May 2020) Added noPlayers option to Tournament

resource..

Version 1.0.73 (22 Apr 2020) Removed Player Leaderboard Ranks resource
as it duplicates functionality in the Player Profile resource.

Version 1.0.72 (4 Mar 2020) Added expandMultiEntries option to Tournament

resource.

Version 1.0.71 (21 Feb 2020) Added Private Leaderboard Edit Functionality

API REFERENCE MANUAL Page 6 of 54

 SHARKSCOPE REST WEB SERVICES

1. REQUEST FORMAT
1.1. URL FORMAT
All REST based web service calls are https calls with the following format:
https://www.sharkscope.com/api/appname/resource path?parameters
appname: Your application name, allocated to you by SharkScope on request,
resource path: The path to a specific resource,
parameters: Request parameters, such as username/password and filter.
1.2. AUTHENTICATION PARAMETERS
The URL parameters may contain the authentication information if required. This includes the
Username as clear text and the Password as a hex string representation of the passwords MD5 hash.
Example:
?Username=someone@somewhere.com&Password=ea3df3c7fa3557d23d2cf889b1a4c90d

1.3. HEADERS
The Accept header is required and should contain the response format required. This can currently be
either XML or JSON.
All REST calls that require authentication may include a username and password pair as headers
instead of parameters.

Header Description Value/Example

Accept Defines the response format application/xml or application/json

Username The authentication username someone@somewhere.com
Password The encoded password ea3df3c7fa3557d23d2cf889b1a4c90d
User-Agent Should exist and be not empty Mozzila

1.4. PASSWORD ENCODING

Together with the application name, SharkScope will provide you with an application key. This is an
alphanumeric key in lowercase. All MD5 encoded passwords must be re-encoded using MD5
encoding the second time post-fixed with the application key. The following illustrates the scrambling
processing in Java:
String encodedPassword = “ea3df3c7fa3557d23d2cf889b1a4c90d”;
String applicationKey = “21f5e7aa7893caf0”;
String key = encodedPassword.toLowerCase() + applicationKey;
byte[] defaultBytes = key.getBytes();
try {
MessageDigest algorithm = MessageDigest.getInstance("MD5");
algorithm.reset();
algorithm.update(defaultBytes);
byte messageDigest[] = algorithm.digest();

StringBuffer hexString = new StringBuffer();

for (int co = 0; co < messageDigest.length; co++) {
int i = 0xFF & messageDigest[co];
if (i < 16) {
hexString.append('0');
}
hexString.append(Integer.toHexString(i));
}
return hexString.toString().toLowerCase();

API REFERENCE MANUAL Page 7 of 54

 SHARKSCOPE REST WEB SERVICES

} catch (NoSuchAlgorithmException nsae){

...
}

The following illustrates the scrambling processing in Ruby:

#!/usr/bin/env ruby

require 'digest/MD5'

def encode(encoded_password, application_key)

key = encoded_password.downcase + application_key
Digest::MD5.hexdigest(key)
end

encode('ea3df3c7fa3557d23d2cf889b1a4c90d', '21f5e7aa7893caf0')

The following illustrates the scrambling processing in C++:

#include <openssl/md5.h>
#include <string.h>
#include <stdio.h>
int main(int argc, char* argv[])
{
char encodedPassword[] = "ea3df3c7fa3557d23d2cf889b1a4c90d";
char applicationKey[] = "21f5e7aa7893caf0";
char encodedPasswordKey[49];

strcpy(encodedPasswordKey, encodedPassword);
strcat(encodedPasswordKey, applicationKey);

unsigned char messageDigest[MD5_DIGEST_LENGTH];

MD5((unsigned char *)encodedPasswordKey, strlen(encodedPasswordKey),

messageDigest);

char encodedMessageDigest[(MD5_DIGEST_LENGTH * 2) + 1];

for (int i = 0; i < MD5_DIGEST_LENGTH; i++) sprintf(encodedMessageDigest +

(i * 2), "%02x", messageDigest[i]);
}

2. RESPONSE FORMAT
Incorrect calls will get either of the following response codes:
404 Not Found
405 Method Not Allowed
Each correctly formatted REST call will get a response from the web service in the form of either an
XML or JSON string.
If the call was unsuccessful the response root will be ErrorResponse, otherwise it will be appropriate
to the request (e.g. all player info calls have a response root PlayerResponse).
Response roots always contain a “timestamp” attribute containing the server time as a long
representation of the number of seconds since UNIX epoch. In fact, all date/time information are
represented in this format (See https://en.wikipedia.org/wiki/Unix_time).
Furthermore, all responses contain a UserInfo element which represents the authenticated user
information. Resources that do not require authentication also contain a UserInfo element.

API REFERENCE MANUAL Page 8 of 54

 SHARKSCOPE REST WEB SERVICES

2.1. BASIC RESPONSE OBJECTS

All structural data including response from the API are represented as XML.
2.1.1. RESPONSE
The root element of all responses is the Response element. The element has a success and a server
timestamp attribute which is the server time of the response as UNIX time. It also has a metadataHash
attribute which is the latest metadata hash code (see the metadata section for more info). Finally, the
root element may contain an appVersion attribute containing the current version number of the
application specified in the request. Example:
<Response success="true" timestamp="1279612806"
metadataHash=" f23ffdbb97027412c39cdba36e28b363" appVersion="3">
The root element contains a UserInfo element and, if the call is successful, the appropriate container
element of the actual response data. If the call is unsuccessful the root element contains the
ErrorResponse container element .
2.1.2. USERINFO
The UserInfo element contains information of the authenticated user. Example:
<UserInfo loggedIn="true">
<Username>someone@somewhere.com</Username>
<Regions name="Non US" code="NonUS"/>
<Regions name="International" code="All"/>
<RemainingSearches>56</RemainingSearches>
<ExpirationDate>1523644928</ExpirationDate>
<RequestLanguages>en-gb,en;q=0.7,el;q=0.3</RequestLanguages>
<AuthorizedNetworks all="true"/>
</UserInfo>
If the resource doesn’t require authentication, or no authentication is provided the UserInfo element
only contains the free remaining searches (and an optional Error string if authentication was required):
<UserInfo loggedIn="false">
<Regions name="Non US" code="NonUS"/>
<Regions name="International" code="All"/>
<RemainingSearches>5</RemainingSearches>
<RequestLanguages>en-gb,en;q=0.7,el;q=0.3</RequestLanguages>
</UserInfo>
The UserInfo element should be checked to confirm that authentication was successful
(loggedIn="true") and to report the number of remaining searches.

2.1.3. ERRORRESPONSE
The ErrorResponse root element contains error information and is returned when the call is
unsuccessful. Example:
<Response success="false" timestamp="1279613507">
<ErrorResponse>
<Error id="101002">Invalid password.</Error>
</ErrorResponse>
</Response>
The ErrorResponse contains an Error element. The value is the description of the error in English and
the id attribute contains the error code. The error code can be used to localize the error string.

3. RESOURCES
The root URL of all REST resources in the section is:
https://www.sharkscope.com/api/appname/
For resources that require authentication or where authentication is optional, the username/password
pair can be either parameters or headers.

API REFERENCE MANUAL Page 9 of 54

 SHARKSCOPE REST WEB SERVICES

3.1. GENERIC RESOURCES

3.1.1. METADATA
Requests metadata information from the server. If the hash parameter is specified and the value
provided is the latest metadata hash, the response is set to cache on the client. The response header
will not contain an appVersion attribute even if there is a valid application version.
Type GET
Authentication No
Cost Free
Response A MetadataResponse object containing the metadata.
Path Metadata
Parameters hash
Example https://www.sharkscope.com/api/someapp/metadata?
hash=f23ffdbb97027412c39cdba36e28b363

3.2. SHARKSCOPE CLIENT RESOURCES

There are resources that are available to provide information about clients that are built on top of
Sharkscope, such as HUD and Tournament Opener.
3.2.1. DOWNLOADRESOURCE
Directs the user to a download link where he/she can download the latest version of the client
application. The resource specifies whether the download is for the installer or the updater.
Type GET
Authentication No
Cost Free
Response A redirect to a URL.
Path client/[updater | installer]
Parameters Hash
Example https://www.sharkscope.com/api/someapp/client/ installer

3.2.2. VERSION CHECK

Gets the latest version number of the client app.
Type GET
Authentication No
Cost Free
Response A GenericResponse object containing the version number.
Path client/[updater | installer]/version
Parameters Hash
Example https://www.sharkscope.com/api/someapp/client/versioncheck

3.3. PLAYER RESOURCES

Player resources have the following root URL:
https://www.sharkscope.com/api/appname/networks/{networkname}/players/{playername}/

The network name in some resources is “network specifier”. In other cases it is a network name or
“PlayerGroup” that is used when requesting player groups. When requesting player groups the player
name is the name of the player group.
Network specifiers are a way to request multiple networks. There are two ways to request multiple
networks, “all” or “any”. When requesting ‘all’ networks, all the networks provided will be used in
the request. In the case of ‘any’ the resource will search each provided network in order until it finds a
matching player.

API REFERENCE MANUAL Page 10 of 54

 SHARKSCOPE REST WEB SERVICES

To provide a network specifier, provide a list of comma-separated network preceded by the ‘all’ or
‘any’ keyword and a colon (‘:’). e.g.:
https://www.sharkscope.com/api/appname/networks/all:fulltilt,pokerstars/players/al
https://www.sharkscope.com/api/appname/networks/any:fulltilt,pokerstars/players/al

The ‘all’ keyword can also be replaced with a * character and the ‘any’ keyword with an ‘@’
character, so the above examples become:
https://www.sharkscope.com/api/appname/networks/*:fulltilt,pokerstars/players/al
https://www.sharkscope.com/api/appname/networks/@:fulltilt,pokerstars/players/al

The ‘any’ or ‘*’ keyword is implied so if you provide just a list of networks it is equivalent to having
an ‘any’ keyword before the list.
https://www.sharkscope.com/api/appname/networks/*:fulltilt,pokerstars/players/al

… is the same as:

https://www.sharkscope.com/api/appname/networks/fulltilt,pokerstars/players/al

If no network list is provided then a list of all active searchable networks is implied. However at least
one of the keywords (‘all’, ‘any’, ‘*’, ‘@’) must be provided. The order is also not predetermined so
the ‘any’ keyword is only useful if you are looking for a player for the first time, otherwise it is going
to be returning whichever player it finds first.
The resources that allow network specifiers have a «network specifier» flag next to the parth in the
definition tables in this chapter
Each network name can be URL encoded (UTF-8) if it contains spaces. Skins can also be provided as
network names. The “Player name” path parameter must always be URL encoded (UTF-8).
The resource “suggestions” doesn’t require a full player name and doesn’t return a PlayerResponse.
Most player resources return a PlayerResponse object sparsely populated according to the request.
All player resources may also be filtered by providing a filter parameter (see filter section).
Summary, statistic and completed tournament requests may provide an optional lastUpdateTime
parameter of type long representing a UNIX timestamp. If the last activity of the player or group
supplied is less than or equal to that timestamp (i.e. there was no activity after the timestamp) then a
Generic response is returned with the text “Unchanged”.
3.3.1. SUMMARY
Requests player summary information. The response contains basic information about the user as well
as all free statistical information and a small number of most recent tournament results.
The optional mode parameter introduces a flexible “versus User” functionality. There are three mode
options: “vsuseronblocked”, “normal”, and “vsuser”. If the user has set up a personal user group
containing their players in various networks and there is a player specified for the network of the
searched player, the default mode is “vsuseronblocked”, otherwise the mode is set to normal in all
cases.
If the user is blocked under the vsuseronblocked mode, only the tournaments where the player has
played against the user are included. In “vsuser” mode there are two player response elements, one for
the all tournaments (if the player is not blocked) and one for the tournaments against the user (if
possible).
If the player is a group then the group inherits the most restrictive opt out mode of its members. E.g. if
there is an opted out player in the group then the whole group is considered opted out and that player
must be removed from the group to be able to view that groups statistics. Likewise if a member of the
group is not opted in on PokerStars, then the financial statistics for that group will not be viewable
until that player is removed or opts in.
Type GET

API REFERENCE MANUAL Page 11 of 54

 SHARKSCOPE REST WEB SERVICES

Authentication Required.
Cost 1
Response A sparsely populated PlayerResponse object.
Path root «network specifier»
Parameters Authentication, filter [Optional], mode [Optional], lastUpdateTime [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom

3.3.2. COMPLETED TOURNAMENTS

Requests a specific number of recent tournaments. The response contains only up to the number of
tournaments requested. The number of tournaments requested and the ordering is defined in the
“order” parameter which is similar to the Limit constraint and takes the same arguments, with one
addition: “player” ordering. When requesting tournaments for a group you may use player ordering
(e.g. order=player,1~1000) to return the tournaments for each player in order. This is more efficient
when requesting a large number of tournaments for a large number of users and you want to perform
the request in chunks (i.e. order=player,1~1000 then order=player,1~2000, etc.).
Type GET
Authentication Required. Subscriber Only.
Cost 1 Search per 100 tournaments returned.
Response A sparsely populated PlayerResponse object.
Path completedTournaments «network specifier»
Parameters Authentication, order [Optional], Filter [Optional], lastUpdateTime [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/completedTou
rnaments?order=Best,1~50

3.3.3. ACTIVE TOURNAMENTS

Requests a specific number of current (registering and running) tournaments. The response contains
only up to the number of tournaments requested. The number of tournaments requested is defined in
the “limit” parameter which is optional. If no limit is provided, all current tournaments are returned.
NB: You can achieve relative date ranges with the use of both inverted and non-inverted Date
constrains can be used to. For example to retrieve all active tournaments that start in the next 10
minutes use the filter “Date:0S;Date!:-600S”. This filter picks the tournaments that haven’t started yet
(with the Date:0s) and will start up to 600 seconds from now).
Type GET
Authentication Required.
Cost 1
Response A sparsely populated PlayerResponse object.
Path activeTournaments «network specifier»
Parameters Authentication, order [Optional], Filter [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/activeTourna
ments

3.3.4. STATISTICS
Requests all or a selection of the statistics. The response contains only the statistics requested (could
be all) with no recent tournaments.
Type GET
Authentication Required. Subscriber Only.
Cost Depends on type of statistics requested/retrieved.
Response A sparsely populated PlayerResponse object.
Path statistics, statistics/[statistic name],... «network specifier»
Parameters Authentication, Filter [Optional], lastUpdateTime [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/statistics
https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/statistics/Total

API REFERENCE MANUAL Page 12 of 54

 SHARKSCOPE REST WEB SERVICES

Stake,TotalCashes,Streaks

3.3.5. SUGGESTIONS
Requests a list of players starting with the player name (prefix) provided. The response is a
SearchSuggestionsResponse.
Type GET
Authentication Required.
Cost Depends on type of statistics requested/retrieved.
Response A SearchSuggestionResponse object.
Path suggestions
Parameters Limit [Optional, default=25]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/suggestions

3.3.6. USER NOTE

Gets or sets the user note on the specified player(s). The response contains the new user note.
Type GET/POST/DELETE
Authentication Required. Subscriber Only.
Cost 0
Response A sparsely populated PlayerResponse object.
Path usernote
Parameters notes [FormParam for POST]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/usernote

3.3.7. OPTOUT
Request to opt out a player's statistics. The response contains the success or failure message. If the
user has the networkadmin privilege for that network the email parameter is not required and the
player is opted out immediately and any existing Optins or Resets are removed. Otherwise a
confirmation email is sent to the user and any existing resets must be removed before an opt out can
be processed. If no email parameter is supplied the username is used. Players who are on an active
leaderboard cannot be Opted Out without the networkadmin privilege – in which case they will be
automatically removed from any current leaderboards – but not from historic leaderboards.
Type GET
Authentication Optional
Cost 0
Response Success or failure message MessagesResponse object.
Path optout
Parameters Email [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/ optout

3.3.8. OPTIN
Request to opt in a player's statistics and removes any existing resets or opt outs. The response
contains the success or failure message. If the user has the networkadmin privilege for that network
the email parameter is not required and the player is opted in immediately and all opt outs and resets
are removed. Otherwise a confirmation email is sent to the user. The email address provided must be
the same as the one used to create any existing opt out or resets. If no email address is supplied the
username is used.
Type GET
Authentication Required
Cost 0
Response Success or failure message MessagesResponse object.
Path optin
Parameters Email [Optional]

API REFERENCE MANUAL Page 13 of 54

 SHARKSCOPE REST WEB SERVICES

Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/ optin

3.3.9. CONFIRM OPT CHANGE

Request to confirm any opt in / out change, based on the id sent to the user in the request email. The
response contains the success or failure message.
Type GET
Authentication Not Required
Cost 0
Response Success or failure message MessagesResponse object.
Path confirmoptchange
Parameters id
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/confirmopt
change

3.3.10. RESET
Request to reset a player statistics so that they start from a specific date and anything before that date
is hidden from all users. The response contains the success or failure message. Resets are restricted to
one per network unless the user has the networkadmin privilege for that network. Resets have no
effect on leaderboard entries. If a reset exists, a user can only update that reset if the request email
address matches the email address that was used to create the reset. Users with networkadmin
privilege can update all resets. If no StartDateTime is provided the current date time is used.
Type GET
Authentication Required. Subscriber Only.
Cost 0
Response Success or failure message MessagesResponse object.
Path reset
Parameters StartDateTime [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/reset

3.3.11. GRAPH
Retrieves an image representing a player's current SharkScope status sometimes referred to as an
Avatar. The image returned is in SVG format and therefore can be scaled to any size. The graphs can
be requested in a range of types from small text-only plaques, up to large graphs similar to the profit
graph on the SharkScope website. The following table describes the currently supported graph types:

Name Description Width Height

A plaque showing several player statistics including an
MiniSummary animated leaderboard icon (if present). Values are colored 130 65
according to profit/loss
A small graph showing the player's profit history. The graph
ProfitHistory 250 250
does not contain any player text.
A large graph showing the player's profit history. The graph
ProfitHistroyLarge also shows a few other player statiistics that put the chart in 600 250
context.
A small graph showing the player's ROI and number of games
ByStake 250 250
by most frequent stakes played.
A small graph showing the player's ROI and profit history by
ByEntrants 250 250
their most frequent game sizes (entrants).
AvatarText A plaque showing several player statistics including an 130 65
(Deprecated) animated leaderboard icon (if present). Values are colored

API REFERENCE MANUAL Page 14 of 54

 SHARKSCOPE REST WEB SERVICES

according to profit/loss
AvatarSmall A small graph showing the player's profit history. The graph
180 180
(Deprecated) does not contain any player text.
A large graph showing the player's profit history. The graph
AvatarLarge
also shows a few other player statiistics that put the chart in 600 250
(Deprecated)
context.

Graphs can be requested in a specific size although, as this is a vector format, this effect can be
reproduced from a single size using the Browser's zoom functionality. The Freshness parameter
specifies the interval in seconds after which the underlying data will be refreshed and thus another
cost incurred. The default value is 10800 (3 hours). The graphs are currently only displayed in USD
currency.
Type GET
Authentication Required.
Cost 1
Response An SVG document with mime-type of application/xhtml+xml
Path graph
Parameters Authentication
filter [Optional]
freshness [Optional]
type: “AvatarText”, “AvatarSmall”, “AvatarLarge”
width [Optional]
height [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/graph ?
type=AvatarLarge

3.3.12. PROFILE
The request retrieves the player object which includes last activity timestamp of the player or group.
Only valid for registered users with an active subscription.
Type GET
Authentication Required.
Cost 0
Response A GenericResponse containing the last activity timestamp.
Path lastActivity
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/profile

3.3.13. TIMELINE
The request retrieves the player’s timeline with all events.
Type GET
Authentication Required.
Cost 0
Response A PlayerResponse containing the player’s timeline.
Path timeline «network specifier»
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/tom/timeline

3.3.14. TIMELINE EVENT

The request retrieves a player’s timeline event by its ID.
Type GET
Authentication Required.

API REFERENCE MANUAL Page 15 of 54

 SHARKSCOPE REST WEB SERVICES

Cost 0
Response A PlayerResponse containing the player’s timeline.
Path timeline/{id} «network specifier»
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/players/timeline/ABC1

3.4. PLAYERGROUP MAINTENANCE RESOURCES

PlayerGroup maintenance resources have the following root URL:
https://www.sharkscope.com/api/appname/playergroups/{groupname}
Group names are unique across all users. However, if the group name is “personal” the API handles
the requests as referring the special “personal group”. The actual name of that group is “<Personal>”
followed by the user ID and hence it is unique. In responses the name of the group is always
“personal”.
All player group maintenance resources require authentication and the user must be subscribed.
3.4.1. LIST
Requests a list of the user’s player groups. The response contains only basic information about the
groups and its members to allow adding, deleting and modifying group aspects. The personal group is
not included in this list.
Type GET
Authentication Required. Subscriber Only.
Response A sparsely populated PlayerGroupResponse object.
Path
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/playergroups

3.4.2. RETRIEVAL
Requests the player group information. The response contains only basic information about the group
and its members to allow adding, deleting and modifying group aspects.
Type GET
Authentication Required. Subscriber Only.
Response A sparsely populated PlayerGroupResponse object.
Path
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/playergroups/MyGroup
https://www.sharkscope.com/api/someapp/playergroups/personal

3.4.3. MODIFICATION
Can be used to modify the flags or the name of the group. There are two group flags that can be
modified, namely if it is public or private and if it is consolidated or not. If the group is public it
appears when searching for groups. Consolidated groups behave as a single player, for example when
requesting the summary of a consolidated group you will get all stats of all players consolidated. The
values for the public and consolidated path parameters can be y/n or true/false. If any of the
parameters missing, invalid or empty it will be ignored.
Type GET
Authentication Required. Subscriber Only.
Response A sparsely populated PlayerGroupResponse object.
Path Modify
Parameters Authentication, public [Optional], consolidated [Optional], name [optional]
Example https://www.sharkscope.com/api/someapp/playergroups/MyGroup/modify?
public=y&consolidated=n

API REFERENCE MANUAL Page 16 of 54

 SHARKSCOPE REST WEB SERVICES

3.4.4. ADDING PLAYERS

This request may be used to add a member to a group. If you attempt to add a player that already
exists in the group with the same filter an error will be returned. You may add the same player
multiple times with different filters to the group.
The request also sets the blog icon flag for the player and the vs player flag. If no blog icon is
specified when adding a player to a personal group the initial value will be false. If no vs player flag is
specified when adding a player then the initial value will be true. Note that the blog icon and vs player
flags are set for all occurrences of the player in the group.
The vs player flag allows you to prevent Vs:Me searches from occurring when you search a blocked
player.
A personal group is created by adding the first member.
Type GET
Authentication Required.
Response A sparsely populated PlayerGroupResponse object.
Path members/<network>/<playerName>
Parameters Authentication, blogicon [Optional], filter [Optional]
Example https://www.sharkscope.com/api/someapp/playergroups/MyGroup/members/fulltilt/to
m
https://www.sharkscope.com/api/someapp/playergroups/personal/members/fulltilt/tom
?blogicon=true
https://www.sharkscope.com/api/someapp/playergroups/personal/members/fulltilt/tom
?filter=Date:1Y

3.4.5. MODIFYING MEMBERS

This request may be used to modify the blog icon flag on a player for personal groups only. Note that
the blog icon is set for all occurrences of the player in the group.
Type GET
Authentication Required.
Response A sparsely populated PlayerGroupResponse object.
Path members/<network>/<playerName>/modify
Parameters Authentication, blogicon
Example https://www.sharkscope.com/api/someapp/playergroups/personal/members/fulltilt/tom
/modify?blogicon=true

3.4.6. DELETING MEMBERS

Removes a player from the group. Players can be removed one at a time. When the last player is
removed the group is deleted.
Type DELETE
Authentication Required. Subscriber Only.
Response A sparsely populated PlayerResponse object.
Path members/<network>/<playerName>
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/playergroups/MyGroup/members/fulltilt/to
m

3.4.7. DELETING THE GROUP

Deletes the group.
Type DELETE
Authentication Required. Subscriber Only.
Response A GenericResponse object with a single message that the group was deleted.
Path

API REFERENCE MANUAL Page 17 of 54

 SHARKSCOPE REST WEB SERVICES

Parameters Authentication
Example https://www.sharkscope.com/api/someapp/playergroups/MyGroup

3.5. TOURNAMENT RESOURCES

Tournament resources have the following root URL:
https://www.sharkscope.com/api/appname/networks/{network name(s)}/tournaments

Network name cannot be “PlayerGroup”. For the resources that request a specific tournament by ID a
network specifier may be provided (see 3.3 for more information). The network name can be URL
encoded (UTF-8) if it contains spaces. Skins can also be provided as network names.
3.5.1. TOURNAMENT ID
Requests a specific tournament by ID. The response contains a single tournament with the requested
ID if it exists. If not found, an error response is returned.
If the tournament is a registering tournament and a last update from the previous retrieval is specified
the response is a simple generic response with the text “unchanged”. This can be used to avoid
transferring large amount of data.
By default for multi-entry tournaments each player’s results are combined into a single result row. To
return each entry as a separate row use expandMultiEntries=true.
Requesting a tournament with the parameter noPlayers=true it will return the tournament element
without the player elements.
Type GET
Authentication Required.
Cost 1 (subsequent requests free for 3 hours)
Response A TournamentResponse object.
Path {Specific Tournament ID} «network specifier»
Parameters Authentication, lastUpdateTime [Optional], expandMultiEntries [Optional], noPlayers
[Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/tournaments/123456789

3.5.2. REGISTERING TOURNAMENTS

Requests specific number of registering tournaments based on an optional filter. The response
contains only up to the number of registering tournaments requested. The number of tournaments
requested is defined in the “limit” parameter. If no limit is supplied, all appropriate registering
tournaments are returned. The resource accepts multiple networks.
Type GET
Authentication Required.
Cost 1 (subsequent requests free for a minute)
Response A RegisteringTournamentResponse object.
Path (root path)
Parameters Authentication, limit, Filter [Optional]
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/activeTournaments?limit=50

3.5.3. COMPLETED TOURNAMENTS

Requests completed tournaments on an optional filter. This resource requires special authorization and
can be provided only by prior agreement with SharkScope. The tournaments are pre-filtered with an
mutually agreed filter and will not include any tournaments older than two days.
Type GET
Authentication Required.
Cost 1
Response A CompletedTournamentResponse object.
Path completedTournaments

API REFERENCE MANUAL Page 18 of 54

 SHARKSCOPE REST WEB SERVICES

Parameters Authentication, Filter [Optional]

Example https://www.sharkscope.com/api/someapp/networks/fulltilt/completedTournaments?
filter=Date:1d

3.5.4. BARE TOURNAMENTS

Requests “bare” tournaments by their IDs. The response contains only the information about the
tournaments themselves without any of their tournament entries that contain participant player
information. The cost is 1 search for every 100 tournaments returned rounded up to the next hundred
(or less depending on the request). For example a request for 101 tournaments will cost 2 searches.
The tournaments IDs are provided either as a query parameter (for a GET request) or a form
parameter (for POST requests). The IDs can be separated by newlines, commas, semicolons or tabs.
If the network is “any” (*) the tournament IDs are expected to contain the network IDs. The network
applies to the IDs following the network ID (e.g. “pokerstars,1234,5678”). This means that the user
can provide network/tournamentID pairs:
pokerstars,1234
pokerstars.es,4567
fulltilt,5678
Alternatively, multiple tournament IDs may be provided for each network:
pokerstars
1234
4567
fulltilt
5678
… or as a continuous list:
pokerstars,1234,4567,fulltilt,5678
Specifically for PokerStars and its international networks you may use the “allpokerstars” specifier.
This translates internally as “all:pokerstars,pokerstarsit,pokerstarsfr,pokerstarses”. Note that using
network specifiers in any other way is not accepted.
allpokerstars,1234,4567,8901,5432
fulltilt,5678
For GET requests the last option is obviously easier.
The first item should be a network ID. Any tournament IDs that exist before the first network ID will
be ignored.
Type GET,POST
Authentication Required.
Cost 1 per 100 tournaments
Response A BareTournamentResponse object.
Path bareTournaments
Parameters Authentication, tournamentIDs
Example https://www.sharkscope.com/api/someapp/networks/fulltilt/bareTournaments?
tournamentIDs=376797050,375781297

3.5.5. RUNNING CHIPS TOURNAMENTS

Requests a single tournament by ID specifically to obtain the current chip counts of the tournament’s
players. When the initial REST request is made the tournament id is submitted to the system.
Subsequent polling (with the identical request) is then required to check on the status of the
submission. A response will contain a RunningChipsTournament with a state attribute of
SUBMITTED, ERROR or COMPLETED:

API REFERENCE MANUAL Page 19 of 54

 SHARKSCOPE REST WEB SERVICES

A state of SUBMITTED means that the tournament has been requested or was already requested.
A state of ERROR means that the tournament data was unable to be retrieved.
A state of COMPLETED means that the response is populated with the tournament data.
A completed response contains limited information about the tournament itself but contains the name
and chip count for each player in the tournament. The cost is 1 search.
Within the COMPLETED response the players are listed in order by highest to lowest chip counts
with knocked-out players appearing with zero chips and a finishing rank (in ascending rank order).
Not all networks are currently supported but support is on-going. If a request is made for an
unsupported network you will receive an immediate error response.
RunningChipsTournaments are cached for 5 minutes; therefore once you have received a response of
either COMPLETED or ERROR, a request for the same game, within this time, will return the same
data.
We recommend a polling interval of around 10 seconds. Polling should be abandoned if a COMPLETED or
ERROR state is not received within 2 minutes.

Type GET
Authentication Required.
Cost 1 (COMPLETED response)
Response A RunningChipsResponse object.
Path chips
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/networks/pokerstars/tournaments/123456789/chips

Example response:
<RunningChipsResponse>
<RunningChipsTournament network="pokerstars" tournamentId="1568330211"
state="COMPLETED" name="$7.00 NL Hold'em [Turbo]" stake="6.45" rake="0.55">
<players>
<player name="simal64" chips="5914"/>
<player name="Roll_Me_Now" chips="5671"/>
<player name="gaita763" chips="1915"/>
<player name="ImSingle6" chips="0" position="4"/>
<player name="fclmdon92" chips="0" position="5"/>
<player name="BronoCaetino" chips="0" position="6"/>
<player name="sanrah1" chips="0" position="7"/>
<player name="Y259066" chips="0" position="8"/>
<player name="sinsa72" chips="0" position="9"/>
</players>
</RunningChipsTournament>
</RunningChipsResponse>

3.6. ACTIVE TOURNAMENTS

Active Tournament resources have the following root URL:
https://www.sharkscope.com/api/appname/activeTournaments

3.6.1. PLAYERS’ ACTIVE TOURNAMENTS

Requests the active tournaments for multiple players. A number of players is provided and the active
tournaments are returned for those players that are currently playing and are not blocked. All other
players are omitted from the response. If the player is a group then only the players that are not
blocked are included.

API REFERENCE MANUAL Page 20 of 54

 SHARKSCOPE REST WEB SERVICES

Type GET/POST
Authentication Not Required.
Cost 1 per player (players inquired within the past 3 hours cost nothing)
Response A PlayerResponse object.
Path
Parameters networdX, playerX where X is the continuous index starting with one.
Example https://www.sharkscope.com/api/someapp/activeTournaments?
network1=pokerstars&player=someplayer&network2=cake&player=anotherplayer&...

3.7. LEADERBOARD RESOURCES

Leaderboard resources have the following root URL:
https://www.sharkscope.com/api/appname/poker-leaderboards

3.7.1. YEAR
Requests the leaderboards for a specific year. The response contains all the leaderboards for the year
as a hierarchy.
Type GET
Authentication Not Required.
Cost 0
Response A LeaderboardDisplayResponse object.
Path <year>
Parameters
Example https://www.sharkscope.com/api/someapp/poker-leaderboards/2010

3.7.2. PRIVATE
Requests the private leaderboards. The response contains all the private leaderboards as a hierarchy.
Type GET
Authentication Not Required.
Cost 0
Response A LeaderboardDisplayResponse object.
Path Private
Parameters
Example https://www.sharkscope.com/api/someapp/poker-leaderboards/private

3.7.3. CATEGORY
Requests the leaderboards for a specific category. The response contains all the leaderboards under
that category as a hierarchy.
Type GET
Authentication Not Required.
Cost 0
Response A LeaderboardDisplayResponse object.
Path <year>/<category>, private/<category>
Parameters
Example https://www.sharkscope.com/api/someapp/poker-leaderboards/2010/Scheduled
https://www.sharkscope.com/api/someapp/poker-leaderboards/private/Scheduled

3.7.4. SUBCATEGORY
Requests the leaderboards for a specific subcategory. The response contains all the leaderboards under
that subcategory as a hierarchy.
Type GET
Authentication Not Required.
Cost 0

API REFERENCE MANUAL Page 21 of 54

 SHARKSCOPE REST WEB SERVICES

Response A LeaderboardDisplayResponse object.

Path [category path]/<subcategory>
Parameters
Example https://www.sharkscope.com/api/someapp/poker-leaderboards/2010/Scheduled/$16-
$35

3.7.5. VALUE TYPE

Requests the leaderboard for a specific value type. The response contains the specific leaderboard
with player entries.
Type GET
Authentication Not Required.
Cost 0
Response A LeaderboardDisplayResponse object containing the leaderboard and players.
Path [subcategory path]/<value-type>
Parameters
Example https://www.sharkscope.com/api/someapp/poker-leaderboards/2010/Scheduled/$16-
$35/total

3.8. NETWORK RESOURCES

Network resources have the following root URL:
https://www.sharkscope.com/api/appname/networks/{network name(s)}

3.8.1. COVERAGE
Requests the network or networks coverage. The response contains all the coverage information for
the specified networks. Network can be “*” to denote all networks.
Type GET
Authentication Not Required.
Cost 0
Response A NetworkCoverageResponse object.
Path Coverage
Parameters
Example https://www.sharkscope.com/api/someapp/networks/pokerstars/coverage
https://www.sharkscope.com/api/someapp/networks/pokerstars,fulltilt/coverage
https://www.sharkscope.com/api/someapp/networks/*/coverage

3.9. USER RESOURCES

Network resources have the following root URL:
https://www.sharkscope.com/api/appname/user

3.9.1. LOGIN
Performs a login confirmation. The response only contains the UserInfo element if successful.
Type GET
Authentication Required.
Cost 0
Response A simple Response object.
Path (root)
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user

3.9.2. PREFERENCES
Requests the user’s preferences.
Type GET

API REFERENCE MANUAL Page 22 of 54

 SHARKSCOPE REST WEB SERVICES

Authentication Required.
Cost 0
Response A UserPreferencesResponse object.
Path Preferences
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/preferences

3.9.3. BLOG URL

Requests or modifies the user’s Blog URL. The blog URL is used only when the user sets up a
personal group. The blog URL is then added as a blog icon to selected members of that group. When
setting, the value must be URL encoded. To be able to set the blog URL the user must have the
appropriate authorization.
Type GET/DELETE
Authentication Required.
Response A BlogUrlResponse object.
Path blogurl
Parameters Authentication, value [when setting]
Example https://www.sharkscope.com/api/someapp/user/blogurl
https://www.sharkscope.com/api/someapp/user/blogurl?value=http%3a%2f
%2fblogs.sharkscopers.com%2fmyblog

3.9.4. USER METADATA

Requests user-specific metadata information from the server.
Type GET
Authentication Optional
Cost Free
Response A UserMetadataResponse object containing the metadata.
Path Metadata
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/metadata

3.9.5. PREFERENCES UPDATE

Updates the value of one or more user preferences. If the value is empty the preference is removed.
The following example sets the Currency preference to USD, Pref1 to “123.4” and deletes Pref2.
Type GET/POST
Authentication Required.
Cost 0
Response A UserPreferencesResponse object.
Path Preferences
Parameters Authentication, preference names and values (as form parameters for POST)
Example https://www.sharkscope.com/api/someapp/user/preferences/update?
Pref1=123.4&Pref2=&Currency=USD

3.9.6. PAYMENTS
Requests the user’s payments.
Type GET
Authentication Required.
Cost 0
Response A UserPaymentsResponse object.
Path Payments
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/payments

API REFERENCE MANUAL Page 23 of 54

 SHARKSCOPE REST WEB SERVICES

3.9.7. CREATION/REGISTRATION
Requests the creation/registration of a new user. If successful, the user is created and a login
confirmation is performed.
Type GET
Authentication Required.
Cost 0
Response A simple Response object.
Path Create
Parameters Authentication, affID [Optional], country [Optional], emailOption [Optional],
Example https://www.sharkscope.com/api/someapp/user/create
The optional affID parameter specifies the affiliation ID, the country specifies the user’s country (if
not specified it is determined by the IP address, and the emailOption parameter (Y/N) specifies if the
user should be added to the sharkscope mailing list.
The password passed as part of the authentication should be encoded only once using MD5 and not
encoded using the application key as described in section 1.4. Example:
String password = “ab1234”;
byte[] defaultBytes = password.getBytes();
try {
MessageDigest algorithm = MessageDigest.getInstance("MD5");
algorithm.reset();
algorithm.update(defaultBytes);
byte messageDigest[] = algorithm.digest();

StringBuffer hexString = new StringBuffer();

for (int co = 0; co < messageDigest.length; co++) {
hexString.append(Integer.toHexString(0xFF & messageDigest[co]));
}
return hexString.toString().toLowerCase();
} catch (NoSuchAlgorithmException nsae){
...
}

3.9.8. SAVED FILTERS LIST

Request to get the saved filter list. The response contains the UserFilters element if there are any
saved filters available for the logged in user.
Type GET
Authentication Required.
Cost 0
Response A UserFilters Response object.
Path filters
Parameters Authentication, type
Example https://www.sharkscope.com/api/someapp/user/filters

3.9.9. SAVED FILTER DEFINITION BY NAME

Request to get the saved filter definition by name. The response contains the UserFilters element if
there is any saved filters available by the given name.
Type GET
Authentication Required.
Cost 0
Response A UserFilters Response object.
Path filters/{filterName}
Parameters Authentication, type

API REFERENCE MANUAL Page 24 of 54

 SHARKSCOPE REST WEB SERVICES

Example https://www.sharkscope.com/api/someapp/user/filters/{filterName}

3.9.10. SAVE THE FILTER

Request to save the filter definition using a filter name. The response contains the UserFilters element.
Type GET
Authentication Required.
Cost 0
Response A UserFilters Response object.
Path filters/{filterName}/save
Parameters Authentication, type, text
Example https://www.sharkscope.com/api/someapp/user/filters/{filterName}/save

3.9.11. DELETE THE SAVED FILTER

Request to delete a saved filter definition. The response contains the UserFilters element.
Type GET
Authentication Required.
Cost 0
Response A UserFilters Response object.
Path filters/{filterName}/delete
Parameters Authentication, type
Example https://www.sharkscope.com/api/someapp/user/filters/{filterName}/delete

3.9.12. CHANGE EMAIL ADDRESS

Request to change the email of a registered user. The response only contains the UserInfo element if
successful.
Type GET
Authentication Required.
Cost 0
Response A simple Response object.
Path Change
Parameters Authentication, newemail
Example https://www.sharkscope.com/api/someapp/user/change

3.9.13. CHANGE USER PASSWORD

Request to change the password for registered user. The response only contains the UserInfo element
if successful.
Type GET
Authentication Required.
Cost 0
Response A simple Response object.
Path Change
Parameters Authentication, newpassword
Example https://www.sharkscope.com/api/someapp/user/change

3.9.14. USER-SPECIFIC PLAYER CLASSES

Requests the user-specific player classes a user. These are the combination of the non-overridden
default and user-defined player classes.
Type GET
Authentication Required.
Cost 0
Response A UserPlayerClassesResponse object.
Path PlayerClasses

API REFERENCE MANUAL Page 25 of 54

 SHARKSCOPE REST WEB SERVICES

Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/playerclasses

3.9.15. USER-DEFINED PLAYER CLASSES

Requests the user-defined player classes a user has previously saved.
Type GET
Authentication Required.
Cost 0
Response A UserPlayerClassesResponse object.
Path PlayerClasses
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/playerclasses/defined

3.9.16. CREATE/MODIFY USER-DEFINED PLAYER CLASS

Creates or modifies a user-defined player class. Also overrides a default player class. Returns the
created/modified/overridden player class. The rules parameter is a string of semicolon separated
entries of <statistic ID>:<minimum>~<maximum> values, one of which can be * for any (see
example). The categories parameter is a string of semicolon separated entries and is used for grouping
the classes into like groups for the Tournament player class summary field.
Type GET
Authentication Required.
Cost 0
Response A UserPlayerClassesResponse object.
Path PlayerClasses
Parameters Authentication, priority, rules, icon, categories, currency
Example https://www.sharkscope.com/api/someapp/user/playerclasses/defined/Fish?
priority=40&rules=Count:50~*;AvProfit:*~0;AvROI:*~-
20;Profit:*~0&icon=images/Fish.gif&currency=USD&categories=Fish

3.9.17. DELETE USER-DEFINED PLAYER CLASS

Deletes user-defined player class or default player class override and returns the remaining user-
defined classes.
Type DELETE
Authentication Required.
Cost 0
Response A UserPlayerClassesResponse object.
Path PlayerClasses
Parameters Authentication, priority, rules
Example https://www.sharkscope.com/api/someapp/user/playerclasses/defined/Fish

3.9.18. RESELLER INFORMATION

Returns, if present, all the reseller information, such as; Reseller packages bought, credit remaining,
the discount level, a list of packages that have been assigned to users and a list of subscriptions that
are available to purchase (with roleIDs).
Type GET
Authentication Required.
Cost 0
Response A ResellerInfoResponse object.
Path reseller
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/reseller

API REFERENCE MANUAL Page 26 of 54

 SHARKSCOPE REST WEB SERVICES

3.9.19. ADD RESELLER PAYMENT

Adds a subscription of a given role id to a given user's account, subtracting the cost from the resellers
account. If the userEmail address is not found in the system, then an account is automatically created
and the subscription assigned to that email.
Returns, if present, all the reseller information, such as; Reseller packages bought, credit remaining,
the discount level, a list of packages that have been assigned to users and a list of subscriptions that
are available to purchase (with roleIDs).
Type GET
Authentication Required.
Cost 0
Response A ResellerInfoResponse object.
Path reseller/payment
Parameters Authentication, userEmail, roleID
Example https://www.sharkscope.com/api/someapp/user/reseller/payment?userEmail=me%40
myemail.com&roleID=341

3.9.20. SET APPLICATION PERMISSION

Sets the permission for a user to use a specific application - with an expiry date. This is for
applications that don’t have a specific reseller payment system and just give users time-limited
permissions. This request can only be called by the designated application user administrator.
The expiry date must be in Unix format i.e. seconds since standard epoch of 1/1/1970. If it is null, the
permission doesn’t expire (i.e. it is perpetual).
You can set the expiry to any date in the future. The GenericReponse returned just contains the expiry
date. If the permission is perpetual the text “Perpetual” is returned in the GenericResponse.
Type PUT
Authentication Required.
Cost 0
Response A GenericResponse object.
Path api/{application}/users/{username}/permission
Parameters Authentication, expiry (optional)
Example https://www.sharkscope.com/api/someapp/users/someone@aol.com/permission ?
expiry= 1407542400

3.9.21. GET APPLICATION PERMISSION

Gets the expiry for a user’s permission to use a specific application. This is for applications that don’t
have a specific reseller payment system and just give users time-limited permissions. This request can
only be called by the designated application user administrator.
The expiry date will be returned in Unix time format i.e. seconds since standard epoch of 1/1/1970. If
the permission is perpetual the text “Perpetual” will be returned in the response. If the user doesn’t
have permission to use the application the text “No Permission” will be returned.
Type GET
Authentication Required.
Cost 0
Response A GenericResponse object.
Path api/{application}/users/{username}/permission
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/users/some@aol.com /permission

API REFERENCE MANUAL Page 27 of 54

 SHARKSCOPE REST WEB SERVICES

3.9.22. DELETE APPLICATION PERMISSION

Deletes the permission for a user’s permission to use a specific application. This is for applications
that don’t have a specific reseller payment system and just give users time-limited permissions. This
request can only be called by the designated application user administrator.
The request returns “No Permission” in a GenericResponse i.e. the same response a GET would return
for a user with no permission. If the deletion failed the text is “Unknown”.
Type DELETE
Authentication Required.
Cost 0
Response A GenericResponse object.
Path api/{application}/users/{username}/permission
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/users/some@aol.com /permission

3.9.23. USER NOTES FOR PLAYERS (BULK)

The request allows the user to retrieve all user notes they have attached to players. It also allows
setting, updating or deleting notes for players.
In the case of updating the notes post parameter should contain lines of text. The first line should be
the network name, the second line should be the player name and the following lines should contain
the notes. A line containing only a dot (‘.’) character denotes the end of the notes. If the notes are
empty – i.e. the dot line is the only line any notes already assigned to the player will be deleted.
Otherwise the notes will replace the notes already assigned to players.
Type GET/POST
Authentication Required.
Cost 0
Response A UserNotesResponse object.
Path api/{application}/user/notes
Parameters Authentication, notes [POST only]
Example https://www.sharkscope.com/api/someapp/user/notes

3.9.24. SET MANAGER

Sets the manager account for the user. Managers are able to see the user’s email address, subscription
status and view and reset their personal player names.
Type GET
Authentication Required.
Cost 0
Response A ManagerResponse object.
Path api/{application}/users/manager
Parameters Authentication, value
Example https://www.sharkscope.com/api/someapp/users/manager?value=manager@gmail.com

3.9.25. DELETE MANAGER

Removes any existing manager the user has assign on their account
Type DELETE
Authentication Required.
Cost 0
Response A ManagerResponse object.
Path api/{application}/users/manager
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/users/manager

API REFERENCE MANUAL Page 28 of 54

 SHARKSCOPE REST WEB SERVICES

3.10. REPORT RESOURCES

3.10.1. REPORT RESOURCE (BY REGION)
Produces a report for market share.
Type can be SNGEntrants or MTTEntrants. The year and month parameters specify the date for the
market share report. If no year or month is specified the current year and month are used. If only year
is specified, all the year is included in the report. If only month is specified, that month from all
available years will be included.
Type GET
Authentication Required.
Cost 0
Response A MarketShareResponse object.
Path api/{application}/reports/marketshare/regions/{region}
Parameters Authentication, year [Optional], month [Optional], type [Optional]
Example https://www.sharkscope.com/api/someapp/reports/marketshare/regions/FR?
type=MTTEntrants&year=12&month=12

3.10.2. REPORT RESOURCES (BY NETWORK)

Similar to Report resource (by region) but the report is produced for the provided network.
See Report resource (by region) for information on parameters.
Type GET
Authentication Required.
Cost 0
Response A MarketShareResponse object.
Path api/{application}/reports/marketshare/networks/{network}
Parameters Authentication, year [Optional], month [Optional], type [Optional]
Example https://www.sharkscope.com/api/admin/reports/marketshare/networks/pokerstars?
type=MTTEntrants&year=12&month=12

3.10.3. HOURLY MARKET SHARES REPORT(BY REGION)

Produces a report for hourly scheduled tournaments for a specific region.
Type GET
Authentication Required.
Cost 0
Response A HourlyMarketShareResponse object.
Path api/{application}/reports/hourlymarketshare/regions/{region}
Parameters Authentication, date [Optional]
Example https://www.sharkscope.com/api/someapp/reports/hourlymarketshare/regions/FR?
date=2014-11-31

The request returns a number of HourlyMarketShare elements with the following attributes: structure,
stake, region, rake, network, hour, game, flags, entrants, date, currency, avduration. The value of the
element itself is the hourly market share.

Example:
<HourlyMarketShareResponse>
<HourlyMarketShare structure="NL" stake="0.4" region="IT" rake="0.1" network="MicroGame"
hour="0" game="H" flags="T" entrants="6.0" date="2015-02-10" currency="EUR"
avduration="1376">3</HourlyMarketShare>
<HourlyMarketShare structure="NL" stake="0.4" region="IT" rake="0.1" network="MicroGame"
hour="0" game="H" entrants="9.0" date="2015-02-10" currency="EUR"
avduration="3141">1</HourlyMarketShare>

API REFERENCE MANUAL Page 29 of 54

 SHARKSCOPE REST WEB SERVICES

<HourlyMarketShare structure="NL" stake="0.4" region="IT" rake="0.1" network="MicroGame"

hour="0" game="H" flags="ST" entrants="12.0" date="2015-02-10" currency="EUR"
avduration="1775">3</HourlyMarketShare>
</HourlyMarketShareResponse>

3.10.4. HOURLY MARKET SHARES REPORT(BY NETWORK)

Produces a report for hourly scheduled tournaments for a specific network.
This is similar to the same report by region.
Type GET
Authentication Required.
Cost 0
Response A HourlyMarketShareResponse object.
Path api/{application}/reports/hourlymarketshare/networks/{network}
Parameters Authentication, date [Optional]
Example https://www.sharkscope.com/api/someapp/reports/hourlymarketshare/networks/pokers
tars?date=2014-11-31

3.10.5. DAILY SCHEDULED TOURNAMENTS REPORT (BY REGION)

Produces a report listing the daily scheduled tournaments for a specific date and region.
Type GET
Authentication Required.
Cost 0
Response A DailyScheduledTournamentsResponse object.
Path api/{application}/reports/dailyscheduledtournaments/regions/{region}
Parameters Authentication, date [Optional]
Example https://www.sharkscope.com/api/someapp/reports/dailyscheduledtournaments/regions/
FR?date=2014-11-31

The request returns a number of ScheduledTournament elements with the following attributes:
structure, stake, region, rake, prizePool, numRebuys, network, name, id, guarantee, game, flags,
entrants, date, and currency.

Example:
<DailyScheduledTournamentResponse>
<ScheduledTournament structure="NL" stake="225.00" region="IT" rake="25.00"
prizePool="14850.0" network="iPoker.it" name="Explosive Sunday HighR 15.000€"
id="624315649" guarantee="15000.0" game="H" flags="D" entrants="66"
date="1391998616" currency="EUR"/>
<ScheduledTournament structure="NL" stake="63.00" region="IT" rake="7.00"
prizePool="2520.0" network="iPoker.it" name="SNAI PSP 3.500€ Gtd" id="624395120"
guarantee="3500.0" game="H" flags="D" entrants="40" date="1391989802"
currency="EUR"/>
<ScheduledTournament structure="NL" stake="4.20" region="IT" rake="0.80"
prizePool="247.75" numRebuys="59" network="iPoker.it"
name="Sat Snai PSP 4.000€ Gtd. R/A" id="624415123" guarantee="200.0"
game="H" flags="T,SAT,R" entrants="25" date="1392058336" currency="EUR"/>
</DailyScheduledTournamentResponse>

3.10.6. DAILY SCHEDULED TOURNAMENTS REPORT (BY NETWORK)

Produces a report listing the daily scheduled tournaments for a specific date and network.
This is similar to the same report by region.
Type GET
Authentication Required.
Cost 0

API REFERENCE MANUAL Page 30 of 54

 SHARKSCOPE REST WEB SERVICES

Response A DailyScheduledTournamentsResponse object.

Path api/{application}/reports/dailyscheduledtournaments/networks/{network}
Parameters Authentication, date [Optional]
Example https://www.sharkscope.com/api/someapp/reports/dailyscheduledtournaments
/networks/pokerstars?date=2014-11-31

3.11. FILTER
Most player resources (except suggestions and usernote) may utilize a filter to restrict the tournaments
included in the statistics and recent tournaments. The filter is a collection of constraints on various
aspects of online poker games such as type, format, speed, etc.
The constraint types and their possible values are contained in the MetadataResponse. Some of them
are ranges or single numerical value constraints and there is a date-type constraint that requires special
handling. All of the constraint types are explained later in this section.
The filter parameter value is a string representation of the various constraints separated by semicolon.
The constraint type and values are separated by colon characters. Finally, the constraint may be
inverted (NOT operation) by adding an exclamation mark (“!”) after the constraint name. For
example:
?filter=Type:O,OHL,T;Type!:SAT;Stake:USD2~*
The above filter selects only tournaments where the Game was Omaha (“Omaha Hi” and “Omaha
H/L”), the Speed was Turbo, the Format was Heads-up or Satellite, the Stake was more than or equal
to $2, the Structure was “Pot Limit” or “Limit”.
3.11.1. DATE CONSTRAINT
Defines the date/time range of the tournaments to include.
Name Date
Type Date
Examples Date:1Y
Date:2007
Date:1274109174~1274130000
Date!:1Y [i.e. NOT the past year]
The value can be one of the following:
 A natural number n (integer greater than 0) followed by a character ('Y', 'M', 'W', 'D', 'H', or 'S'). It
denotes a time period of the last n years, months, weeks, days, hours or seconds respectively. E.g.
“1Y” means “in the past year”.
 A negative integer followed by one of the previously mentioned characters. It denotes a time
offset in the future e.g. “up to the next 1 hour”. This is only relevant for active tournaments in
order to find tournaments that start in the near future. See “Active Tournaments” for further
information.
 A year after 2006. It denotes that specific year as the time period.
 A range of Unix timestamps. It denotes the specified range of date/times as the time period.

3.11.2. DAYOFWEEK CONSTRAINT

Defines the date/time range of the tournaments to include.
Name DayOfWeek
Type DayOfWeek multiselect – one or more of (Su,Mo,Tu,We,Th,Fr,Sa)
Examples DayOfWeek:Su
DayOfWeek:Mo,Tu,Fr
DayOfWeek:Sa,Su
DayOfWeek:Mo,Tu,We,Th,Fr

API REFERENCE MANUAL Page 31 of 54

 SHARKSCOPE REST WEB SERVICES

The value can be one or more days of week represented by the first two letters of week days in
English. If multiple days are specified they must be separated by comma characters.
3.11.3. DURATION CONSTRAINT
Defines the date/time range of the tournaments to include.
Name Duration
Type Range
Examples Duration:1~10, Duration:30s~50m, Duration!:1h~*
The ranges can be post fixed with an “s”, “m” or “h” to denote seconds, minutes or hours. If there is
no postfix the number is assumed to denote minutes. For example “Duration: 30s-10” sets the
duration range to 30 seconds to 10 minutes inclusive.
3.11.4. ENTRANTS CONSTRAINT
Defines the number of entrants as a range.
Name Entrants
Type Range
Examples Entrants:2~5
Entrants:5~*
Entrants!:*~4 [same as “5~*”]
The value is a range. A star (“*”) character denotes “any”, e.g. “5~*” means “5 to any” or “more than
4”.
3.11.5. TYPE CONSTRAINT
Defines the tournament types to be included.
Name Type
Type Multiple selection
Examples Type:SO,FPP,O,OHL,HORSE,T
Type:FPP,HU,SAT
Type!:SAT
At the time of writing this document these are the available options:
Option Catego Name Description
ry
TR Format Tiered The prize is a ticket to the next tournament
tier. Also known as Step tournaments.
DM Flag Deal Made A deal was made in this tournament.
M Format Matrix 4 simultaneous Sit&Goes against the same
players, with additional prizes for overall
performances.
B Format Bounty Additional prizes are given for knocking
players out. Also known as Knockout, Hitman
and HeadHunter tournaments.
SO Format Shootout Only the winner of each table progresses.
HU Format Heads Up 2 players per table.
R Format Rebuy The tournament allows rebuys or add-ons.
DN Format Double or Half of the players double their buy in.
Nothing
FPP Format FPP The tournament buy in is with frequent
player points.
J Format Jackpot Additional rake goes towards a grand prize.
TN Format Triple or Nothing 1/3rd of the players triple their buy in.

API REFERENCE MANUAL Page 32 of 54

 SHARKSCOPE REST WEB SERVICES

W Format Winner Takes All 1st place wins the entire prize pool.
C Format Cashout Players can cash in their tournament chips at
any time.
RH Format Rush When players fold, they are transferred to a
new table and dealt a new hand.
SAT Format Satellite Prize is an entry into another tournament.
TI Format Timed The tournament finishes at a set time.
ME Format Multi Entry Players can register more than once and play
multiple tables.
T Speed Turbo Blinds level increase faster than normal.
ST Speed Super Turbo Blind levels increase faster than in a Turbo
tournament.
D Speed Deep Stack Starting stacks are larger than normal.
NBI Speed No Blind Static blind levels for the entirety of the
Increases tournament.
L Speed Lottery All players are automatically put All In at the
start.
N Speed Normal Blinds level increase at normal rate.
NL Structur No Limit
e
PL Structur Pot Limit
e
FL Structur Limit
e
SL Structur Spread Limit
e
ML Structur Mixed Limit
e
H Game Hold'em
OMAH Game Any Omaha O,OHL,O5,OHL5,CL,CLHL
A
O Game Omaha Hi
OHL Game Omaha H/L
O5 Game Omaha 5
OHL5 Game Omaha 5 H/L
CL Game Courchevel
CLHL Game Courchevel H/L
STUD Game Any Stud 7CS,7CSHL,5CS,RAZZ,A,S
7CS Game 7 Card Stud
7CSHL Game 7 Card Stud H/L
5CS Game 5 Card Stud
RAZZ Game Razz
A Game Americana
S Game Soko
DRAW Game Any Draw 5CD,BA,TD27L,SD27L,32D
5CD Game 5 Card Draw
BA Game Badugi
TD27L Game 2-7 Triple draw
SD27L Game 2-7 Single Draw

API REFERENCE MANUAL Page 33 of 54

 SHARKSCOPE REST WEB SERVICES

32D Game 32 Draw

MIXED Game Any Mixed HORSE,HEROS,HOSE,RASH,HA,HAR,SHOE,TE,
8G,7G
HORSE Game HORSE
HEROS Game HEROS
HOSE Game HOSE
RASH Game RASH
HA Game HA
HAR Game HAR
SHOE Game SHOE
TE Game Telesina
8G Game 8-Game
7G Game 7-Game
HBJ Game Holdem BJ
Easy Difficult Easy
y Tournament
Neutra Difficult Neutral
l y Tournament
Hard Difficult Hard
y Tournament
The list of possible values with grouping and description in English is included in the metadata.
3.11.6. STAKE CONSTRAINT
Defines the tournament stake ranges to be included as a comma separated list of ranges (or single
values) with currency and rebuy option. The format is <Currency ISO code>min~max[R] (e.g.
USD10~20R). The “R” postfix denotes that the average buy-in for the tournament including rebuys
will be used for rebuy tournaments. The minimum or maximum can be “*” meaning “any”.
Name Stake
Type Cash Range(s)
Examples Stake:USD2~10,GBP*~5R
Stake:USD20

3.11.7. RAKE CONSTRAINT

Defines the tournament rake ranges to be included as a comma separated list of ranges (or single
values) with currency and rebuy option. The format is <Currency ISO code>min~max (e.g.
USD10~20). The minimum or maximum can be “*” meaning “any”.
Name Rake
Type Cash Range(s)
Examples Rake:USD2~10,GBP*~5
Rake:USD20

3.11.8. STAKE PLUS RAKE CONSTRAINT

Defines the tournament stake plus rake ranges to be included as a comma separated list of ranges (or
single values) with currency and rebuy option. The format is <Currency ISO code>min~max[R] (e.g.
USD10~20R). The “R” postfix denotes that the average buy-in for the tournament including rebuys
will be used for rebuy tournaments. The minimum or maximum can be “*” meaning “any”.
This is similar to the Stake constraint with the Rake added.
Name StakePlusRake
Type Cash Range(s)
Examples StakePlusRake:USD2~10,GBP*~5R

API REFERENCE MANUAL Page 34 of 54

 SHARKSCOPE REST WEB SERVICES

StakePlusRake:USD20

3.11.9. GUARANTEE CONSTRAINT

Defines the tournament guarantee ranges to be included as a comma separated list of ranges (or single
values) with currency and rebuy option. The format is <Currency ISO code>min~max (e.g.
USD10~20). The minimum or maximum can be “*” meaning “any”.
Name Guarantee
Type Cash Range(s)
Examples Guarantee:USD10~100,GBP*~500
Guarantee:USD2000

3.11.10. OVERLAY CONSTRAINT

Defines the tournament overlay ranges to be included as a comma separated list of ranges (or single
values) with currency and rebuy option. The format is <Currency ISO code>min~max (e.g.
USD10~20). The minimum or maximum can be “*” meaning “any”.
Name Overlay
Type Cash Range(s)
Examples Overlay:USD10~100,GBP*~500
Overlay:USD2000

3.11.11. PRIZE CONSTRAINT

Defines the player’s tournament result prize range. The parameter format is the same as the Stake
constraint.
Name Prize
Type Cash Range(s)
Examples Prize:USD10~200, GBP5~100
Prize!:GBP*~100
Prize:USD1000

3.11.12. PRIZEPOOL CONSTRAINT

Defines the tournament prize pool range. The parameter format is the same as the Stake constraint.
Name PrizePool
Type CashRange(s)
Examples PrizePool:USD10~200, GBP5~150
PrizePool!:GBP*~500
PrizePool:USD2000

3.11.13. CLASS CONSTRAINT

Defines the tournament types to be included.
Name Class
Type Multiple selection
Examples Class:SNG
Class:SCHEDULED,LIVE
Tournament classes are SNG (Sit & Go), SCHEDULED and LIVE.
3.11.14. PLAYER CLASS CONSTRAINT
Defines the running or registering tournaments to be included in the response. The constraint defines
the ranges of participants of specific player classes. For example, the request can contain a player
class constraint of 2-4 players classified as “fish”. Only one player class per constraint can be defined,
however multiple player class constraints can be specified.
User specified player classes can be used.

API REFERENCE MANUAL Page 35 of 54

 SHARKSCOPE REST WEB SERVICES

In addition, each player class may have 1 or more categories assigned to it. Categories can be used in
place of player class names. For example, there are currently three player classes representing “shark”
players: HighStakesShark, MidStakesShark, LowStakesShark. These player classes are all members
of the category “Shark” so the total number of any type of shark players can be filtered.
Name Player Class
Type <Player Class>, Range
Examples PlayerClass:Fish,2~4 (2-4 fish tournaments)
PlayerClass:Fish,3~4;PlayerClass:Shark,0~0 (3-4 fish, no sharks)

3.11.15. LIMIT CONSTRAINT

Defines a range of results based on a specified context. The contexts are Best, Worst, First and Last.
The range is 1-based. This allows the user to request the specific number of tournaments to be taken
into consideration (or returned).
The Limit constraint will narrow the tournaments to the best, worst, oldest or latest based on the
specified range. So Limit:Best,1~250 will process the player’s best 250 tournaments. Best and worst
tournaments are determined by result (profit). First and Last are determined by date. Using this
constraint tournaments can be retrieved in parts.
Name Limit
Type <Context>, Range [ Context = Best, Worst, First, Last ]
Examples Limit:Best,1~250 (best 250 tournaments)
Limit:Worst,251~500 (second batch of worst tournaments)
Limit:Last,1~8 (last 8 tournaments)

3.11.16. SAVED FILTER CONSTRAINT

Users may save filters for future use. These filters are saved with a unique name. The filter can easily
be reused (optionally in conjunction with other constraints) by utilizing the “Saved” constraint. The
unique name must be URL encoded. The filter cannot be reversed with “!”, an error will be thrown if
reversal is specified.
Name Saved
Type Special
Examples Saved:MyFilter

3.11.17. VERSUS PLAYER

The “versus player” contains a player list. The response contains a PlayerView for the player and one
PlayerView containing tournaments against for each of the players in the list.
Name VersusPlayer
Type Player name list
Examples VersusPlayer:Tom
VersusPlayer:Tom,Tim

3.11.18. REBUYS CONSTRAINT

Defines the average number of rebuys to include when calculating statistics that contain rebuy
tournaments. By default the average number of rebuys used is the average number for players in that
tournament. A value of 0 would mean the player made no rebuys in any rebuy tournament.
Name Rebuys
Type Number
Examples Rebuys:2.5

3.11.19. RAKEBACK CONSTRAINT

Defines the rakeback percentage that should be included when calculating statistics.
Name Rakeback
Type Percentage

API REFERENCE MANUAL Page 36 of 54

 SHARKSCOPE REST WEB SERVICES

Examples Rakeback:25

3.11.20. TOURNAMENT NAME CONSTRAINT

The constraint is a filter on the tournament name. All tournaments whose name contains the provided
string are included (or excluded if inverted).
Name TournamentName
Type Text
Examples TournamentName:Holdem, TournamentName:$5%20Hold

3.11.21. REENTRIES CONSTRAINT

The constraint is a filter on tournaments where the player made the prescribed number of re-entries.
Name ReEntries
Type Integer
Examples ReEntries: 2

3.12. MISSING GAMES RESOURCES

Tournament results that exist on a network but are not found by SharkScope can be reported as
missing using the missing games resources. Reported missing games will be fetched, and if found,
will be added to the SharkScope database.
3.12.1. MISSING GAMES BY GAME IDS
Request to add missing game(s) using the game ids for the Pokerstars network(s). This missing games
resource has the following root URL:
https://www.sharkscope.com/api/appname/networks/network
name/reportmissinggames
The response contains all the provided Game IDs with status of processed, pending (already reported),
error, or existing. If the status is error the actual error message is also included.
The MissingTournamentsResponse contains the following attributes representing numbers of games:
total, processed, existing, pending, error. Only relevant attributes appear, e.g. if there are no errors the
attribute “error” will not be included. Example:
<MissingTournamentsResponse total="20" processed="15" existing="5">
In the above example, out of 20 game IDs, 15 were processed and 5 already existing. No errors
occurred and no pending games were provided. The parent element also contains one
MissingTournament element for each game containing a gameID attribute and a status attribute. The
status is one of “processed”, “pending”, “existing” or “error”. If the status is “error” then there is also
an attribute containing the error details in text.
<MissingTournaments gameID="123457820" status="processed" />
<MissingTournaments gameID="12345782a" status="error"
error="Invalid game ID" />
Type POST
Authentication Not Required.
Cost 0
Response A MissingTournamentsResponse object.
Path ReportMissingGames
Parameters gameids [FormParam for POST]
Example https://www.sharkscope.com/api/someapp/networks/pokerstars/reportmissinggames

API REFERENCE MANUAL Page 37 of 54

 SHARKSCOPE REST WEB SERVICES

3.12.2. MISSING GAMES BY TOURNAMENT SUMMARY

Request to add missing game(s) using tournament summary information from the Pokerstars
network(s) email system, using the following root URL:
https://www.sharkscope.com/api/appname/reportmissinggamesbysummary
A Pokerstars tournament summary (as plain text) must be included in the body of this request, in the
same format as the email received from Pokerstars when requesting a tournament summary from
them.

Example tournament summary:

Tournament History for Tournament #1 requested by SomeUsername (SomeEmail@gmail.com)
PokerStars Tournament #1234578820, No Limit Hold'em
Buy-In: $2.82/$0.18 USD
3 players
Total Prize Pool: $6.00 USD
Tournament started 2015/08/27 17:24:39 ET
Tournament finished 2015/08/27 17:40:14 ET
1: SomeUsername1 (Netherlands), $6.00 (100%)
2: SomeUsername2 (Luxembourg),
3: SomeUsername3 (Finland),
There are no personal statistics because you did not play in this tournament.

If you have any questions, please contact "PokerStars Support" <support@pokerstars.com>

The response contains the provided Game ID with status of processed, pending (already reported),
error, or existing. If the status is error the actual error message is also included.
The MissingTournamentsResponse contains the same structure as for Game IDs, except in this case
only one summary (a tournament summary email from Pokerstars) can be processed at a time.

Example response:
<MissingTournamentsResponse total="1" processed="1">
<MissingTournaments gameID="123457820" status="processed" />
</MissingTournamentsResponse>

The status is one of “processed”, “pending”, “existing” or “error”. If the status is “error” then there is
also an attribute containing the error details in text.
<MissingTournaments gameID="12345782a" status="error"
error="Invalid game ID" />
Type POST
Authentication Not Required.

API REFERENCE MANUAL Page 38 of 54

 SHARKSCOPE REST WEB SERVICES

Cost 0
Response A MissingTournamentsResponse object.
Path ReportMissingGamesBySummary
Parameters none
Data Parameter Tournament summary from Pokerstars as plain text – see example above
Example https://www.sharkscope.com/api/someapp/ reportmissinggamesbysummary

3.13. DEAL RESOURCES

Deal resources have the following root URL:
https://www.sharkscope.com/api/appname/deals/deal name

3.13.1. ACTIVATION
Requests the activation of a specific deal. The deal name must reflect an existing deal provided by
sharkscope for the given application. For signup deals you may use either the name “signup” or “*”.
The resource requires authentication as well as a unique ID and an activation code. The ID is a unique
identifier for the device or license of the product that comes with the deal. The activation code is the
username followed by the unique ID encoded in the same way as the password for the given
application (example follows). The response is either an error response if the deal is not found, the ID
or activation code is incorrect or missing, the deal is already activated; or a generic success response
with the text “Deal activated.”
Type GET
Authentication Required.
Cost 0
Response A genericResponse object.
Path https://www.sharkscope.com/api/appname/deals/deal
name/activate
Parameters ID [Required], activationCode [Required]
Example https://www.sharkscope.com/api/someapp/deals/signup/activate?id=1234?
activationCode=F3DE434598
https://www.sharkscope.com/api/someapp/deals/*/activate?id=1234?
activationCode=F3DE434598

To derive the activation code, first concatenate the username and the unique ID, lowercase the
resulting string and then scramble it using the same method as for scrambling the password described
in section 1.4 (Password Encoding). Example code in Java:
String username = someone@somewhere.com;
String uniqueID = “1234567890”;
String applicationKey = “21f5e7aa7893caf0”;
String code = username + uniqueID;
String key = code.toLowerCase() + applicationKey.toLowerCase();
byte[] defaultBytes = key.getBytes();
try {
MessageDigest algorithm = MessageDigest.getInstance("MD5");
algorithm.reset();
algorithm.update(defaultBytes);
byte messageDigest[] = algorithm.digest();

StringBuffer hexString = new StringBuffer();

for (int co = 0; co < messageDigest.length; co++) {
hexString.append(Integer.toHexString(0xFF & messageDigest[co]));
}
return hexString.toString().toLowerCase();
} catch (NoSuchAlgorithmException nsae){
...

API REFERENCE MANUAL Page 39 of 54

 SHARKSCOPE REST WEB SERVICES

3.14. PRIVATE LEADERBOARD RESOURCES

Gold subscribers can add their own Private Leaderboards for competitions between their friends or on
their forum etc. Up to 3 leaderboards can be created per account with up to 100 entrants in each.
Once created, a leaderboard will be updated daily provided the users gold subscription is active.
Private leaderboard resources have the following root URL:
https://www.sharkscope.com/api/appname/user/private-leaderboards

3.14.1. LIST
Retrieve all private leaderboards created by the user.
Type GET
Authentication Required.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path root
Parameters
Example https://www.sharkscope.com/api/someapp/user/private-leaderboards

3.14.2. CREATE
Creates a new private leaderboard (with no entrants). Leaderboard names must be unique across all
users.
Type GET
Authentication Required. Gold Subscriber Only.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path create
Parameters Authentication, filter, name, rankingstatistic, currency, mingamesfordisplay[Optional]
Example https://www.sharkscope.com/api/someapp/user/private-leaderboards/create?name=my
%20test
%20leaderboard&filter=Entrants:9;Stake:USD15~25;Type!:NL;Date:1325232000~13
27996800&rankingstatistic=Profit&currency=USD&mingamesfordisplay=10

3.14.3. EDIT
Edits an existing private leaderboard.
Type GET
Authentication Required. Gold Subscriber Only.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path <Private Leaderboard ID>/edit
Parameters Authentication, filter[Optional], name[Optional], rankingstatistic[Optional],
currency[Optional], mingamesfordisplay[Optional]
Example https://www.sharkscope.com/api/someapp/user/private-leaderboards/67867/edit?
filter=Entrants:9;Stake:USD15~25;Type!:NL;Date:1325232000~1327996800

3.14.4. DELETE
Deletes a user's private leaderboard entirely.

API REFERENCE MANUAL Page 40 of 54

 SHARKSCOPE REST WEB SERVICES

Type DELETE
Authentication Required.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path <Private Leaderboard ID>
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/private-leaderboards/76867

3.14.5. ENABLE
Enables a user's private leaderboard so that it is returned in public private leaderboard requests and
updated.
Type GET
Authentication Required.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path <Private Leaderboard ID>/enable
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/private-leaderboards/76867/enable

3.14.6. DISABLE
Disables a user's private leaderboard so that it is no longer returned in public private leaderboard
requests or updated.
Type GET
Authentication Required.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path <Private Leaderboard ID>/disable
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/private-leaderboards/76867/disable

3.14.7. ADD ENTRANT

Adds an entrant to a user's private leaderboard.
Type GET
Authentication Required.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path <Private Leaderboard ID>/<network>/<playername>
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/private-
leaderboards/76867/PokerStars/Alkazar99

3.14.8. REMOVEENTRANT
Removes an entrant from a user's private leaderboard.
Type DELETE
Authentication Required.
Cost 0
Response A UserPrivateLeaderboardResponse object.
Path <Private Leaderboard ID>/<network>/<playername>

API REFERENCE MANUAL Page 41 of 54

 SHARKSCOPE REST WEB SERVICES

Parameters Authentication
Example https://www.sharkscope.com/api/someapp/user/private-
leaderboards/76867/PokerStars/Alkazar99

3.15. STABLE RESOURCES

3.15.1. GET STABLE
Lists all the users and personal player names that have assigned the user account as their manager.
Type GET
Authentication Required.
Cost 0
Response A StableResponse object.
Path /stable
Parameters Authentication
Example https://www.sharkscope.com/api/someapp/stable

4. RESPONSE OBJECTS
All structural data including response from the API are represented as XML.
4.1. METADATA
The metadata response object contains the following objects:
 FilterDefinition
 Regions
 Networks
 Currencies
 PlayerStatisticsDefinitions
 TournamentStatisticsDefinitions
 DefaultPlayerClasses

4.1.1. FILTERDEFINITION
This is effectively a container of ConstraintDefinition objects.
4.1.2. CONSTRAINTDEFINITION
Represents a description of a filter constraint. It has an “id” and a “type” attribute. If the type is
“Multiselect” or “Selection” it also contains Option elements that define the possible values for the
selection. Example:
<ConstraintDefinition type="Multiselect" id="Type">
<Option type="Format" name="Tiered" description="The prize is a
ticket to the next tournament tier. Also known as Step tournaments."
id="TR" />
<Option type="Format" name="Matrix" description="4 simultaneous
Sit&Goes against the same players, with additional prizes for overall
performances." id="M" />
<Option type="Format" name="Bounty" description=" Additional prizes
are given for knocking players out. Also known as Knockout, Hitman and
HeadHunter tournaments." id="B" />
...
</ConstraintDefinition>

4.1.3. REGIONS
This is effectively a container of Region objects.

API REFERENCE MANUAL Page 42 of 54

 SHARKSCOPE REST WEB SERVICES

4.1.4. REGION
Represents poker network regions. Contains code, name and optional image attributes.
4.1.5. NETWORKS
This is effectively a container of Network objects.
4.1.6. NETWORK
Represents a poker network. It contains the following attributes:
name: the human-readable network name.
code: a two-letter code of the network.
region: the network’s region.
closed: true if the network is closed, false otherwise.
There are also the following coverage/availability Boolean attributes.
hudCoverage, scheduledCoverage, sitngoCoverage, tournamentSelector, tournamentOpener.
The network element also contains the following elements:
FullCoverageStartDate: the date when full coverage started.
FullCoverageTrackingRate: the percentage of the tracking rate of the full coverage.
UpdateInterval: how often the coverage data is updated in minutes.
EarliestGameTrackDate: the date of the earliest tracked game.
TrackedGamesCount: the number of tracked games.
CoverageStage: The coverage stage. “Full” means the network is fully covered.
If the network has skins these are included as simple elements.
Example:
<Network name="Live Events" code="li" … >
…
</Skins>
<Skin>Aussie Millions 100k</Skin>
<Skin>Hollywood Home Game</Skin>
<Skin>NHPC</Skin>
<Skin>PPT</Skin>
<Skin>WPT</Skin>
</Skins>
</Network>

4.1.7. CURRENCIES
This is effectively a container of Currency objects.
4.1.8. CURRENCY
Represents one of the currently supported currency. The attributes “symbol” and “iso” contain the
currency symbol and iso code respectively. The value contains the exchange rate value.
Examples:
<Currency symbol="C$" iso="CAD" />
<Currency symbol="€" iso="EUR" />
4.1.9. PLAYERSTATISTICSDEFINITIONS
This is effectively a container of PlayerStatisticDefinition and StatisticalDataSetDefinition objects.
4.1.10. PLAYERSTATISTICDEFINITION
Defines a player statistic. The id attribute contains the identifier included in player responses, the
name is the human-readable name of the statistic and the type defines the value type.
Examples:
<PlayerStatisticDefinition name="Av Stake" type="Currency" id="AvStake"/>
<PlayerStatisticDefinition name="Av ROI" type="Percentage" id="AvROI"/>

API REFERENCE MANUAL Page 43 of 54

 SHARKSCOPE REST WEB SERVICES

4.1.11. PLAYERSTATISTICALDATASETDEFINITION
Defines a player statistical data set. The id attribute contains the identifier included in player
responses, while the xAxisTitle and xAxisType define the name and type of the x axis for the z axis. If
the dataset is three-dimensional it will also contain zAxisTitle and zAxisType. It also contains Series
elements that define the id, type, and title of included data series.
Examples:
<StatisticalDataSetDefinition xAxisType="Timestamp"
xAxisTitle="Date" id="byDate">
<Series type="Currency" title="Total Profit ($)" id="totalProfit" />
<Series type="Currency" title="Average ROI ($)" id="averageROI" />
<Series type="Currency" title="Average Stake ($)" id="averageStake" />
<Series type="Number" title="Games Played" id="gamesPlayed" />
</StatisticalDataSetDefinition>

4.1.12. TOURNAMENTSTATISTICSDEFINITIONS
Simlar to PlayerStatisticsDefinitions, this is effectively a container of TournamentStatisticDefinition
and TournamentStatisticalDataSetDefinition objects.
4.1.13. TOURNAMENTSTATISTICDEFINITION
Defines a tournament statistic. The id attribute contains the identifier included in tournament
responses, the name is the human-readable name of the statistic and the type defines the value type.
4.1.14. PLAYERSTATISTICALDATASETDEFINITION
Defines a tournament statistical data set. The id attribute contains the identifier included in player
responses, while the xAxisTitle and xAxisType define the name and type of the x axis. If the dataset is
three-dimensional it will also contain zAxisTitle and zAxisType for the z axis.It also contains Series
elements that define the id, type, and title of included data series.
4.1.15. DEFAULTPLAYERCLASSES
This is a container of the default PlayerClass definitions. These can be overridden by users.
4.1.16. PLAYERCLASS
Represents a named set of rules that identify a particular player as a member of that class. The object
contains the name, priority and iconUri attributes, as well as the categories assigned to the player
class. The name is the identifier in other elements.
4.1.17. RULE
The player class rule represents a range of values for specific player statistics. A player’s relevant
statistic must fall within the defined range for the rule to be satisfied. All rules within a player class
must be satisfied for the player to be considered a member of the player class.
Also note that the player classes are relevant and depend upon any applied search filters. So, for
example, a particular player may be a “Fish” in scheduled tournaments and a “Shark” in $10-20 sit &
go tournaments.
4.2. USERMETADATA
The User metadata response object contains the following objects:
 UserFilters
 UserDefinedPlayerClasses

4.2.1. USERFILTERS
This is effectively a container of SavedFilter objects.
4.2.2. SAVEDFILTER
Represents a filter saved by the user. It has an “name” and a “type” attribute. The type attribute
determines if the filter is a player filter or a tournament selector filter or both. The value of the
element is the filter string. Example:

API REFERENCE MANUAL Page 44 of 54

 SHARKSCOPE REST WEB SERVICES

<UserFilters>
<SavedFilter type="All" name="SNG Only">Class:SNG</SavedFilter>
<SavedFilter type="Player" name="TestFilter">Entrants:5~10</SavedFilter>
</UserFilters>

4.2.3. USERDEFINEDPLAYERCLASSES
This is a container of the user defined PlayerClass definitions.
4.2.4. PLAYERCLASS
Represents a named set of rules that identify a particular player as a member of that class. The object
contains the name, priority and iconUri attributes, as well as the categories assigned to the player
class. The name is the identifier in other elements.
4.2.5. RULE
The player class rule represents a range of values for specific player statistics. A player’s relevant
statistic must fall within the defined range for the rule to be satisfied. All rules within a player class
must be satisfied for the player to be considered a member of the player class.
Also note that the player classes are relevant and depend upon any applied search filters. So, for
example, a particular player may be a “Fish” in scheduled tournaments and a “Shark” in $10-20 sit &
go tournaments.
4.3. PLAYER
The player response object contains a number of PlayerView objects:
4.3.1. PLAYERVIEW
This is a view to player’s data. It is defined by the filter and player network/name. It contains the
Filter and Player objects. The latter contains sparsely populated data depending on the request.
4.3.2. FILTER
The filter object represents the filter applied to the request. It is effectively a container of Constraint
objects that define individual filter constraints.
4.3.3. CONSTRAINT
The Constraint object represents individual filter constraints. The id attribute maps directly to a
ConstraintDefinition object in the metadata. Depending on the type it contains the value(s) of the
constraint in appropriate sub-elements.
Examples:
<Constraint id="Game">
<Selection id="O" />
<Selection id="OHL" />
<Selection id="7CS" />
<Selection id="7CSHL" />
</Constraint>
<Constraint id="Format">
<Selection id="HU" />
<Selection id="SAT" />
</Constraint>
<Constraint id="Stake">
<Minimum>2.00</Minimum>
</Constraint>
<Constraint id="Structure">
<Selection id="PL" />
<Selection id="FL" />
</Constraint>
<Constraint id="Limit">
<Value>100</Value>
</Constraint>

API REFERENCE MANUAL Page 45 of 54

 SHARKSCOPE REST WEB SERVICES

4.3.4. PLAYER
The player object contains sparsely populated data depending on the request. It always contains a
name and a network attribute that uniquely identifies the player. It may also optionally contain the
following objects:
Icon: If the player has associated icons.
Statistics: if statistics were requested and the player is not blocked.
recentTournaments: A list of the most recent tournaments, or
completedTournaments: A list of the current tournaments.
activeTournaments: A list of the current tournaments.
The player may also be a consolidated player group in which case the element name is PlayerGroup.
A player group doesn’t have a network attribute and contains one or more Player objects. These player
objects may only contain Icon objects, the statistics and recent tournaments for those players are
consolidated at the top level player group object.
Examples:
<Player network="PokerStars" name="someone">
<Icon type="blog" tip="Visit my Blog" image="images/icons/blog.gif"
url="http://www.sharkscopers.com/blog/21210" />
<Statistics ...
<RecentTournaments ...
</Player>

<PlayerGroup name="somePlayerGroup">
<Players>
<Player network="PokerStars" name="someone">
<Icon type="blog" tip="Visit my Blog"
image="images/icons/blog.gif"
url="http://www.sharkscopers.com/blog/21210" />
</Player>
<Player network="FullTilt" name="someone" />
</Players>
<Statistics ...
<RecentTournaments ...
</PlayerGroup>

4.3.5. STATISTICS
The statistics object is effectively a container of Statistic and StatisticalDataSet objects. It contains
two attributes: “optedIn” and “displayCurrency”. The “optedIn” attribute contains a Boolean value
and is “true” if the player has opted in. The display currency contains the currency used in statistic
values.
Examples:
<Statistics optedIn="true" displayCurrency="USD">
<Statistic id="Count">2198</Statistic>
<Statistic id="AvProfit">7.78</Statistic>
<Statistic id="AvStake">28.67</Statistic>
<Statistic id="AvROI">25.43</Statistic>
<Statistic id="TotalProfit">17091.70</Statistic>
<Statistic id="Form">LLLLWPLW</Statistic>
<Statistic id="TotalStake">63015.00</Statistic>
<StatisticalDataSet id="byDate">
<Data x="1122336000">
<Y id="totalProfit">-118.00</Y>
<Y id="averageROI">-76.62</Y>
<Y id="averageStake">20.00</Y>
<Y id="gamesPlayed">7</Y>
</Data>
<Data x="1122422400">
<Y id="totalProfit">60.00</Y>

API REFERENCE MANUAL Page 46 of 54

 SHARKSCOPE REST WEB SERVICES

<Y id="averageROI">90.91</Y>
<Y id="averageStake">20.00</Y>
<Y id="gamesPlayed">3</Y>
</Data>
<Data x="1122508800">
<Y id="totalProfit">152.00</Y>
<Y id="averageROI">276.36</Y>
<Y id="averageStake">25.00</Y>
<Y id="gamesPlayed">2</Y>
</Data>
<Data x="1123200000">
<Y id="totalProfit">-33.00</Y>
<Y id="averageROI">-100.00</Y>
<Y id="averageStake">30.00</Y>
<Y id="gamesPlayed">1</Y>
</Data>
</StatisticalDataSet>
</Statistics>

4.3.6. STATISTIC
The Statistic object represents a single statistical value. It contains an id attribute that refers to the
StatisticDefinition from the metadata. The value depends on the type.
Examples:
<Statistic id="Count">2198</Statistic>
<Statistic id="AvProfit">7.78</Statistic>
<Statistic id="AvStake">28.67</Statistic>
<Statistic id="AvROI">25.43</Statistic>

4.3.7. STATISTICALDATASET
The StatisticalDataSet object represents a set of values that can be represented as a graph. It contains
an id attribute that refers to the StatisticalDataSetDefinition from the metadata. It also contains Data
elements which define data points in the graph. The Y values map directly to the metadata definition.
Examples:
<StatisticalDataSet id="byDate">
<Data x="1122336000">
<Y id="totalProfit">-118.00</Y>
<Y id="averageROI">-76.62</Y>
<Y id="averageStake">20.00</Y>
<Y id="gamesPlayed">7</Y>
</Data>
<Data x="1122422400">
<Y id="totalProfit">60.00</Y>
<Y id="averageROI">90.91</Y>
<Y id="averageStake">20.00</Y>
<Y id="gamesPlayed">3</Y>
</Data>
<Data x="1122508800">
<Y id="totalProfit">152.00</Y>
<Y id="averageROI">276.36</Y>
<Y id="averageStake">25.00</Y>
<Y id="gamesPlayed">2</Y>
</Data>
<Data x="1123200000">
<Y id="totalProfit">-33.00</Y>
<Y id="averageROI">-100.00</Y>
<Y id="averageStake">30.00</Y>
<Y id="gamesPlayed">1</Y>
</Data>
</StatisticalDataSet>

API REFERENCE MANUAL Page 47 of 54

 SHARKSCOPE REST WEB SERVICES

4.3.8. PLAYERSUGGESTIONS
The PlayerSuggestions object is a container for player suggestions. It is returned in the
SearchSuggestionsResponse for the suggestions resource. The player suggestions object contains
Player objects with only the name, network and Icon objects populated.
Example:
<PlayerSuggestions>
<Player network="PokerStars" name="Alkazar99">
<Icon type="video" tip="Instructional videos are available. "
image="images/icons/video.gif"
url="http://www.sharkscopers.com/video/20" />
<Icon type="blog" tip="Visit my Blog"
image="images/icons/blog.gif"
url="http://www.sharkscopers.com/blog/20" />
</Player>
<Player network="PokerStars" name="Alkazar1972" />
<Player network="PokerStars" name="alkazarus" />
<Player network="PokerStars" name="alkazara" />
<Player network="PokerStars" name="alkazar13" />
<Player network="PokerStars" name="alkazar78" />
</PlayerSuggestions>

4.4. TOURNAMENT
The tournament response object contains information about running, registering or completed
tournaments. Completed tournaments returned as part of a Player response will only contain
participant information the player and no statistics.
4.4.1. STATISTICS
Tournaments have their own statistics and statistical datasets. The definitions of these statistics are
included in the metadata under “TournamentStatisticsDefinitions”.
4.4.2. TOURNAMENTENTRY
Tournament entry objects contain information about the participants of the tournament as Player
objects. The player objects contained in tournament entries only contain basic player information like
username, icons without statistics.
For completed tournaments, the position of the player in the tournament and profit are also included.
4.5. LEADERBOARDS
The metadata response object contains leaderboard definitions as a hierarchy or individual
leaderboads with their players depending on the request. Examples follow.
4.5.1. HIERARCHY:
<LeaderboardDisplayResponse>
<Leaderboards year="2010" subcategory="$101-$300"
category="Any Game">
<LeaderboardDisplay year="2010" valueType="average"
subcategory="$101-$300" category="Any Game"/>
<LeaderboardDisplay year="2010" valueType="total"
subcategory="$101-$300" category="Any Game"/>
</Leaderboards>
</LeaderboardDisplayResponse>

4.5.2. LEADERBOARD
<LeaderboardDisplayResponse>
<LeaderboardDisplay year="2010" valueType="total"
subcategory="$101-$300" category="Any Game">
<Details/>
<Rank value="132708.0" position="1" count="12216">
<Player network="FullTilt" name="rams85">

API REFERENCE MANUAL Page 48 of 54

 SHARKSCOPE REST WEB SERVICES

<Icon type="leaderboard" tip="..."

image="images/icons/diamondstar.gif"/>
</Player>
</Rank>
<Rank value="125355.0" position="2" count="5656">
<Player network="PokerStars" name="la_gâchette">
<Icon type="leaderboard" tip="..."
image="images/icons/diamondstar.gif"/>
</Player>
</Rank>
...
</LeaderboardDisplay>
</LeaderboardDisplayResponse>

API REFERENCE MANUAL Page 49 of 54

 SHARKSCOPE REST WEB SERVICES

5. SHARKSCOPE-AS-A-SERVICE (SHARKSCOPE-PUSH)

In addition to the API we offer a push service. Sharkscope-as-a-service can push each and every game
or a filtered subset of games on any network to you in real-time from our own game tracking system.
Game objects are serialized to JSON so they can be deserialized on many different platforms and
languages. Each game object is composed of over 50 fields which makes filtering and processing the
object quick and easy. The manner in which the object is pushed can vary depending on your needs
and throughput capabilities. Please contact us for more information .

API REFERENCE MANUAL Page 50 of 54

 SHARKSCOPE REST WEB SERVICES

6. ERRORS
6.1. DESCRIPTION
If a request fails for any reason an error response is returned. These have the following format:
<Response success="false" timestamp="1287868980">
<UserInfo>
...
</UserInfo>
<ErrorResponse>
<Error id="error code">Error Description
</Error>
</ErrorResponse>
</Response>
If the error code is 0 the error is internal and there is also a code supplied as and attribute that can be
used to report the error to SharkScope.
6.2. ERROR CODES
The following table shows the error codes that can be returned after a request, with their descriptions.
Error ID Description
0 Internal error.
101001 User not found.
101002 Invalid password.
101003 No username or password supplied.
101004 User already exists.
101005 User <username> already registered.
101006 Failed to create user.
101007 Failed to change the email.
101008 Invalid email address.
101009 An account already exists with this Email address.
101010 Failed to change the password.
101011 User-Agent header not specified
101012 Request information is not valid.
101013 Invalid username (must be a valid email address).
101014 Order number not found.
101015 Password email dispatch failed.
101016 User cannot be delete as they have payment entries registered to this account.
102001 Free daily searches quota used up.
102002 Daily searches quota used up.
102003 Pay-as-you-go searches used up.
102004 Operation only allowed for subscribers.
102005 Operation only allowed for gold subscribers.
103001 Invalid player class name.
103002 Invalid player class priority.
103003 Invalid player class rules.
103004 Player class not found.
103005 Player class update failed.
103006 Invalid player class currency.
105001 Player group not found.
105002 Invalid player group name.
105003 No valid player group members specified.

API REFERENCE MANUAL Page 51 of 54

 SHARKSCOPE REST WEB SERVICES

Error ID Description
105004 Player group already exists.
105005 Player not valid member for group.
105006 Player already in group.
105007 The group may be modified only by its owner.
105008 The maximum number of players allowed for this network have already been added to your personal group.
105009 Cannot add blocked players to groups.
105010 Personal group not configured.
105011 At least one member must be opted in.
106001 Maximum number of private leaderboards already exist.
106002 Private leaderboard contains maximum number.
106003 A private leaderboard with that name already exists.
106004 This player is blocked from being entered into leaderboards.
106005 This operation can only be performed on private leaderboards.
106006 This player is already in at least one leaderboard.
106007 This player was recently checked to see if they qualified for any leaderboards. Please try again later.

200001 Authentication failure.

200002 No valid statistics requested.
200003 Network not found.
200004 Player not found or opted out.
200005 Invalid player name prefix.
200006 Invalid native currency.
200007 Invalid display currency.
200008 Invalid tournament limit.
200009 Invalid mode.
200010 Leaderboard not found.
200011 Leaderboards not found.
200012 Tournament not found.
200013 Request not allowed on all networks.
200014 There is no installer/updater for this application
200015 Application not found.
200016 Valid download types are “installer” and “updater”.
200017 Invalid currency.
200018 Request not allowed on multiple users.
200019 Player is opted out
200020 Invalid URL
200021 You must enter a valid number for this parameter
200022 Database not found
200023 Unknown payment processor
200024 Cart is empty
200025 Missing parameter
200026 Opt Out request failed. Please contact support@sharkscope.com if the problem persists.
200027 Opt In request failed. Please contact support@sharkscope.com if the problem persists.
200028 This player has already been reset by another user.
200029 Blocks are not allowed on this network.
200030 Player belongs to one or more leaderboards.
200031 Player is not opted out.
200032 To unblock the user you must use the same email address as was used to block it
200033 Unknown confirmation request
200034 Too many usernames blocked on this network
200035 Report not found.
200036 Unknown report type.

API REFERENCE MANUAL Page 52 of 54

 SHARKSCOPE REST WEB SERVICES

Error ID Description
200037 Network has its own Opt/Out procedure.
200038 Reset date must be in the past.
200039 Player group not found.
200040 Player is not a member of the group.
200041 Task not found.
200042 Task not stopped.
200043 Task not active.
200044 The <network> database in currently under maintenance. Please try again later.
200045 Unknown graph type.
201001 Master databases are not active.
201002 Invalid load balancing.
201003 Server is busy. Try again later.
202001 Filter <filter> not found
202002 Filter not valid
202003 Load user filters failed
202004 Save failed
202005 Delete failed
204001 Unknown filter constraint “<constraint>”.
204002 Constraint “<constraint>” is not valid for this request.
204003 Invalid value(s) for filter constraint “<constraint>”
204004 Constraint “<constraint>” is not allowed at your user level.
204005 Constraint “<constraint>” cannot be inverted.
204006 Constraint “<constraint>” is not valid for this type of search.
300001 Invalid order parameter.
300002 Invalid order option.
300003 Failed to parse order range.
300004 Invalid order range.
300005 Order range start must be one or greater.
300006 Order range end must be greater than start.
305001 No activation credentials.
305002 Invalid activation code.
305003 No such deal.
305004 Deal already activated.
305005 Username or Account number not found. Please allow up to 3 days after completing the sign
up requirements for your details to be registered in our system.
305006 Not enough player points earned. Please allow up to 3 days after completing the sign up
requirements for your latest player points total to be registered in our system.
400001 No authorization for this action.
400002 Player not opted in.
400003 Resets not allowed on this network.
400004 Access to this network is not authorized.
400005 Access to this application is not authorized.
500001 Failed to retrieve payment properties.
500002 Payment initialization failed.
500003 Payment initialization response was invalid
500004 Invalid payment parameters
500005 Cart not found
500006 Payment confirmation failed
500007 Payment confirmation response was invalid

API REFERENCE MANUAL Page 53 of 54

 SHARKSCOPE REST WEB SERVICES

Error ID Description
500008 Subscription setup failed
500009 Multiple recurring subscriptions are not allowed
500010 Too many cart items
500011 IPN Processing failed.
500012 IPN not verified.
500013 Payment not found.
500014 Payment modification failed.
500015 Invalid refund amount.
500016 Only Completed payments can be refunded.
500017 Billing Agreements cannot be refunded through admin. Perform the refund on the PayPal
site and then update the SharkScope price.
500018 Operation not supported.
990001 Invalid username.
990002 Role not found.
990003 Invalid role ID.
990004 Insufficient funds.
990005 User creation failed.
990006 Payment registration failed.

API REFERENCE MANUAL Page 54 of 54