Asianodds Push API

Version 1.3, January 31, 2017

This document provides a guide to developing applications using the Asianodds88 Push Application Programming Interface (API). It defines those aspects of the API that are available for client-side customer usage. The API provides a set of tools to build clients that access information from the API. The API handles client-server communication, data conversions, data validation and security. Just call simple API functions and listen to events. It is really that simple. We also offer a RESTful service which is described in a separate document.


Getting the API

Please contact Asianodds support to get the API. Support can create you the necessary credentials as well as provide connection details.

Email: support@asianodds88.com

Skype ID: asianodds88


Updating the API

New versions of the API may be released from time to time. Generally, these updates will include mandatory bug fixes, performance improvements and handy new features. Make sure you always use the latest API as failure to update can result in loss of service.


API Files

During the installation process the following files will be deployed:

  • ● AsianoddsAPI.dll
  • ● AsianoddsAPIObjects.dll
  • ● APIMessaging.dll
  • ● Newtonsoft.Json.dll
  • ● protobuf-net.dll
  • ● log4net.dll
  • ● Logger.dll

Installing the API

Run the Asianodds API executable to install the software. During the installation process it will copy required libraries, documentations and will also register some COM objects.


1. Event Handling

The API is fundamentally asynchronous - applications initiate operations and subsequently receive events to notify them of the results; however, there are some operations that are synchronous for your convenience.

There are two ways to receive API events. You can use one or a combination of them. The same data is delivered in both cases.

During development, avoid doing long running operations on the event threads. Instead, move the data to another thread and process it from there to make sure that the data delivery is uninterrupted.


When using the API from winform applications please remember that callbacks are made on separate threads so invoke is required to bring the data back to the GUI thread.

1.1. Dedicated Events

All data types that support subscription have its own event. Subscribing to these events is the most convenient way to receive data from the API. Events usually (but not always) return an object which can later be converted to json or xml if needed using built-in features.

See the following example that subscribes to odds updates:

static void Main(string[] args)
{
AsianoddsAPI.Asianodds api = new AsianoddsAPI.Asianodds();
api.OnOddsData += new OddsDataEventHandler(api_OnOddsData);
}
void api_OnOddsData(AsianoddsAPIObjects.GameObject gameObject)
{
//do something
}
Example 1 - Receiving Events

There are events that will fire only if you first let the API know that you are interested in receiving that kind of data (e.g.: OnOddsData). Other events are fired regardless of whether you are interested or not (e.g.: OnAccountSummaryChange).

1.2. Events through OnReceive()

The OnReceive event is for developers who prefer to receive data through a single channel. The format can be preselected as either json or xml

See the following example for receiving events on the OnReceive() channel:

static void Main(string[] args)
{
AsianoddsAPI.Asianodds api = new AsianoddsAPI.Asianodds();
api.OnReceive += new ReceiveEventHandler(api_OnReceive);
}
void api_OnReceive(string msgType, string message)
{
switch (msgType)
{
case "OddsUpdate":
//do something
break;
}
}
Example 2 - Receiving events on the OnReceive() channel

2. Error Handling

In case of an error, the API will throw an exception and/or raise the error through the OnError event. Exception and errors have to be handled in the user’s code.

In this document, we describe all possible errors and exceptions that the developers can receive while using the API. Failing to properly handle these error conditions may result in unexpected API behavior.

Example of handling errors:

static void Main(string[] args)
{
AsianoddsAPI.Asianodds api = new AsianoddsAPI.Asianodds();
try
{
api.OnError += new ErrorEventHandler(api_OnError);
api.Init("api.asianodds88.com", 4111, "Your Username",
api.CalculateMD5Hash("Your Password"));
}
catch (AsianoddsAPI.AsianoddsExceptions.InitializationException ex)
{
//do something
}
}
void api_OnError(int errorCode, string errorMessage)
{
//do something
}
Example 3 - Error handling

Usually errors raised by the API on the client side are thrown as exception and errors raised on the server side are delivered via events through the OnError callback.

See Exceptions and Errors chapter for detailed descriptions.

3. Logging

The API has a built-in logging feature that can help in debugging your application during development. Create an instance of the Logger and place the provided log4net.config in your application root folder and that’s it.

The API will be generating logs on its own which can help you to identify issues during the development process but you can also write your log entries as shown in the following example:

static Logger.Logger apiLogger = new Logger.Logger(false);
static AsianoddsAPI.Asianodds api = new AsianoddsAPI.Asianodds();
static void Main(string[] args)
{
api.OnEvent += new EventEventHandler(api_OnEvent);
api.Init("api.asianodds88.com", 4111, "Your Username",
api.CalculateMD5Hash("Your Password"));
} static void api_OnEvent(string eventMsg)
{
apiLogger.Info(eventMsg);
}
Example 4 - Using the built in logger

All log entries will be timestamped so there is no need to add date and time to your entries. The provided log4net.config can be changed freely. For more information about log4net and configuration options go to https://logging.apache.org/log4net/

4. Quick Start

The provided API DLLs were compiled with 32bit platform flag. Using them from x64 apps can lead to issues so make sure that you compile your code as 32bit (x86).

4.1. API Initialization

Create an instance of the API and subscribe to API events. Call the Init() function and wait for events.

An example can be seen below:

static void Main(string[] args)
{
AsianoddsAPI.Asianodds api = new AsianoddsAPI.Asianodds();
api.OnLoginStatusChange +=
new LoginEventHandler(api_OnLoginStatusChange);
api.OnAccountSummaryChange +=
new AccountSummaryEventHandler(api_OnAccountSummaryChange);
api.OnEvent += new EventEventHandler(api_OnEvent);
api.OnError += new ErrorEventHandler(api_OnError);
api.OnReceive += new ReceiveEventHandler(api_OnReceive);
api.OnBetTicket += new BetTicketEventHandler(api_OnBetTicket);
api.OnLeagueNameList +=
new LeagueNameListEventHandler(api_OnLeagueNameList);
api.OnTeamNameList +=
new TeamNameListEventHandler(api_OnTeamNameList);
api.OnMatchObject += new MatchObjectEventHandler(api_OnMatchObject);
api.OnOddsData += new OddsDataEventHandler(api_OnOddsData);
api.SetMessageFormat((int) Helper.MessageFormat.json);
api.Init("api.asianodds88.com", 4111, "Your Username",
api.CalculateMD5Hash("Your Password"));
}
Example 5 - API initialization

Always subscribe to events first as you can lose important callbacks if calling Init() before your application is subscribed to events.

Only one API instance per application is supported. Multiple API instances may work however it is a nonrecommend operation. Do it at your own risk.

The API communication can switch IP during operation. The IP that was used to initiate the connection will not necessarily be the one that is used during operation.

4.2. Init()

Calling the Init() function will initialize the API and will try to log the customer in using the provided connection parameters and credential.

void Init(string serverIP, int serverPort, string userId,
string password)

It is an asynchronous process. Listen to event OnLoginStatusChange to get notification about changes in the connection status. Use the CalculatePasswordHash function to hash your password.

Never store the clear text version of your password in your code. Calculate a hashed version and use that instead.

The API object can be initialized only once. If you face any issue during login please dispose the object before trying to initialize it again. Otherwise an InitializationException will be raised.

For connection details and credentials, please contact Asianodds88 support.

Input Parameters

Parameter Type Description
serverIP string The host name or IP address of the Asianodds88 API server
serverPort int Port where the API server is listening
userId string Your API username
Password string Hashed version of your API password

Return Type

● None

Raised Events

● ONLOGINSTATUSCHANGE

Exception Type

● INITIALIZATIONEXCEPTION

- Raised when calling the Init() function on an object that is already initialized. Create a new instance before calling Init() again.

● INVALIDOPERATION

- A basic sanity check runs on all input parameter and this exception is raised when incorrect values are detected.

Errors

● AN INVALID IP ADDRESS WAS SPECIFIED [101]

- Check the IP address and make sure that it is either a valid IPV4 address or a hostname.

● NO CONNECTION COULD BE MADE BECAUSE THE TARGET MACHINE ACTIVELY REFUSED IT [101]

- Talk to Assianodds support and check the IP address and port number of the service. Also check your firewall and make sure that it is not preventing the API to connect to the server side.

Events raised during initialization and login process

If you subscribe to OnEvent callback you will receive API events that will expose the different stages of the login process.

The following output was recorded during a successful login:

Event: Initializing Asianodds API...
Event: *****************************
Event: Asianodds API
Event: Version: 1.0.7.216
Event: Object Version: 1.0.7.83
Event: © 2016, asianodds88.com
Event: All rights reserved
Event: *****************************
Event: Checking external IP
Event: My external IP is 64.39.212.219
Event: Connecting to 119.81.251.217
Event: Connection status changed. New state: Conected
Event: Sending login message
Event: Login response received
Event: New login state: :Logged In
Output 1 - Login

4.3. CalculatePasswordHash()

The function can be used to convert a clear text password to hashed one. You need to use this function for the login process only.

static string CalculatePasswordHash(string password)

This is a static function of the API.

Input Parameters

Parameter Type Description
password string API password

Return Type

● STRING – hashed version of the clear text password

Raised Events

● None

Exception Type

● None

Errors

● None

4.4. Logout()

The call will logout the API user and terminate the client-server connection.

void Logout()

Logout called automatically if another session is initiated with the same login credentials. Strictly one connection per account is permitted.

It is advised to call this function when exiting your application however the server side will logout the user even if Logout() wasn’t called before the session was terminated.

Input Parameters

● None

Return Type

● None

Raised Events

● None

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

4.5. SetMessageFormat()

The object conversion can be set with the help of the SetMessageFormat() function. This is used only in OnReceived callbacks. It will not affect data delivery in any other calls.

void SetMessageFormat(int format)

MessageFormat enumeration is available in AsianoddsAPIObjects library. See the Enumeration chapter for more details.

Input Parameters

Parameter Type Description
format int Object format ID:
0 – XML
1 – JSON

Return Type

● None

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the value of the format property is not in the supported range.

Errors

● None

4.6. SetOddsFormat()

Use this function to set or change the format of the odds.

void SetOddsFormat(int format)

Currently the following types are supported: Malay (MY), Hong Kong (HK), Decimal (00)

Any odds messages delivered after the odd format change will be in the new format. It is recommended to unsubscribe, change odd format and then re-subscribe to get all current odds in the new format.

Input Parameters

Parameter Type Description
format int Object format ID:
0 – Malay (MY)
1 – Hong Kong (HK)
2 – Decimal (00)

Return Type

● None

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the value of the format property is not in the supported range.

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

4.7. GetAPIVersion()

Use this function to get the version number of the API in string format.

string GetAPIVersion()

This is a static function.

Input Parameters

● None

Return Type

● STRING – version number of the API

Raised Events

● None

Exception Type

● None

Errors

● None

5. Synchronous Functions

The provided API DLLs were compiled with 32bit platform flag. Using them from x64 apps can lead to issues so make sure that you compile your code as 32bit (x86).

Please remember that these calls will hold the calling thread until the requested data becomes available.

Depending on the network latency between the client and server the wait time can be even hundreds of milliseconds. Keep that in mind when designing your application.

The calls provide a dataset that can change over time. You will not get any notification of such changes. In some cases the same functionality is available in an asynchronous version too. Use that if you want to keep an up to date version of the requested data.

5.1. GetSports()

