Top X operations
Let your users predict match outcomes and compete in a Top X game
Top X operations are responsible for communicating with the Prediction API in the context of a Top X game.
Games (a.k.a. Top X editions) are created by the staff members using their tokens in the Management Portal.
The following methods provide the functionality for end-users' interactions with the game.
Each method that works with statistical data also converts your IDs to the desired ID provider for easier and quicker development.
The namespace is of course called topX. All methods return promises. The general design of the namespace follows this pattern unless stated otherwise:
sdk.topX.someMethod(filtersObject).then((responseObject) => {
// do something with responseObject
});
Game related operations
The following methods are relating to the game instance.
Play the game
Method: *play({})
Submits the user's predictions for a specific game.
Options object:
- gameInstanceId: string. The game instance ID
- fixtures: array of objects. Contains a list of fixtures and predictions for each of the games in the game instance. Each object should contain:
- matchId: string. The ID of the match. It should exist in the game instance.
- prediction: Object. The prediction for this match
- value: String. Goals to be scored by each team separated by ":". Example: "2:3"
- tiebreaker: Object. Optional. The first minute the user thinks a goal will be scored across all matches.
- goldenGoal: Number. The number of the first goal prediction across all matches
N.B. The order of fixtures need to be the same as the order of the fixtures in the game
sdk.topX
.play({
gameInstanceId: 'ZLk',
fixtures: [
{
matchId: 'fb:m:425669548',
market: "CORRECT_SCORE",
prediction: {
value: '2:1',
},
},
{
matchId: 'fb:m:491738836',
market: "CORRECT_SCORE",
prediction: {
value: '1:2',
},
},
{
matchId: 'fb:m:547901653',
market: "CORRECT_SCORE",
prediction: {
value: '4:1',
},
},
{
matchId: 'fb:m:776046224',
market: "CORRECT_SCORE",
prediction: {
value: '1:1',
},
},
{
matchId: 'fb:m:203853114',
market: "CORRECT_SCORE",
prediction: {
value: '1:2',
},
},
{
matchId: 'fb:m:103467734',
market: "CORRECT_SCORE",
prediction: {
value: '3:1',
},
},
],
tiebreaker: {
goldenGoal: 11,
},
})
.then((responseObject) => {
// do something with responseObject
});
Example result
{
id: "GSGUDDW5xVNSo7I0ujVbsNBoeMz2_g_ZLk",
gameInstanceId: "ZLk",
gameType: "TOP_X",
wager: null,
totalFixtures: 6,
settledFixtures: 0,
userId: "GSGUDDW5xVNSo7I0ujVbsNBoeMz2",
fixtures: [
{
market: "CORRECT_SCORE",
matchId: "fb:m:103467734",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
prediction: {
value: "3:1",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:203853114",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:425669548",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:491738836",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
prediction: {
value: "1:2",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:547901653",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
prediction: {
value: "4:1",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:776046224",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
prediction: {
value: "1:1",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
}
],
status: "ACTIVE",
tiebreaker: {
goldenGoal: 11
},
points: 0,
createdAt: "2022-03-09T12:33:59Z",
updatedAt: "2022-03-09T12:33:59Z"
}
Delete game participation
Method: delete(gameInstanceId)
Deletes the user's participation (all game predictions) in a specific game.
sdk.topX.delete('GSGUDDW5xVNSo7I0ujVbsNBoeMz2_g_ZLk').then((responseObject) => {
// do something with responseObject
});
Example result
// returns 200 OK status code and boolean variable
Get games
Method: getGames(filters?, disableCache?)
Returns a list of Top X game instances, paginated.
If no value is passed to disableCache (undefined) it will be set to false.
Filters object:
- limit: number. The number of games to be returned.
- startAfter: string. The ID after which the games should be listed. To be used in the context of infinite scroll/pagination.
- status: string. Options include: "OPEN", "LIVE", "PENDING", "CANCELED", "CLOSED", "SETTLED"
- gameIds: array. An array of Game IDs
- sortOrder: string. Options are: desc and asc. Games will be returned sorted by predictions cutoff. So for example when asc value is provided the games will be sorted by earliest predictions cutoff time. By default is desc (latest predictions cutoff time).
sdk.topX.getGames({}).then((responseObject) => {
// do something with responseObject
});
Example result
{
meta: {
pagination: {
nextPageStartsAfter: "XgW",
itemsPerPage: 1
}
},
data: [
{
id: "XgW",
title: "Top 6 on Demo website",
description: "Guess the correct score of 6 matches. This game is with demo purposes only. No rewards will be available at the end.",
type: "TOP_X",
status: "OPEN",
predictionsCutoff: "2022-05-01T08:15:30Z",
scheduleOpenAt: "2022-05-01T07:00:30Z",
fixtures: [
{
matchId: "fb:m:103467734",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:203853114",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:425669548",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:491738836",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:547901653",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:776046224",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
}
],
participantsCount: 123,
rules: 'Rules for participating in the game.',
flags: ['This', 'is', 'string', 'array'],
images: null,
excludedProfileIds: ["profile-id-1", "profile-id-2"],
related: [
{
entityId: "game-id",
entityType: "game"
}
],
labels: {
label: "label"
},
customFields: {
custom: "fields"
},
createdAt: "2022-02-07T14:21:19Z",
updatedAt: "2022-02-15T04:29:03Z"
}
]
}
Get game by ID
Method: getGameById(gameId, disableCache?)
Returns a particular Match Quiz game instance.
If no value is passed to disableCache (undefined) it will be set to false.
sdk.topX.getGameById('game-instance-id').then((responseObject) => {
// do something with responseObject
});
Example result
{
id: "XgW",
title: "Top 6 on Demo website",
description: "Guess the correct score of 6 matches. This game is with demo purposes only. No rewards will be available at the end.",
type: "TOP_X",
status: "OPEN",
predictionsCutoff: "2022-05-01T08:15:30Z",
fixtures: [
{
matchId: "fb:m:103467734",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:203853114",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:425669548",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:491738836",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:547901653",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
},
{
matchId: "fb:m:776046224",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "notstarted",
subType: "not_started"
}
}
],
participantsCount: 31,
rules: 'Rules for participating in the game.',
flags: ['This', 'is', 'string', 'array'],
excludedProfileIds: ["profile-id-1", "profile-id-2"],
related: [
{
entityId: "game-id",
entityType: "game"
}
],
adContent: "<p>Ad content</p>",
labels: {
new: "new",
label_: "label_",
field3: "new label 3"
},
customFields: {
new: "new",
custom_: "custom_",
field3: "new custom field 3"
},
createdAt: "2022-02-07T14:21:19Z",
updatedAt: "2022-02-15T04:29:03Z"
}
Get game predictions
Method: getGamePredictions(gameId, filters?, disableCache?)
Returns predictions for particular Top X game.
If no value is passed to disableCache (undefined) it will be set to false.
Filters object:
- limit: number. The number of predictions to be returned.
- startAfter: string. The ID after which the predictions should be listed. To be used in the context of infinite scroll/pagination.
sdk.topX.getGamePredictions('game-instance-id').then((responseObject) => {
// do something with responseObject
});
Example result
{
meta: {
pagination: {
nextPageStartsAfter:
"ygLWDk3V7kYeC7drW9bzD6dMkWZ2_g_3jWDkLOHhKtWAakeEfjZ1A",
itemsPerPage: 20,
},
},
data: [
{
id: "ygLWDk3V7kYeC7drW9bzD6dMkWZ2_g_3jWDkLOHhKtWAakeEfjZ1A",
gameInstanceId: "3jWDkLOHhKtWAakeEfjZ1A",
gameType: "TOP_X",
wager: null,
totalFixtures: 1,
settledFixtures: 0,
userId: "ygLWDk3V7kYeC7drW9bzD6dMkWZ2",
fixtures: [
{
market: "CORRECT_SCORE",
matchId: "fb:m:842091979",
matchType: "FOOTBALL",
matchModel: MatchBasicModel,
prediction: {
value: "1:1",
playerId: null,
playerModel: null,
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
},
},
]
status: "ACTIVE",
tiebreaker: null,
points: 0,
createdAt: "2022-02-16T10:38:37Z",
updatedAt: "2022-02-16T10:38:37Z",
]
}
Get game results
Method: getGameResults(gameId, filters?, disableCache?)
Returns the leaderboard for a specific game. Has pagination.
If no value is passed to disableCache (undefined) it will be set to false.
Filters object:
- limit: number. The number of games to be returned.
- startAfter: string. The ID after which the results should be listed. To be used in the context of infinite scroll/pagination.
- status: string. Options include: "OPEN", "LIVE", "PENDING", "CANCELED", "CLOSED", "SETTLED"
sdk.topX.getGameResults('game-instance-id').then((responseObject) => {
// do something with responseObject
});
Example result
{
meta: {
pagination: {
nextPageStartsAfter: "user-id",
itemsPerPage: 20
}
},
data: [
{
userId: "user-id",
points: 10,
results: [
{
matchId: "matchId",
outcome: "outcome"
}
]
tiebreaker: {
goldenGoal: 30
}
]
}
Get markets results for specific game
Method: getMarketsResultsForGame(gameId, disableCache?)
Returns the market correct results for provided game id.
If no value is passed to disableCache (undefined) it will be set to false.
Example call
sdk.topX.getMarketsResultsForGame('game-id').then((responseObject) => {
// do something with responseObject
});
Example result
{
gameId: "game-id"
results: [
{
matchId: "1256453",
market: "CORRECT_SCORE",
result: "1:1",
matchModel: MatchBasicModel,
matchStatus: {
type: "finished",
subType: "finished
}
},
{
matchId: "32152513",
market: "CORRECT_SCORE",
result: "2:1",
matchModel: MatchBasicModel,
matchStatus: {
type: "finished",
subType: "finished
}
},
{
matchId: "6464323",
market: "CORRECT_SCORE",
result:"3:0",
matchModel: MatchBasicModel,
matchStatus: {
type: "finished",
subType: "finished
}
}
],
tieBreakers: {
goldenGoals: [
{
minute: 37,
matchId: "1256453",
matchModel: MatchBasicModel,
playerId: "3794",
playerModel: PlayerBasicModel,
goalType: "penalty_goal" // can be goal or own_goal
}
]
}
}
Get current game results
Method: getCurrentGameResults(disableCache?)
Alias of getGameResults but returns the active game results. Has pagination.
If no value is passed to disableCache (undefined) it will be set to false.
sdk.topX.getCurrentGameResults().then((responseObject) => {
// do something with responseObject
});
Example result
// See response for getGameResults(gameId)
Get game winners
Method: getGameWinners(gameId)
Method returns winners for the specific game.
sdk.topX.getGameWinners("gameId").then((responseObject) => {
// do something with responseObject
});
Example result
{
contestId: "gameId",
contestType: "GAME",
contestModel: GamesListModel
description: "description",
userList: [
{
position: "winner",
profileId: "profileId",
profileModel: ProfileModel,
note: "Winner note",
tags: [
"big_prizezzzzz",
"winner"
]
}
]
}
User related operations
The following methods are relating to the user and their interaction with the game instances.
Get user's own game participations
Method: getMyGameEditions(filters, disableCache?)
Returns a list of Top X editions I have participated in.
If no value is passed to disableCache (undefined) it will be set to false.
Filters object:
- limit: number. The number of games to be returned.
- startAfter: string. The ID after which the games should be listed. To be used in the context of infinite scroll/pagination.
- status: string. Options include: "OPEN", "LIVE", "PENDING", "CANCELED", "CLOSED", "SETTLED"
- gameIds: array. An array of Game IDs
sdk.topX.getMyGameEditions().then((responseObject) => {
// do something with responseObject
});
Example result
{
meta: {
pagination: {
nextPageStartsAfter: "prediction-id-example_g_4p4RFgstxvwUZAHnvf2TYZ,
itemsPerPage: 1
}
},
data: [
{
id: "4p4RFgstxvwUZAHnvf2TYZ",
title: "Example Title",
description: "Example description",
type: "TOP_X",
status: "SETTLED",
outcome: "LOST",
predictionsCutoff: "2022-08-08T18:45:00Z",
scheduleOpenAt: "2022-08-08T16:45:00Z",
fixtures: [
{
matchId: "fb:m:54797",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "finished",
subType: "finished"
},
prediction: {
value: "2:1",
result: {
settledAt: "2022-08-08T21:01:01Z",
resettledAt: null,
status: "SETTLED",
outcome: "INCORRECT",
points: 0
}
}
}
],
tiebreaker: {
timeTiebreaker: false
},
predictionId: "prediction-id-example",
participantsCount: 99,
rules: "Some custom rules",
flags: ["Some", "custom" "flags"],
excludedProfileIds: ["profile-id-1", "profile-id-2"],
related: [
{
entityId: "game-id",
entityType: "game"
}
],
points: 0,
predictionsMadeAt: "2022-08-08T17:27:43Z",
images: {
main: "https://bla.bla/bla.jpg",
cover: "https://bla.bla/bla.jpg",
mobile: "https://bla.bla/bla.jpg"
},
predictionTiebreaker: {
goldenGoal: 15
},
createdAt: "2022-08-08T15:47:26Z",
updatedAt: "2022-08-08T21:01:19Z"
}
]
}
Get user's own predictions for a game
Method: getMyGamePrediction(gameId)
Returns my own predictions for a specific Top X instance.
sdk.topX.getMyGamePrediction('game-instance-id').then((responseObject) => {
// do something with responseObject
});
Example result
{
id: "GSGUDDW5xVNSo7I0ujVbsNBoeMz2_g_ZLk",
gameInstanceId: "ZLk",
gameType: "TOP_X",
wager: null,
totalFixtures: 6,
settledFixtures: 0,
userId: "GSGUDDW5xVNSo7I0ujVbsNBoeMz2",
fixtures: [
{
market: "CORRECT_SCORE",
matchId: "fb:m:103467734",
matchType: "FOOTBALL",
matchModel: {},
prediction: {
value: "0:0",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:203853114",
matchType: "FOOTBALL",
matchModel: {},
prediction: {
value: "0:0",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:425669548",
matchType: "FOOTBALL",
matchModel: {},
prediction: {
value: "0:0",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:491738836",
matchType: "FOOTBALL",
matchModel: {},
prediction: {
value: "0:0",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:547901653",
matchType: "FOOTBALL",
matchModel: {},
prediction: {
value: "0:0",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
},
{
market: "CORRECT_SCORE",
matchId: "fb:m:776046224",
matchType: "FOOTBALL",
matchModel: {},
prediction: {
value: "0:0",
playerId: null,
playerModel: null
},
result: {
settledAt: null,
resettledAt: null,
status: "NOT_SETTLED",
outcome: "NOT_VERIFIED",
points: 0
}
}
],
status: "ACTIVE",
tiebreaker: {
goldenGoal: 0
},
points: 0,
createdAt: "2022-03-09T13:47:09Z",
updatedAt: "2022-03-09T13:47:09Z"
}
Get user's game prediction
Method: getUserGamePrediction(userId, gameId, disableCache?)
Returns user’s predictions for a specific Top X instance.
If no value is passed to disableCache (undefined) it will be set to false.
sdk.topX.getUserGamePrediction('user-id', 'game-instance-id').then((responseObject) => {
// do something with responseObject
});
Example result
// See result for getMyGamePrediction(gameId)
Get user's game participations
Method: getUserGameEditions(userId, disableCache?)
Returns the edition the user has participated in.
If no value is passed to disableCache (undefined) it will be set to false.
sdk.topX.getUserGameEditions('user-id').then((responseObject) => {
// do something with responseObject
});
Example result
{
meta: {
pagination: {
nextPageStartsAfter: "prediction-id-example_g_4p4RFgstxvwUZAHnvf2TYZ",
itemsPerPage: 1
}
},
data: [
{
id: "4p4RFgstxvwUZAHnvf2TYZ",
title: "Title Example",
description: "Description Example",
type: "TOP_X",
status: "SETTLED",
outcome: "WON",
predictionsCutoff: "2022-08-08T18:45:00Z",
fixtures: [
{
matchId: "fb:m:54797",
matchType: "FOOTBALL",
market: "CORRECT_SCORE",
matchModel: MatchBasicModel,
matchStatus: {
type: "finished",
subType: "finished"
},
prediction: {
value: "2:1",
result: {
settledAt: "2022-08-08T21:01:01Z",
resettledAt: null,
status: "SETTLED",
outcome: "CORRECT",
points: 50
}
}
}
],
tiebreaker: {
timeTiebreaker: false
},
predictionId: "prediction-id-example",
participantsCount: 883,
rules: "Some custom rules",
flags: ["Some", "custom", "flags"],
excludedProfileIds: ["profile-id-1", "profile-id-2"],
related: [
{
entityId: "game-id",
entityType: "game"
}
],
images: {
main: "https://bla.bla/bla.jpg",
cover: "https://bla.bla/bla.jpg",
mobile: "https://bla.bla/bla.jpg"
},
predictionTiebreaker: {
goldenGoal: 10
},
points: 50,
createdAt: "2022-08-08T15:47:26Z",
updatedAt: "2022-08-08T21:01:19Z",
predictionsMadeAt: "2022-08-08T16:13:57Z"
}
]
}
Other operations
Get config
Method: getConfig()
Returns the configuration for the Top X feature. Top X games can be created only with matches who are part of competitions who are listed in competitionsWhitelist.
The config will be cached in LocalStorage for 4 hours.
sdk.topX.getConfig().then((responseObject) => {
// do something with responseObject
});
Example result
{
enabled: true,
minFixtures: 1,
maxFixtures: 6,
competitionsWhitelist: [
"fb:c:1",
"fb:c:3",
"fb:c:4",
"fb:c:5",
"fb:c:6",
"fb:c:7",
"fb:c:8",
"fb:c:9",
"fb:c:11",
"fb:c:12",
"fb:c:13",
"fb:c:14",
"fb:c:15",
"fb:c:16",
"fb:c:17",
"fb:c:18",
"fb:c:19",
"fb:c:20",
"fb:c:21",
"fb:c:22",
"fb:c:27",
"fb:c:28",
"fb:c:30",
"fb:c:34",
"fb:c:37",
"fb:c:119"
]
}
Updated 9 months ago