Blackbox API Documentation

Release 1.2.2

Algosport

Aug 28, 2018

 CONTENTS:

1 Introduction 1

2 Core API Types 3

2.1 Contest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2.1 Definition and parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.2 Parameter derivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Settlement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4 Bets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4.1 Understanding the correlation factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 Sports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1 Football . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1.1 Participants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1.2 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1.3 State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1.4 Market Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.6 API Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.7 API Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.7.1 API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.7.1.1 InvalidSTLSelections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.7.1.2 CompilationErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.7.1.3 DerivationError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.7.1.4 PricingErrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 API 15
3.1 Bet builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1.2 Example request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Bet editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.2 Example request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.3 Templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3.2 Example request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4 Test environment 25

Index 27

i
ii
 CHAPTER

ONE

INTRODUCTION

The Blackbox API builds on Algosport’s core modelling and pricing technology to enable bookmakers to access
1. On-demand pricing and market creation
Expand your market offering with new markets through our templating API.
2. Bet builder
Enable your customers to place multiples on related contingencies within the same sporting contest.
3. Cash-out
Cash out singles or related contingency bets.
4. Bet editor
Allow customers to add, remove or replace selections within their related contingency bet.
5. Custom feature
Create your own product! With access to Algosport’s modelling and selection building technology it’s
never been easier to test and bring new products to market.

1
Blackbox API Documentation, Release 1.2.2

2 Chapter 1. Introduction
 CHAPTER

TWO

CORE API TYPES

2.1 Contest

Contains all the relevant sporting information about a contest. The properties on the contest object are consistent
across sports but the structure of the values they contain is sport dependent. e.g. The state/scoreboard for a tennis
contest will differ from that of a football contest.
Contest
Contest information.
Object Properties
• participants – Particpants in the contest - teams and/or players.
• format – The format of the contest - how many sets, will there be penalties, bonus point
rules etc.
• state – The current state of the contest - current time, score and incidents if in-play.
Contest participants can be split by whether or not a contest is team or player based.
Teams
Participants in a contest between two teams of players.
Object Properties
• 1 (TeamInfo) – The home team.
• 2 (TeamInfo) – The away team.
Players
Participants in a contest between two players.
Object Properties
• 1 (PlayerInfo) – Player 1.
• 2 (PlayerInfo) – Player 2.
TeamInfo
Information about a team and its players.
Object Properties
• name (string) – Optional Name of the team. Used by templating engine when creating
markets and selections. Not required for bet builder or editor.
• players – Mapping between a unique string identifier for a player and PlayerInfo.
The identifier is required for player markets.

3
Blackbox API Documentation, Release 1.2.2

For example, take Danny Welbeck from Example football match participants. He has a
unique identifier of '1234' and so the STL selection for him to score a hat-trick would be
encoded as

total(<RT, goals[player='1234']>) >= 3

PlayerInfo
Information about an individual player.
Object Properties
• name (string) – Optional player name.

Listing 2.1: Example football match participants