SportList GetSports()

An XML example of the data returned by the call can be seen below:

[SportList]
[Sports]
[SportItem]
[Name]Football[/Name]
[SportId]1[/SportId]
[/SportItem]
[SportItem]
[Name]Basketball[/Name]
[SportId]2[/SportId]
[/SportItem]
[/Sports]
[/SportList]
Output 2 - List of available sports

Input Parameters

● None

Return Type

● SPORTLIST – list of available sports

Raised Events

● None

Exception Type

● None

Errors

● None

5.2. GetBookieList()

It returns all the available sportsbooks for the requested sport.

BookieList GetBookieList(int sportId)

It is a general list for the given sport and does not mean that all games are quoted by all bookies.

XML example of the data returned:

[SportList]
[BookieList]
[Bookies]
[BookieItem]
[SourceId]IBC[/SourceId]
[Name]IBCBet[/Name]
[/BookieItem]
[BookieItem]
[SourceId]SBO[/SourceId]
[Name]SBOBET[/Name]
[/BookieItem]
[BookieItem]
[SourceId]PIN[/SourceId]
[Name]Pinnacle Sports[/Name]
[/BookieItem]
[BookieItem]
[SourceId]SIN[/SourceId]
[Name]Singbet[/Name]
[/BookieItem]
[BookieItem]
[SourceId]ISN[/SourceId]
[Name]BETISN[/Name]
[/BookieItem]
[BookieItem]
[SourceId]GA[/SourceId]
[Name]GA288[/Name]
[/BookieItem]
[/Bookies]
[/BookieList]
Output 3 - List of available bookies

Input Parameters

Parameter Type Description
sportId int The ID of the requested sport. Use GetSports() for the list of available sports.

Return Type

● BOOKIELIST – list of available sportsbooks

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the value of the sportId is invalid

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

5.3. GetTeamNames()

Returns a collection with the team names for the given sport and market. This is a snapshot of the names

NameList GetTeamNames(int sportId, int marketId)

The list is in an alphabetical order. The names are Asianodds internal names and they don’t necessarily match the sportsbook names.

An XML example of the data returned by the call can be seen below:

[NameList]
[SportId]1[/SportId]
[MarketId]0[/MarketId]
[List]
[string]Albirex Niigata[/string]
[string]Avispa Fukuoka[/string]
[string]Bentleigh Greens[/string]
[string]Brisbane City FC (Youth)[/string]
[string]Brisbane Olympic (W)[/string]
[string]Bucheon 1995[/string]
[string]Bucheon FC 1995[/string]
[string]FC Tokyo[/string]
[string]Gamba Osaka[/string]
[string]Hiroshima Sanfrecce[/string]
[string]Incheon United[/string]
[string]Jeonbuk Hyundai Motors[/string]
[string]Jeonnam Dragons[/string]
[string]Jubilo Iwata[/string]
Output 4 - Team name list

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market

Return Type

● NAMELIST – snapshot of the team names

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range.

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

● TIMEOUTEXCEPTION

- Raised if the call times out while waiting for server response

Errors

● None

5.4. GetLeagueNames()

Returns a collection with league names for the given sport and market. This is a snapshot of the leagues.

NameList GetLeagueNames(int sportId, int marketId)

The list is in an alphabetical order. The names are Asianodds internal names and they don’t necessarily match the sportsbook names.

An XML example of the data returned by the call can be seen below:

[NameList]
[SportId]1[/SportId]
[MarketId]1[/MarketId]
[List]
[string]AUSTRALIA BRISBANE WOMEN ELAINE WATSON CUP[/string]
[string]AUSTRALIA NEW SOUTH WALES NATIONAL PREMIER LEAGUE[/string]
[string]AUSTRALIA QUEENSLAND NATIONAL YOUTH PREMIER LEAGUE[/string]
[string]AUSTRALIA VICTORIA DOCKERTY CUP[/string]
[string]JAPAN J-LEAGUE DIVISION 1[/string]
[string]KOREA FA CUP[/string]
[string]CHILE CUP[/string]
[string]COLOMBIA PRIMERA A[/string]
[string]COPA LIBERTADORES[/string]
[string]ECUADOR PRIMERA A[/string]
[string]ECUADOR PRIMERA B[/string]
[string]FINLAND VEIKKAUSLIIGA[/string]
[string]MALAYSIA CUP[/string]
[string]SWEDEN 1ST DIVISION NORTH[/string]
[/List]
[/NameList]
Output 5 - League names

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market

Return Type

● NAMELIST – snapshot of the league names

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range.

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

● TIMEOUTEXCEPTION

- Raised if the call times out while waiting for server response

Errors

● None

5.5. GetMatchList()

Returns a collection of match objects for the given sport and market. This is a snapshot of matches currently held in the Asianodds system.

MatchObjectList GetMatchList(int sportId, int marketId)

See SubscribeMatchList() for a subscription based alternative to this function. You will also see in that section how to use the calls together.

This collection can become outdated as matches move from early to today, today to live and live games can finish. Also, from time to time there are changes in the kickoff time.

An XML example of the data returned by the call can be seen below:

