Getting Started

Quick Start Guide

1. Get API Credentials

   Contact SharkScope to obtain:

   • Your application name (appname)
   • Your application key (for password encoding)
   • Your username (email address)
   • Your password

2. Encode Your Password

   Encode your password using the double MD5 hash method:

   1. Calculate MD5 hash of your password
   2. Append your application key (lowercase)
   3. Calculate MD5 hash of the result

   Use the code examples above or the Password Encoding reference.

3. Make Your First Request

   Try the Metadata endpoint (no authentication required):

   curl -X GET "https://www.sharkscope.com/api/your-appname/metadata" \
     -H "Accept: application/json"

4. Make an Authenticated Request

   Try a player summary request:

   curl -X GET "https://www.sharkscope.com/api/your-appname/networks/PokerStars/players/PlayerName/summary?Username=your-email@example.com&Password=your-encoded-password" \
     -H "Accept: application/json"

5. Explore the API

   Browse all available API endpoints in the API Endpoints

Request Format

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

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 password's MD5 hash.

?Username=someone@somewhere.com&Password=ea3df3c7fa3557d23d2cf889b1a4c90d

Note: All REST calls that require authentication may include a username and password pair as headers instead of parameters.

Headers

The Accept header is required and should contain the response format required. This can currently be either XML or JSON.

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 encoding process is: MD5(MD5(password) + application_key)

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();
} catch (NoSuchAlgorithmException nsae) {
    // Handle exception
}

#!/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')

#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]);
    }
    
    return 0;
}

See full Password Encoding reference →

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. All date/time information are represented in this format.

Furthermore, all responses contain a UserInfo element which represents the authenticated user information. Resources that do not require authentication also contain a UserInfo element.

Response Element

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. Finally, the root element may contain an appVersion attribute containing the current version number of the application specified in the request.

<Response success="true" timestamp="1279612806" 
    metadataHash="f23ffdbb97027412c39cdba36e28b363" appVersion="3">
    <UserInfo>...</UserInfo>
    <!-- Response data -->
</Response>

UserInfo Element

The UserInfo element contains information of the authenticated user.

<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>

The UserInfo element should be checked to confirm that authentication was successful (loggedIn="true") and to report the number of remaining searches.

ErrorResponse Element

The ErrorResponse root element contains error information and is returned when the call is unsuccessful.

<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.

See full Error Codes reference →

Filter Overview

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 in the Filter Constraints reference.

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.

?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 NOT Satellite
• The Stake was more than or equal to $2

See full Filter Constraints reference →

Next Steps