{ "participants":
{ "1":
{ "name": "Arsenal"
, "players":
{ "1234": { "name": "Danny Welbeck" }
, "3456": { "name": "Henrikh Mkhitaryan" }
}
}
, "2":
{ "name": "AC Milan"
, "players":
{ "4321": { "name": "Nikola Kalinic" }
, "6543": { "name": "Fabio Borini" }
}
}
}

Listing 2.2: Tennis match example

{ "participants":
{ "1": { "name": "Roger Federer" }
, "2": { "name": "Rafael Nadal" }
}
}

2.2 Model

Contains a description of the underlying model being used for pricing.

Model
Object Properties
• defaultParameters (ModelParameters) – Default parameters / structure of the
model.
• currentParameters (ModelParameters) – How is the model currently set up to
run.
• derivationRequest (DerivationRequest) – Current contest markets and state
that are to be used to update the model parameters.

4 Chapter 2. Core API Types

 Blackbox API Documentation, Release 1.2.2

2.2.1 Definition and parameters

ModelParameters

Todo: Document model parameters. Currently defaulted to the base football model.

2.2.2 Parameter derivation

A derivation request calculates the underlying parameters of a model that best align with a given set of driving markets
given the current state of the contest.
DerivationRequest
Object Properties
• markets – What markets are being used to drive derivation.
The structure of markets is sport dependent because the sample - contest interval and incident type - a market works
over is sport dependent, e.g. first half goals, sets in match, centuries in the next frame. However, the structure of an
individual market over that sample - i.e. its selections and prices - is consistent across sports.

Listing 2.3: Example football markets for goals, corners and cards
{ "goals":
{ "RT":
{ "asianHandicaps":
{ "0.5": { "1": 1.95, "2": 1.9 } }
, "asianTotals":
{ "2.25": { "U": 1.9, "O": 1.95 } }
}
, "H1":
{ "europeanHandicaps":
{ "0": { "1": 4.5, "X": 2.05, "2": 2.62 } }
}
}
, "corners":
{ "RT":
{ "europeanTotals":
{ "11": { "U": 2.0, "X": 8.5, "2": 2.0 } }
}
}
, "cards":
{ "RT":
{ "asianTotals":
{ "4.0": { "1": 1.95, "2": 1.85 } }
}
}
}

For a given contest interval and incident type there are a number of markets that we can take account of whilst do a
derivation
1. Asian handicap
Which player or team - with a given handicap - will record the most incidents within the time frame. This is a
2-way market that may contain partial or full voids. e.g. Draw no bet in football will be void if the match ends

2.2. Model 5
Blackbox API Documentation, Release 1.2.2

in a draw.
2. Asian totals
Will the total number of incidents be over or under some value. This is a 2-way market that may be partially or
fully voided dependent on the line and result. e.g. Over/Under 8 games in set 1 of a tennis match will be voided
if there are exactly 8 games in that set, for instance if the set score was 6-2.
3. European handicap
Which player or team - with a given integer valued handicap - will record the most incidents within the time
frame. This is a 3-way where draws are permissible.
4. European totals
Will there be under, exactly or over some integer valued number of incidents within the time frame.
5. Nth player
Which player will trigger the nth incident of a given type. e.g. Last player to score or first player to receive a
yellow card. Positive market indexes track the incidents forwards in time so 𝑛 = 2 refers to the 2nd incident.
Negative indexes work backwards in time so that 𝑛 = −1 refers to the last incident.
StatisticMarkets
Object Properties
• asianHandicaps – Optional. Asian handicap markets which are a mapping from a nu-
meric handicap - the first team or players handicap - to AsianHandicapSelections.
• asianTotals – Optional. Asian total markets which are a mapping from a numeric - the
over/under line - to AsianTotalSelections.
• europeanHandicaps – Optional. European handicap markets which are a
mapping from an integral handicap - the first team or players handicap - to
EuropeanHandicapSelections.
• europeanTotals – Optional. European total markets which are a mapping from an
integral handicap - the over/under line - to EuropeanTotalSelections.
• nthPlayers – Optional. Nth player markets are a mapping from an integer - which
incident the market refers to - to NthPlayerSelections.

Listing 2.4: Example of statistic markets

{ "asianHandicaps":
{ "-0.5": { "1": 1.875, "2": 1.975 }
, "0.0": { "1": 1.425, "2": 2.750 }
}
, "asianTotals":
{ "2.75": { "U": 1.925, "O": 1.925 }
, "2.5": { "U": 2.1, "2": 1.7 }
}
, "europeanHandicaps":
{ "0": { "1": 1.85, "X": 4.0, "2": 4.2 }
}
, "nthPlayers":
{ "1":
{ "1234": 6.5
, "3456": 7.5
, "4321": 8.5
, "6543": 13.0
}

6 Chapter 2. Core API Types

 Blackbox API Documentation, Release 1.2.2

}
}

AsianHandicapSelections
Object Properties
• 1 (number) – The odds of the first player or team.
• 2 (number) – The odds of the second player or team.
AsianTotalSelections
Object Properties
• U (number) – The odds of the under selection.
• O (number) – The odds of the over selection.
EuropeanHandicapSelections
Object Properties
• 1 (number) – The odds of the first player or team.
• X (number) – The odds of the draw.
• 2 (number) – The odds of the second player or team.
EuropeanTotalSelections
Object Properties
• U (number) – The odds of the under selection.
• X (number) – The odds of the exact total selection.
• O (number) – The odds of the over selection.

2.3 Settlement

The settlement type is used for pricing and resulting selections. A settlement value contains two parts
1. Winning proportion, 𝑤 ∈ [0, 1]
2. Voiding proportion, 𝑣 ∈ [0, 1]
such that 𝑤 + 𝑣 ≤ 1 and is represented as
Settlement
Object Properties
• winning (number) – Winning proportion of selection.
• voiding (number) – Voiding proportion of selection.
Settlements are used in two contexts
1. Bet settlement. If a bet has been placed with stake 𝑠 at odds 𝑜 then the customer will be returned a total of
𝑤𝑠𝑜 + 𝑣𝑠. e.g. A stake of 2 at odds of 4 with a settlement of

{ "winning": 0.25, "voiding": 0.5 }

will return the customer 2 × 4 × 0.25 + 2 × 0.5 = 3.

2.3. Settlement 7
Blackbox API Documentation, Release 1.2.2

2. Pricing. When pricing a selection we will return the expected settlement of the selection which may be turned
into odds via the transformation
1−𝑣
odds(𝑤, 𝑣) =
𝑤
For example, a selection priced with an expected settlement of

{ "winning": 0.2, "voiding": 0.4 }

will have 100% odds of (1 − 0.4)/0.2 = 3.0.

2.4 Bets

The API allows for the building and editing of related contingency bets.
BetDefinition
Object Properties
• selections – List of Selection containing the pricing information for each selection
in the bet.
Selection
Object Properties
• definition (text) – The settlement rules as expressed in STL.
• odds (number) – The odds a customer would get if placing a single on that selection.
Priced related contigency bets are expressed as below.
PricedBet
Object Properties
• selections – List of PricedSelection containing the pricing information for each
selection in the bet.
• expectation (Settlement) – The expected settlement of the combined bet.
• calculatedPrice (CalculatedPrice) – The calculated price for the bet based on
a combination of the provided odds for each selection and the algorithm calculated price.
PricedSelection
Object Properties
• expectation (Settlement) – The expected returns for a selection.
CalculatedPrice
The calculated price for a selection based on the 100% price obtained via the model and the provided margined
odds. The details of the calculation can be found in Understanding the correlation factor.
Object Properties
• odds (number) – The calculated odds for the selection.
• correlationFactor (number) –

8 Chapter 2. Core API Types

 Blackbox API Documentation, Release 1.2.2

2.4.1 Understanding the correlation factor

The correlation factor is used to help bookmakers provide odds for the combined bet whilst accounting for the over-
round on their own markets.
For instance if bookmaker 1 is offering
• Both teams to score at 1.95
• Corners match bet at 2.9
in one territory but
• Both teams to score at 1.8
• Corners match bet at 2.8
in another then you would expect them to offer a combined bet with a higher overround for the 2nd territory reflecting
the higher overround on their individual markets.
Image the bet builder request returned
• Both teams to score { "winning": 0.5, "voiding": 0.0 }
• Corners match bet { "winning": 0.333, "voiding": 0.0 }
• Combined bet { "winning": 0.25, "voiding": 0.0 }
The correlation factor, 𝑔𝑎𝑚𝑚𝑎, is calculated so that the bookmaker can offer odds for the combined bet with the same
relative odds that the Algosport model has derived. It is defined as

𝛾
(𝑠1 × 𝑠2 × · · · × 𝑠𝑛 ) = 𝑐

where 𝑠𝑖 are the 100% odds of the single selections and c is the 100% odds of the combined bet. For the example
above we would have
• 𝑠1 = 2.0
• 𝑠2 = 3.0
• 𝑐 = 4.0
and so 𝛾 ≈ 0.774. The bookmaker could therefore offer odds in territory 1 of

0.774
(1.95 * 2.9) = 3.82

and in territory 2 of

0.774
(1.8 * 2.8) = 3.49

lining up with the requirement for higher margin to be offered in territory 2.

Note: The correlation factor is only a guide to what the bookmakers odds should be based on their selection prices.
More or less margin can be easily applied by either adjusting the value of the correlation factor or using an in house
margining method.

2.4. Bets 9
Blackbox API Documentation, Release 1.2.2

2.5 Sports

2.5.1 Football

{ "participants":
{ "1":
{ "name": "Arsenal"
, "players":
{ "1234": { "name": "Danny Welbeck" }
, "3456": { "name": "Henrikh Mkhitaryan" }
}
}
, "2":
{ "name": "AC Milan"
, "players":
{ "4321": { "name": "Nikola Kalinic" }
, "6543": { "name": "Fabio Borini" }
}
}
}
}

2.5.1.1 Participants

Participants in football are described using Teams.

2.5.1.2 Format

Todo: This currently defaults to a 90 minute match.

2.5.1.3 State

Todo: This currently defaults to pre-match.

2.5.1.4 Market Statistics

Market statistics are required to describe the input markets for derivation. Football currently supports
1. Time windows
• RT - regulation time (usually 90 minutes unless match length otherwise specified in the format)
• H1 - first half of regulation time.
• H2 - second half of regulation time.
2. Incidents
• goals

10 Chapter 2. Core API Types

 Blackbox API Documentation, Release 1.2.2

• corners
• cards

2.6 API Requests

Request
API requests contain an optional metadata section and the request body itself.
Object Properties
• metadata (RequestMetadata) – Metadata associated with the request. Used for log-
ging and tracking of requests.
• request (object) – The request body itself determined by the type of request being
made.
RequestMetadata
To aid tracking requests, metadata in the form of a correlation id may be sent with each request.
Object Properties
• correlationId (string) – A user defined string relating to the request in some way.

2.7 API Responses

The API responses

Response
Object Properties
• metadata (ResponseMetdata) – Metadata about the request.
• status (string) – Indicates whether the request succeeded. Returns OK if it did or
Error otherwise.
• response – If the request was succesful contains data of the appropriate type for the API
call. If an error was encountered it will contain an APIError.
ResponseMetdata
Object Properties
• requestMetadata (object) – The metadata that was sent with the request.
• requestId (string) – Internally generated request id.
APIError
How errors are reported in the API. See API Errors for a complete list of error types and what information they
contain.
Object Properties
• type (string) – What type of error was encounted.
• details – Optional field containg more detailed information about the cause of the error.

2.6. API Requests 11

Blackbox API Documentation, Release 1.2.2

Warning: This information provided by this field is likely to change in the future and
shouldn’t currently be relied on for implementing business logic.

SelectionError
Wraps error details, e.g. parse errors, for a particular selection with the STL used to define that selection.

Listing 2.5: Selection with a parse error

{ "selection": "total(<RT, goals>) == 0"
, "error":
{ "type": "ParseError"
, "details": "1:31:\nunexpected \"= 0\"\nexpecting result\n",
}
}

Object Properties
• selection (string) – The STL that was used to define the selection.
• error – The associated error details.

2.7.1 API Errors

Below are the list of error types that may be returned in an APIError along with the associated types for describing
the error.

2.7.1.1 InvalidSTLSelections

A list of SelectionError wrapped STLError. Generated when selections being ill-defined in STL.
STLError
Object Properties
• type (string) – One of
– ParseError: the STL was ill-formed.
– TypeError: the STL was ill-typed. e.g. multiplying strings and integers or refering to
goals in a rugby contest
• details – Further information about the error.
• location – Optional information indicating where in the STL the error occured. trig-
gered.

2.7.1.2 CompilationErrors

A list of SelectionError wrapped compilation errors which are rendered as strings. Generated when the STL
selection can’t be implemented by the underlying model.

2.7.1.3 DerivationError

There was a problem deriving the underlying parameters for the model.

12 Chapter 2. Core API Types

 Blackbox API Documentation, Release 1.2.2

2.7.1.4 PricingErrors

A list of SelectionError wrapped pricing errors which are rendered as strings. Generated when the STL selection
can’t be priced by the underlying model. e.g. too many player based selections included in an accumulator.

2.7. API Responses 13

Blackbox API Documentation, Release 1.2.2

14 Chapter 2. Core API Types

 CHAPTER

THREE

API

3.1 Bet builder

3.1.1 Overview

The bet builder operation allows the creation of a single bet from a set of related contingency bets. Traditionally if you
entered selections such as
• Home to win
• Away team most corners
in to the betslip you would have only been given the option to place singles on the two outcomes. The bet builder API
enables these selections to be combined using Algosport’s core modelling and pricing technology.

3.1.2 Example request

POST /v1/api/betBuilder/
Example request:

POST /blackbox/v1/api/betBuilder/ HTTP/1.1

Host: test.algosport.co.uk
Accept: application/json

{ "metadata": { "correlationId": "123-123134-asgkj2" }

, "request":
{ "contest":
{ "participants":
{ "1":
{ "name": "Liverpool"
, "players":
{ "1234": { "name": "Salah" }
, "5678": { "name": "Firminho" }
}
}
, "2": { "name": "Manchester City"}
}
}
, "model":
{ "derivationRequest":
{ "markets":
{ "cards":
{ "RT":

15
Blackbox API Documentation, Release 1.2.2

{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
}
}
, "corners":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
}
}
, "goals":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
, "nthPlayers":
{ "1":
{ "1234": 5.5
, "5678": 7
}
}
}
, "*":
{ "methodOfVictory":
{ "ET": { "1": 4.5, "2": 5.5 }
, "PS": { "1": 7, "2": 8 }
}
}
}
}
}
}
, "bet":
{ "selections":
[ {"definition": "asian(total(<RT, goals>)) > 2.5", "odds": 1.9}
, {"definition": "supremacy(<RT, goals>) >= 0", "odds": 1.25}
]
}
}
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "OK"
, "response":
{ "bet":
{ "selections":
[ { "expectation":
{ "voiding": 0
, "winning": 0.500014716036126

16 Chapter 3. API
 Blackbox API Documentation, Release 1.2.2

}
}
, { "expectation":
{ "voiding": 0
, "winning": 0.7503362018705245
}
}
]
, "expectation":
{ "voiding": 0
, "winning": 0.36248822665393243
}
, "calculatedPrice":
{ "odds": 2.393675544289017
, "correlationFactor": 1.03510131355745
}
}
}
, "metadata":
{ "requestMetadata": { "correlationId": "123-123134-asgkj2" }
, "requestId": "b8a765b7-6402-448b-9ecc-e4bb34d1cd9d"
}
}