[MatchObjectList]
[marketId]0[/marketId]
[sportId]1[/sportId]
[matchList]
[MatchObject]
[MatchId]-1395446242[/MatchId]
[HomeName]Cambodia U16[/HomeName]
[AwayName]Brunei Darussalam U16[/AwayName]
[LeagueName]AFF U16 CHAMPIONSHIP (IN CAMBODIA)[/LeagueName]
[SportId]1[/SportId]
[MarketId]0[/MarketId]
[KickoffTime]2016-07-13T11:30:00[/KickoffTime]
[/MatchObject]
[MatchObject]
[MatchId]-139512352[/MatchId]
[HomeName]China U17[/HomeName]
[AwayName]South Korea U16[/AwayName]
[LeagueName]FOUR NATIONS TOURNAMENT (IN CHINA)[/LeagueName]
[SportId]1[/SportId]
[MarketId]0[/MarketId]
[KickoffTime]2016-07-13T11:35:00[/KickoffTime]
[/MatchObject]
[MatchObject]
[MatchId]1837341971[/MatchId]
[HomeName]Guangzhou R&F[/HomeName]
[AwayName]Hebei China Fortune[/AwayName]
[LeagueName]CHINA FA CUP[/LeagueName]
[SportId]1[/SportId]
[MarketId]0[/MarketId]
[KickoffTime]2016-07-13T11:00:00[/KickoffTime]
[/MatchObject]
[MatchObject]
[MatchId]-2112224507[/MatchId]
[HomeName]Henan Jianye[/HomeName]
[AwayName]Jiangsu Suning FC[/AwayName]
[LeagueName]CHINA FA CUP[/LeagueName]
[SportId]1[/SportId]
[MarketId]0[/MarketId]
[KickoffTime]2016-07-13T11:35:00[/KickoffTime]
[/MatchObject]

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market

Return Type

● MATCHOBJECTLIST – snapshot of the current matches

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range.

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

● TIMEOUTEXCEPTION

- Raised if the call times out while waiting for server response

Errors

● None

5.6. GetBetLimits()

Returns the minimum and maximum stake that the bookie takes for the requested game. If there is no response within the specified timeout (ms) the API will raise an exception.

BetLimit GetBetLimits(int sportId, int marketId, int lineId, char term, char gameType, char betType, string sourceId, int timeout)

An XML example of the data returned by the call can be seen below:

[BetLimit]
[MinAmount]5[/MinAmount]
[MaxAmount]659[/MaxAmount]
[Currency]USD[/Currency]
[SourceId]IBC[/SourceId]
[/BetLimit]

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
lineId int ID of the betting line
term char Game period (See Enum: Term for reference)
gameType char Game type (See Enum: GameType for reference)
betType char Bet type (See Enum: BetType for reference)
sourceId string Two/three-letter notation of the book
timeout int Maximum time for waiting for a response from the server

Return Type

● BETLIMIT – min/max amount advertised by the bookie.

Raised Events

● None

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range.

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

● TIMEOUTEXCEPTION

- Raised if the call times out while waiting for server response

Errors

● None

5.7. GetHistoryStatement()

Returns an array of statement objects that will give you information about turnover, win/loss, etc. for a given time period.

HistoryStatement[] GetHistoryStatement(string from, string to, string bookieList)
This collection contains settled bets only.

Input Parameters

Parameter Type Description
from string From date (MM/DD/YYYY)
to string To date (MM/DD/YYYY)
bookieList string Comma separated bookie list

Return Type

● HISTORYSTATEMENT[] – Array of statement object

Raised Events

● None

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

● TIMEOUTEXCEPTION

- Raised if the call times out while waiting for server response

Errors

● None

5.8. GetBetByReference()

Returns a bet ticket with the given referenceId.

void GetBetByReference(string betId)

Input Parameters

Parameter Type Description
betId string Unique identifier of the bet

Return Type

● BETTICKET – Bet ticket object

Raised Events

● None

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

● TIMEOUTEXCEPTION

- Raised if the call times out while waiting for server response

Errors

● None

6. Asynchronous Calls

When using asynchronous calls we just tell the API that we are interested in certain type of data and the API will transfer that request to the server. The server registers the interest and will send back the data when it becomes available.

The API will not wait for the data and the call immediately returns to the caller. That means it will not block the calling thread.

Once there is available data that matches the client’s request, the server will send that down to the API which then make it available to the client through callbacks (events). Check the function documentation to see on what channel you can expect the data.

When using the API from winform GUI’s please remember that the callbacks are not made on the GUI thread. Invoke is required to bring the data back to the main thread.

For example:

public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void button1_Click(object sender, EventArgs e)
{
//create an instance of the API
AsianoddsAPI.Asianodds api = new AsianoddsAPI.Asianodds();
//register for callbacks on the OnEvent event
api.OnEvent += new AsianoddsAPI.EventEventHandler(api_OnEvent);
//login
api.Init("119.81.251.217", 4111, "DemoUser",
api.CalculatePasswordHash("DemoPassword"));
}
delegate void _api_OnEvent(string eventMsg);
void api_OnEvent(string eventMsg)
{
if (InvokeRequired)
{
//bring the call back to the GUI thread
_api_OnEvent d = new _api_OnEvent(api_OnEvent);
this.BeginInvoke(d, new object[] { eventMsg });
}
else
{
//add eventMsg to the listbox
listBox1.Items.Add(eventMsg);
}
}
}
Example 6 - Invoke

6.1. SubscribeMatchList()

Similarly to the GetMatchList() call this function is to receive one or a series of match objects. The main difference between the two calls is that by calling this subscription based function you will receive updates if a match object changed (e.g.: new kickoff time) or if a new match shows up in the system.

void SubscribeMatchList(int sportId, int marketId)

Through this call you will not receive the current objects. Only new or changed match objects will be delivered. Use it together with GetMatchList() to keep a complete and up to date list.

Always subscribe for updates with SubscribeMatchList() first and then get the current match collection with GetMatchList() to make sure that no updates are missed.

[MatchObject xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"]
[MatchId]777433440[/MatchId]
[HomeName]Italy U19[/HomeName]
[AwayName]Austria U19[/AwayName]
[LeagueName]UEFA U19 CHAMPIONSHIP (IN GERMANY)[/LeagueName]
[SportId]1[/SportId]
[MarketId]0[/MarketId]
[KickoffTime]2016-07-14T10:00:00[/KickoffTime]
[/MatchObject]

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market

Return Type

● None

Raised Events

● ONMATCHOBJECT

- MatchObject typed objects are provided with the callback

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range.

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.2. UnsubscribeMatchList()

Subscription that was initiated with SubscribeMatchList() call can be terminated with calling UnsubscribeMatchList().

void UnsubscribeMatchList(int sportId, int marketId)

Following this call you will receive no more OnMatchObject events.

SubscriptionId has to be unique. If you re-use the IDs previous subscription will be overwritten without warning.

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
subscriptionId string Unique identifier of the subscription

Return Type

● None

Raised Events

● None

- Event is fired when there is a new GameObject to be delivered

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.3. SubscribeMarket()

This call will tell the server to see all odds updates for all matches for the specified sport and market. First you will receive a snapshot of the current matches/odds and then there will be a new callback every time there is a change.

void SubscribeMarket(int sportId, int marketId, string subscriptionId)

The object type passed along with the OnOddsData update is GameObject.

SubscriptionId has to be unique. If you re-use the IDs previous subscription will be overwritten without warning.

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
subscriptionId string Unique identifier of the subscription

Return Type

● None

Raised Events

● ONODDSDATA

- Event is fired when there is a new GameObject to be delivered

● ONODDSREMOVED

- Event is fired when one of the GameObject lines are removed

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.4. SubscribeLeague()

First read the SubscribeMarket() section. Everything that is written there applies here too. The only difference is that instead of receiving updates on all games you will be getting only those where the league name matches the name specified in the subscription.

void SubscribeLeague(int sportId, int marketId, string subscriptionId, string leagueName)

For league name asterisk (*) can be used as a wildcard character.

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
subscriptionId string Unique identifier of the subscription
leagueName string League name that you want to receive updates from

Return Type

● None

Raised Events

● ONODDSDATA

- Event is fired when there is a new GameObject to be delivered

● ONODDSREMOVED

- Event is fired when one of the GameObject lines are removed

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.5. SubscribeTeam()

This subscription will send you update from the specified market if the league name matches your leagueName parameter and if either the home or away name matches the teamName parameter.

void SubscribeTeam(int sportId, int marketId, string subscriptionId, string leagueName, string teamName)

For league name asterisk (*) can be used as a wildcard character.

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
subscriptionId string Unique identifier of the subscription
leagueName string League name that you want to receive updates from
teamName string Team name that you want to receive updates from

Return Type

● None

Raised Events

● ONODDSDATA

- Event is fired when there is a new GameObject to be delivered

● ONODDSREMOVED

- Event is fired when one of the GameObject lines are removed

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.6. SubscribeMatch()

With the help of this call you can subscribe to receive updates from one single match. Updates will stop automatically when the match is over however the subscription remains active.

void SubscribeMatch(int sportId, int marketId, string subscriptionId, string leagueName, string homeName, string awayName)

For league name asterisk (*) can be used as a wildcard character.

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
subscriptionId string Unique identifier of the subscription
leagueName string League name that you want to receive updates from
teamName string Team name that you want to receive updates from
homeName string Home team name
awayName string Away team name

Return Type

● None

Raised Events

● ONODDSDATA

- Event is fired when there is a new GameObject to be delivered

● ONODDSREMOVED

- Event is fired when one of the GameObject lines are removed

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.7. Unsubscribe()

Subscriptions that was registered through SubscribeMarket(), SubscribeLeague(), SubscribeTeam() or SubscribeMatch() can be cancelled with this call.

void Unsubscribe(string subscriptionId)

Provide a previously used subscription ID to stop receiving updated.

Input Parameters

Parameter Type Description
subscriptionId int ID of the subscription you want to stop

Return Type

● None

Raised Events

● None

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.8. UnsubscribeAll()

The call will cancel all subscriptions that was registered through SubscribeMarket(), SubscribeLeague(), SubscribeTeam() or SubscribeMatch().

void UnsubscribeAll()

Provide a previously used subscription ID to stop receiving updated.

Input Parameters

● None

Return Type

● None

Raised Events

● None

Exception Type

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.9. RequestBetLimits()

Sends a request for the minimum and maximum stake that the bookie takes for the requested game. If there is no response within the specified timeout (ms) the API will raise an exception.

BetLimit GetBetLimits(int sportId, int marketId, int lineId, char term, char gameType, char betType, string sourceId, int timeout)

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
lineId int ID of the betting line
term char Game period (See Enum: Term for reference)
gameType char Game type (See Enum: GameType for reference)
betType char Bet type (See Enum: BetType for reference)
sourceId string Two/three-letter notation of the book

Return Type

● None

Raised Events

● ONBETLIMIT

- Event is fired when there is a new BetLimit object received

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

6.10. PlaceBet()

Sends a request to place a bet.

PlaceBet(int sportId, int marketId, int lineId, char term, char gameType, char betType, double stake, double odds, bool acceptWorst, double HDP_Goal, List bookieList, string betId)

Input Parameters

Parameter Type Description
sportId int ID of the sport
marketId int ID of the market
lineId int ID of the betting line
term char Game period (See Enum: Term for reference)
gameType char Game type (See Enum: GameType for reference)
betType char Bet type (See Enum: BetType for reference)
stake double Amount to be placed for the bet
odds double Odds in which the bet is to be placed
acceptWorst bool Flag to tell if bet will push through if odds go down
HDP_Goal double Handicap (in case of HDP betting) or Goal (in case of OU) for the bet
bookieList List Selected bookies to place the bet on
betId string Assigned ID for the bet

Return Type

● None

Raised Events

● ONBETTICKET

- Event is fired when there is a new BetTicket object or one has changed

Exception Type

● UNSUPPORTEDOPERATION

- Raised when the input values are not in the supported range

● NOTCONNECTEDEXCEPTION

- Raised if the function called when the API is not connected

Errors

● None

7. API Events

7.1. OnLoginStatusChange

This event is fired when there is a change in the API’s login status. This is the first event received after a successful API initialization.

void OnLoginStatusChange(bool isLoggedIn, string message)

When IsLoggedIn is set to true it means the login was successful and you are logged in to the Asianodds system. The message string will be empty as there were no errors.

Read the message string for further details about while the login failed if IsLoggedIn is set to false.

Errors that are raised in this event:

● INVALID USERID OR PASSWORD

- Check your login credentials and try again. It is likely that either the userId or the password is incorrect. Make sure that the password is hashed using the CalculatePasswordHash function.

● INCORRECT API VERSION

- In order to avoid compatibility issue the server side will check the API version and will reject any connection attempts that are coming from outdated APIs. Make sure that you pay attention to Asianodds notification emails. We will contact you immediately when there is new API version is available. Usually API updates don’t require changes in your code.

● DISABLED USER

- Contact Asianodds support.

7.2. OnEvent

The event is fired by the API to give you an insight of what it is doing. Usually through this channel you can see messages that are raised while the API is communicating with the server.

OnEvent(string eventMsg)

This is an information only channel that can be used to debug issues.

If you enable the built in logging messages fired on this channel will be automatically written to the main log file.

A simple example can be seen below

Event: Subscribe to Product list (1,0)...
Event: Sending Product list request (1,0)...
Event: MatchObject Received
Example 7 - Receiving Events

It is recommended but not mandatory to listen on this channel.

7.3. OnError

The event is fired when there was an issue in processing incoming messages from the server or if the server side raised an error while processing a request that was initiated by the API user. Sometimes the API itself also uses this channel to raise errors on an asynchronous way.

void OnError(int errorCode, string error);

Along with the error message the callback provides an errorCode as well which determines the error category (e.g.: network error, bet placement error, etc). Individual errors do not have unique error codes.

A simple example can be seen below

Event: Connection status changed. New state: Disconnected OnError[101]: No connection could be made because the target machine actively refused it 119.81.251.217:41131
Example 8 - OnError

See Exceptions and Errors chapter for more details

7.4. OnReceive

All data objects that are fired through dedicated event channels (e.g.: OnAccountSummaryChange) can be received here too in an XML or JSON format. The format can be preset with SetMessageFormat().

void OnReceive(string msgType, string message)

The event fires even if there is active registration on the dedicated event channel.

The example below shows the reception of an AccountSummary object:

OnReceive: AccountSummary {"Currency":"USD","Credit":852.0,"OpenBets":0,"Outstanding":0.0,"Pnl":- 269.51,"TodayPnl":0.0,"YesterdayPnl":0.0}
Example 9 - OnReceive

Objects that can be received on this channel

  • ● ACCOUNT SUMMARY
  • ● BETTICKET
  • ● MATCHOBJECT
  • ● TEAMNAME
  • ● LEAGUENAME
  • ● FULLODDSUPDATE
  • ● ODDSUPDATE
  • ● REMOVEGAME
  • ● ANNOUNCEMENT

See API Object section for more detailed information on these objects.

7.5. OnAccountSummaryChange

Event is fired after a successful login and every time when there is a change in available credit, open bets, etc.

OnAccountSummaryChange(AsianoddsAPIObjects.AccountSummary accSummary)

See API Object section for more detailed information on the structure of the received AccountSummary objects.

The XML example below shows an AccountSummary object:

[AccountSummary]
[Currency]USD[/Currency]
[GivenCredit]852[/GivenCredit]
[Commission]0[/Commission]
[AvailableCredit]656.51[/AvailableCredit]
[OpenBets]1[/OpenBets]
[Outstanding]-6.29[/Outstanding]
[Pnl]-189.20[/Pnl]
[TodayPnl]147.12[/TodayPnl]
[YesterdayPnl]28.30[/YesterdayPnl]
[/AccountSummary]

7.6. OnBetTicket (under constructon!)

--------

void OnBetTicket(AsianoddsAPIObjects.BetTicket betTicket)

See API Object section for more detailed information on the structure of the received objects.

The XML example below shows a BetTicket object:

[MatchResult]
[FTHomeScore]0[/FTHomeScore]
[FTAwayScore]0[/FTAwayScore]
[HTHomeScore]0[/HTHomeScore]
[HTAwayScore]0[/HTAwayScore]
[/MatchResult]
[MatchInfo]
[HomeName]AD Santa Rosa[/HomeName]
[AwayName]Deportivo Cartagena Guanacaste[/AwayName]
[LeagueName]COSTA RICA LIGA DE ASCENSO[/LeagueName]
[KickoffTime]2016-09-01T05:00:00[/KickoffTime]
[/MatchInfo]
[Odds]0.86[/Odds]
[Stake]6.29[/Stake]
[Pnl]0[/Pnl]
[BetId]13161278545[/BetId]
[Timestamp]2016-08-31T17:57:39[/Timestamp]
[Status]0[/Status]
[SourceId]IBC[/SourceId]
[GameType]H[/GameType]
[BetType]H[/BetType]
[Term]F[/Term]
[Currency]USD[/Currency]
[HDPorGoal]0.75[/HDPorGoal]
[UserId]Imre[/UserId]
[Favoured]2[/Favoured]
[HomeScore]0[/HomeScore]
[AwayScore]0[/AwayScore]
[OddsFormat]0[/OddsFormat]
[PnlInfo]
[Pnl]0[/Pnl]
[/PnlInfo]
[SportId]0[/SportId]
[/BetTicket]

7.7. OnMatchObject (under constructon!)

--------

void OnMatchObject(AsianoddsAPIObjects.MatchObject matchObject)

See API Object section for more detailed information on the structure of the received objects.

7.8. OnOddsData (under constructon!)

--------

void OnOddsData(AsianoddsAPIObjects.GameObject gameObject)

See API Object section for more detailed information on the structure of the received objects.

7.9. OnOddsRemove (under constructon!)

--------

void OnOddsRemove(AsianoddsAPIObjects.RemoveLine remLin)

See API Object section for more detailed information on the structure of the received objects.

7.10. OnAnnouncement (under constructon!)

--------

void OnAnnouncement(string announcement)

--------

8. Exceptions and Errors

9. API Objects

9.1. AccountSummary

Field Data Type Description
Currency string 3-letter code of the account currency. Such as “EUR”, “USD”
Credit decimal Currently available credit of the user. It is an all-inclusive amount (including base credit, outstanding and P&L)
Outstanding decimal The current outstanding amount that are in bets that are already placed but not yet settled
Pnl decimal Realized P&L number
TodayPnl decimal Today’s total P&L
YesterdayPnl decimal Yesterday’s P&L

9.2. BookieList

Field Data Type Description
Bookies BookieItem [] An array of BookieItem objects

9.3. BookieItem

Field Data Type Description
SourceId string SportsBook ID – usually a 2-3 letter code
Name decimal Full name of the sportsbook

9.4. NameList

Field Data Type Description
SportId int Sport ID
MarketId int Market (live, today, early) ID
List string [] Full name of the sprotsbook

9.5. SportList

Field Data Type Description
Sports SportItem [] An array of SportItem objects

9.6. SportItem

Field Data Type Description
Name string Sport name
SportId int Sport ID

9.7. Announcement

Field Data Type Description
AnnouncementText string Announcement message

9.8. MatchObject

Field Data Type Description
MatchId int Unique identifier of the match
HomeName string Home team name
AwayName string Away team name
LeagueName string League Name
SportId int Sport ID
MarketId int Market (live, today, early) ID
KickoffTime DateTime Yesterday’s P&L

9.9. MatchObjectList

Field Data Type Description
MarketId int Market (live, today, early) ID
SportId int Sport ID
MatchList MatchObject [] Collection of MatchObjects

9.10. GameObject

Field Data Type Description
Match MatchObject Match object holding basic information about the match
MatchDetails MatchDetailsObject Extra details of the match that becomes available after kickoff time
LineId long ID of the data line
HalfTime TermData Odds data for half time
FullTime TermData Odds data for full time
SubscriptionList string [] Subscription ID collection that satisfied this object

9.11. MatchDetailsObject

Field Data Type Description
InRunningTime int In running time of the match in minutes. First half starts at 60, second half at 120
HomeScore int Number of goals scored by home team
AwayScore int Number of goals scored by away team
HomeRedCardCount int Red cards collected by home team
AwayRedCardCount int Red cards collected by away team
Favoured int Favored team – 0: none, 1: home, 2: away

9.12. TermData

Field Data Type Description
DataLine_1x2 GameData1x2 Data line for 1x2 odds
DataLine_Handicap GameDataHandicap Data line for HDP odds
DataLine_OverUnder GameDataOverUnder Data line for Over-Under odds

9.13. GameData1x2

Field Data Type Description
Odds OddsData [] Collection of odds

9.14. GameDataHandicap

Field Data Type Description
Handicap string HDP value
Odds OddsData [] Collection of odds

9.15. GameDataOverUnder

Field Data Type Description
Goal string Goal value
Odds OddsData [] Collection of odds

9.16. OddsData

Field Data Type Description
HomeOdd double Home odd
AwayOdd double Away odd
DrawOdd double Draw odd – used only for 1x2
SourceId string SportsBook ID

9.17. OddsData

Field Data Type Description
MatchResult MacthResultObject Object holding information about the outcome of the match
MatchInfo MatchInfoObject Match details
Odds double Odd on the bet
Stake double Amount / Stake of the bet
PnL double Pnl of the bet (only once it is settled)
BetId string Asianodds ID of the bet
Timestamp DateTime Time of the bet placement
Status string Current status of the bet (see BetStatus enum for values)
SourceId string Current status of the bet (see BetStatus enum for values)
Status string ID of the sportsbook that took the bet
GameType string 1x2, OU or HDP (see GameType enum for values)
BetType string Type of the bet (see BetType enum for values)
Term string Half Time / Full time (see Term enum)
Message string Message from Asianodds (usually filled when bet rejected)
Currency string 3-letter currency code of the bet
HDPOrGoal string HDP or Goal values – empty for 1x2
UserId string User who placed the bet
Favoured int Tells which teams favoured (see Favoured enum for values)
HomeScore int Number of goals scored by home team
AwayScore int Number of goals scored by away team
OddsFormat int Format of the Odds (see OddType enum for values)
PnlInfo PnlObject P&L related information (only for settled bets)
SportId int Sport ID

9.18. PnlObject

Field Data Type Description
Pnl double Profit and loss value
PnlText string Result in a human readable format: won, lost, half won and half lost

9.19. MatchInfoObject

Field Data Type Description
HomeName string Name of the home team
AwayName string Name of the away team
LeagueName string Name of the league
KickoffTime DateTime Match start time

9.20. MatchInfoObject

Field Data Type Description
FTHomeScore string Number of goals scored by the home team
FTAwayScore string Number of goals scored by the away team
HTHomeScore string Half time home score
HTAwayScore string Half time away score

9.21. HistoryStatement

Field Data Type Description
Date string Statement date (MM/DD/YYYY)
Remark string Description of the statement line (e.g. opening balance, statement, etc.)
Turnover double Turnover
WinLoss double Profit and loss
Commission double Commission earned or paid
Balance double Closing balance of the day

10. Enumerables

The Enumerables shown below can help you with the development. Instead of numbers or chars, you can use meaningful names.

Due to compatibility issues with some programming languages API methods does not take enums values as parameter directly. They need to be casted to either int or char.

Still we encourage developers to use them whenever possible in order to produce code that is easier to read and understand.

For example:

api.GetTeamNames(1, (int)AsianoddsAPIObjects.Helper.MarketType.live);
Example 10 - Using enums

10.1. Enum: MarketType (int)

Constant Value it represents Description
live 0 Live (currently running) market
today 1 For matches played today
early 2 All other matches

10.2. Enum: MessageFormat (int)

Constant Value it represents Description
xml 0 XML (Extensible Markup Language)
json 1 JSON (JavaScript Object Notation)

10.3. Enum: OddType (int)

Constant Value it represents Description
malay 0 Malay format
hongKong 1 Hong Kong format
euro 2 Euro/Binary format

10.4. Enum: BetStatus (char)

Constant Value it represents Description
pending ‘0’ Pending at bookie
running ‘1’ Accepted and currently in running state
done ‘2’ Settled / Done state
done ‘2’ Settled / Done state
rejected ‘8’ Rejected
_void ‘V’ Void
unknown ‘U’ Unknown – contact support ASAP
sending ‘S’ Sending to bookie

10.5. Enum: GameType (char)

Constant Value it represents Description
_1x2 ‘X’ Classic 1x2
overUnder ‘O’ Over / Under
handicap ‘H’ Handicap

10.6. Enum: BetType (char)

Constant Value it represents Description
draw ‘X’ Draw (1x2)
over ‘O’ Over (over/under)
under ‘U’ Under (over/under)
home ‘H’ Home
away ‘A’ Away

10.7. Enum: Term (char)

Constant Value it represents Description
halfTime ‘H’ 1st half
fullTime ‘F’ Full time

10.8. Enum: Favoured (int)

Constant Value it represents Description
none 0 No favoured team
home 1 Home favoured
away 2 Away favoured

11. Examples

In this section you will find a few simple sample applications that demonstrate the usage of the API. In most of these demos there is no error handling to keep the code short and focus on the core API functionalities.

These sample applications can be found in the API installation directory as well. In there you will find further examples covering additional programming languages too.

The code samples in this document were written in .NET C#.

To run the demos you will need the following:

  • ● Asianodds API account for the Integration system
  • ● API has to be installed or required DLLs copied to your PC
  • ● Visual Studio (or without it you can do command-line building)
  • ● .NET 3.5 or higher
  • ● Internet connection

Please contact Asianodds support if you would like to see further demos covering features that were not demonstrated here.

11.1. Subscribing to odds updates – Demo01

In this example we are going to write a console application that subscribes to one match and display on screen the 1x2 odds offered by the different sportsbooks for this match.

The program takes two parameters: userId and password. There is no error handling (except for login error) in this code.

Here is the output of this console application:

First thing to do is create an instance of the API. Make the API object global so it can be reached from any methods.

In Main() subscribe to callbacks (events). What we need for this demo is the LoginStatusChange and OddsData events. Following the subscription call Init() on the API. The API will contact the server side and authenticate the user. After authentication it will call back to the code through the LoginStatusChange event. Here check if the API is connected (isLoggedIn). If it is, then get a list of available bookies (we will need this to display the grid). Also request a list of current live matches.

Pick the first match from the MatchObjectList and subscribe to it (using SubscribeMatch()). The server will immediately start streaming odds updates on the requested match. The odds updates are received with the OddsData callback.

When a callback is received first we need to check if the game line has 1x2 data (the match can have multiple game lines – we are interested only in the one that has 1x2 data). If it has then we can display it using the API’s built in render feature (DisplayGame_1x2). It is basically returning a multiline string that can directly be printed on the console without any further manipulation.

Let’s also display an update time so we know when the data was last refreshed. When the next update is received first we clear the screen and then display the odds again.

That’s it.

using System;
using AsianoddsAPIObjects;
using AsianoddsAPI;
class Demo01
{
static BookieList bookieList = new BookieList();
static void Main(string[] args)
{
//register for callback that is called when login status changes
api.OnLoginStatusChange += new LoginEventHandler(api_OnLoginStatusChange);
//register for odds data changes callback
api.OnOddsData += new OddsDataEventHandler(api_OnOddsData);
//Login
api.Init("119.81.251.217", 4111, args[0], api.CalculatePasswordHash(args[1]));
//Wait for console input (to avoid exit)
Console.ReadLine();
}
static void api_OnLoginStatusChange(bool isLoggedIn, string message)
{
if (!isLoggedIn)
{
//login failed. Let's show the reason and exit
Console.WriteLine("Login Error: " + message);
Environment.Exit(0);
}
else
{
//Get a list is available sportsbook
bookieList = api.GetBookieList(1);
//Get a list of live football games
MatchObjectList mList =
api.GetMatchList(1, (int)Helper.MarketType.live);
if (mList.MatchList.Count>0)
//subscribe to the 1st game in the list
api.SubscribeMatch(1, (int)Helper.MarketType.live, "subscr001",
"*", mList.MatchList[0].HomeName, mList.MatchList[0].AwayName);
else
{
Console.WriteLine("No live games found");
Environment.Exit(0);
}
}
}
static void api_OnOddsData(GameObject gameObject)
{
//check to see if this line of the game has 1x2
if (gameObject.FullTime.DataLine_1x2.Odds.Count > 0)
{
//if yes, clear the console
Console.Clear();
//Display the game using the API's built in display helper function
Console.WriteLine(Helper.DisplayGame_1x2(bookieList, gameObject));
//show last update time
Console.WriteLine("Last Update time: " + DateTime.Now.ToString("hh:mm:ss"));
}
}
}
Example 11 - Demo application (Demo01)