Status Codes
• 200 OK – Expected response - API errors are reported in body of the response.

BetBuilderRequest
Object Properties
• contest (Contest) – Contest information.
• model (Model) – Model and derivation information
• bet – BetDefinition
The bet that we wish to be calculated.
BetBuilderResponse
The type of data returned on a succesful call to the API. (See Response).
Object Properties
• bet (PricedBet) – Information about individual selection and combined prices.

3.2 Bet editor

3.2.1 Overview

The bet editor operation allows the editing of a previously created related contingency bet. For instance, if you had a
bet on
• Home to win
• Away team most corners
you could edit it by either removing selections to give

3.2. Bet editor 17

Blackbox API Documentation, Release 1.2.2

• Home to win
or by adding selections to give
• Home to win
• Away team most corners
• Harry Kane to score last
or a combination of both
• Home to win
• Harry Kane to score last
This allows customers to have full control of the lifetime of their bet from creation to settlement.

Note: Cash out is achieved through this operation by removing all selections from the bet.

3.2.2 Example request

POST /v1/api/betEditor/
Example request:

POST /blackbox/v1/api/betEditor/ HTTP/1.1

Host: test.algosport.co.uk
Accept: application/json

{ "metadata": { "correlationId": "123-123134-asgkj2" }

, "request":
{ "contest":
{ "participants":
{ "1":
{ "name": "Liverpool"
, "players":
{ "1234": { "name": "Salah" }
, "5678": { "name": "Firminho" }
}
}
, "2": { "name": "Manchester City"}
}
}
, "model":
{ "derivationRequest":
{ "markets":
{ "cards":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
}
}
, "corners":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }

18 Chapter 3. API
 Blackbox API Documentation, Release 1.2.2

, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
}
}
, "goals":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
, "nthPlayers":
{ "1":
{ "1234": 5.5
, "5678": 7
}
}
}
, "*":
{ "methodOfVictory":
{ "ET": { "1": 4.5, "2": 5.5 }
, "PS": { "1": 7, "2": 8 }
}
}
}
}
}
}
, "currentBet":
{ "selections":
[ {"definition": "asian(total(<RT, goals>)) > 2.5", "odds": 1.9}
, {"definition": "supremacy(<RT, goals>) >= 0", "odds": 1.25}
]
}
, "newBet":
{ "selections":
[ {"definition": "asian(total(<RT, goals>)) > 2.5", "odds": 1.9}
]
}
}
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "OK"
, "response":
{ "currentBet":
{ "selections":
[ { "expectation":
{ "voiding": 0
, "winning": 0.500014716036126
}
}
, { "expectation":
{ "voiding": 0
, "winning": 0.7503362018705245

3.2. Bet editor 19

Blackbox API Documentation, Release 1.2.2

}
}
]
, "expectation":
{ "voiding": 0
, "winning": 0.36248822665393243
}
}
, "newBet":
{ "selections":
[ { "expectation":
{ "voiding": 0
, "winning": 0.500014716036126
}
}
]
, "expectation":
{ "voiding": 0
, "winning": 0.500014716036126
}
}
}
, "metadata":
{ "requestMetadata": { "correlationId": "123-123134-asgkj2" }
, "requestId": "b8a765b7-6402-448b-9ecc-e4bb34d1cd9d"
}
}

Status Codes
• 200 OK – Expected response - API errors are reported in body of the response.

BetEditorRequest
Object Properties
• contest (Contest) – Contest information.
• model (Model) – Model and derivation information
• currentBet – BetDefinition
The current bet the customer has already placed.
• newBet – BetDefinition
The new bet the customer would like to have in place of their current bet.
BetEditorResponse
The type of data returned on a succesful call to the API. (See Response).
Object Properties
• currentBet (PricedBet) – Information about individual selection and combined
prices.
• newBet (PricedBet) – Information about individual selection and combined prices.

20 Chapter 3. API
 Blackbox API Documentation, Release 1.2.2

3.3 Templating

3.3.1 Overview

The templating API allows the creation of complete markets to be used in conjunction within your current offering.
Aligning Algosport’s model to you current market prices allows you to create and offer new, consistent and competitive
markets on the fly.

3.3.2 Example request

POST /v1/api/templating/
Example request:
POST /blackbox/v1/api/templating/ HTTP/1.1
Host: test.algosport.co.uk
Accept: application/json

{ "metadata": { "correlationId": "123-123134-asgkj2" }

, "request":
{ "contest":
{ "participants":
{ "1":
{ "name": "Liverpool"
, "players":
{ "1234": { "name": "Salah" }
, "5678": { "name": "Firminho" }
}
}
, "2": { "name": "Manchester City"}
}
}
, "model":
{ "derivationRequest":
{ "markets":
{ "cards":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
}
}
, "corners":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }
}
}
, "goals":
{ "RT":
{ "asianHandicaps":
{ "-0.50": { "1": 1.95, "2": 1.95 } }
, "asianTotals":
{ "2.50": { "U": 1.95, "O": 1.95 } }

3.3. Templating 21
Blackbox API Documentation, Release 1.2.2

, "nthPlayers":
{ "1":
{ "1234": 5.5
, "5678": 7
}
}
}
, "*":
{ "methodOfVictory":
{ "ET": { "1": 4.5, "2": 5.5 }
, "PS": { "1": 7, "2": 8 }
}
}
}
}
}
}
, "templates":
{ "highestScoringHalfTeam":
{ "name": "Team with highest scoring half"
, "selections":
{ "1":
{ "name": "%(vs1.name)"
, "definition":
"max([total(<H1,goals[team=home]>), total(<H2,goals[team=home]>)]) >
˓→ max([total(<H1,goals[team=away]>), total(<H2,goals[team=away]>)])"

}
}
, "X":
{ "name": "Neither"
, "definition":
"max([total(<H1,goals[team=home]>), total(<H2,goals[team=home]>)])
˓→= max([total(<H1,goals[team=away]>), total(<H2,goals[team=away]>)])"

}
, "2":
{ "name": "%(vs2.name)"
, "definition":
"max([total(<H1,goals[team=home]>), total(<H2,goals[team=home]>)])
˓→< max([total(<H1,goals[team=away]>), total(<H2,goals[team=away]>)])"

}
}
}
}
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "OK"
, "response":
{ "templates":
{ "highestScoringHalfTeam":
{ "name": "Team with highest scoring half"
, "selections":
{ "1":
{ "name": "Liverpool"

22 Chapter 3. API
 Blackbox API Documentation, Release 1.2.2

, "expectation":
{ "voiding": 0
, "winning": 0.25
}
}
, "X":
{ "name": "Neither"
, "expectation":
{ "voiding": 0
, "winning": 0.5
}
}
, "2":
{ "name": "Man City"
, "expectation":
{ "voiding": 0
, "winning": 0.25
}
}
}
}
}
}
, "metadata":
{ "requestMetadata": { "correlationId": "123-123134-asgkj2" }
, "requestId": "b8a765b7-6402-448b-9ecc-e4bb34d1cd9d"
}
}

Status Codes
• 200 OK – Expected response - API errors are reported in body of the response.

TemplateRequest
Object Properties
• templates – Mapping from a unique string identifier for a template and
MarketTemplate.
MarketTemplate
Object Properties
• selections – Mapping from a unique string identifier for a selection template and
SelectionTemplate.
SelectionTemplate
Object Properties
• definition (string) – The STL definition for the selection.
TemplateResponse
The type of data returned on a succesful call to the API. (See Response).
Object Properties
• templates – Mapping from the unique string identifier for the market template to
GeneratedMarket.
GeneratedMarket

3.3. Templating 23
Blackbox API Documentation, Release 1.2.2

Object Properties
• selections – Mapping from the unique string identifier for a selection template to
GeneratedSelection.
GeneratedSelection
Object Properties
• expectation (Settlement) – The expected settlement of the generated selection.

24 Chapter 3. API
 CHAPTER

FOUR

TEST ENVIRONMENT

Our test environment allows you to develop your application without requiring to deploy it. The API is based at
http://test.algosport.co.uk/blackbox, so calls to the Bet builder endpoint should be directed at http://test.algosport.co.
uk/blackbox/v1/betBuilder.
All requests to the test environment will need to be authenticated. This is done via the addition of a single
Authorization header with a token that will be supplied to you.
POST /blackbox/v1/api-endpoint
Example request:

POST /blackbox/v1/api-endpoint HTTP/1.1

Host: test.algosport.co.uk
Authorization: Basic EXAMPLETOKEN

...

Request Headers
• Authorization – Required authorization method and token.
Status Codes
• 403 Forbidden – Authorization has failed. Token may have expired or request may be ill-
formatted.

25
Blackbox API Documentation, Release 1.2.2

26 Chapter 4. Test environment

 INDEX

J
JSON Objects
APIError, 11
AsianHandicapSelections, 7
AsianTotalSelections, 7
BetBuilderRequest, 17
BetBuilderResponse, 17
BetDefinition, 8
BetEditorRequest, 20
BetEditorResponse, 20
CalculatedPrice, 8
DerivationRequest, 5
EuropeanHandicapSelections, 7
EuropeanTotalSelections, 7
GeneratedMarket, 23
GeneratedSelection, 24
MarketTemplate, 23
ModelParameters, 5
PlayerInfo, 4
Players, 3
PricedBet, 8
PricedSelection, 8
Request, 11
RequestMetadata, 11
Response, 11
ResponseMetdata, 11
Selection, 8
SelectionError, 12
SelectionTemplate, 23
StatisticMarkets, 6
STLError, 12
TeamInfo, 3
Teams, 3
TemplateRequest, 23
TemplateResponse, 23

27