Download OpenAPI specification

 
API ENUMERATIONS


Team Type

Categorizes teams.

IdentifierNameDescription
CClub teamRepresents a city. Competes in domestic competitions. In addition the best teams compete in international competitions.
NNational teamRepresents a whole country. Exclusively competes in international competitions.


Competition Mode

Categorizes competitions by the way teams compete against each other and how results are valued.

IdentifierNameDescription
LLeagueTeams compete in a league or group against (all) other participants. They earn points for wins and draws. The teams with the most points in the end are promoted to the next stage or the best team wins the league.
KOKnock-OutTeams compete against a single opponent in one or two legs (rarely a decider). The team that scores most goals in total (or most in an away game) is promoted to the next round or stage.


Match Schedule

Defines the appointed time when a match was or will be played.

IdentifierNameDescription
NNormalThe match is normally scheduled at the given start date.
PPPostponedThe match start has changed and will be scheduled at a future date. The quoted start date is unconfirmed.
ANAnnulledThe match could not be finished for whatever reason. Consequently, a final or intermediate result has been invalidated.
NPNot playedThe match initially scheduled at the quoted date has not been played and neither will be even at a future date.


Match Time

A point in time regarding match progress. In particular at the end of a match period.

IdentifierNameDescription
HTHalf timeAfter 45'+. The time between first and second half.
FTFull timeAfter 90'+. The time after second half when a regular match ends.
ETExtra timeAfter 120'+. The time after two additional halves of 15' when the regular time did not bring a winner although required.
PPenaltiesAfter the final penalty shooting if extra time did not bring a decision.
AWAwardedThe time when a match outcome is overruled by court due to match abandonment or misbehavior of a match participant.


Performance Index Format

Defines the representation and relationship of performance index values.

IdentifierNameDescription
ABSAbsolute index formatRepresents index values as points. Good performance leads to an increase in points, bad performance to a decrease. Index changes are positive for strong performances against equally strong opponents and negative otherwise.
RELRelative index formatRepresents index values as a relation to all other participants on a scale between 0 and 1. Good performance may not lead to an increase if others perform even stronger. Index changes are positive if their absolute value is higher than those of other participants.


Team Performance Index Projection

Groups associated team performance indices to be included in the result of an API response. Used to control payload and billed points.

IdentifierNameDescription
IIndexThe main index incorporates the team performance in all matches no matter which venue. This is the default projection.
VIVenue indexA venue index solely incorporates the team performance in matches at a particular venue (home or away).
ITIndex trendShows the relationship between a team's long-run and short-run performance. Significant variances may be a signal for turnarounds and hence unexpected results.
LICLast index changeIndicates the index change as a result of the team's performance in the last match. Affects the main index as well as the home index if the team competed at home ground or the away index if competed at away ground.
LMDLast match detailsIncludes fixture and result of the match that initiated the last index change.


Performance Index Trend Classification

Assesses the relationship between short and long performance index trends.

IdentifierNameDescription
BT3Strongly below trendThe team's short-run performance heavily differs from the long-run performance due to poor results. Future results are likely to be in the team's favor.
BT2Increasingly below trendThe team's latest results do definitely not meet the expectation. This may be due to bad luck and/or weak performance.
BT1Slightly below trendThe team performed marginally weaker in the last matches than it normally does.
IT0In trendThe team's short-run performance exactly fits the expectation.
AT1Slightly above trendThe team performed marginally better in the last matches than it normally does.
AT2Increasingly above trendThe team's latest results definitely surpass the expectation. This may be due to luck and/or strong performance.
AT3Strongly above trendThe team's short-run performance heavily differs from the long-run performance due to outstanding results. Future results are likely to be in the opponents' favor.


Metrics Projection

Groups associated metrics to be included in the result of an API response. Used to control payload and billed points.

IdentifierNameDescription
MDMatch detailsIncludes fixture and result of the match for given metrics. If excluded only the match identifier is returned.

TITeam indexThe main performance index of a team. Corresponds to the I performance projection.
TIVTeam venue indexThe venue performance index of a team (home or away). Corresponds to the VI performance projection.
TITTeam index trendThe trend of a team's main performance index. Corresponds to the IT performance projection.
CICompetition indexThe performance index of the belonging competition.

XGExpected goalsAn estimation of the number of goals that will be scored in an average game under the same preconditions. The final result may substantially diverge from this expectation as a result of over/under performance, strike rate and/or (bad) luck.
XSExpected shotsAn estimation of the number of shots that will be taken in an average game under the same preconditions. Shots are in general more representative than goals concerning performance. They uncover a team's attacking power and provide an excellent scoring indicator. Yet the strike rate may essentially differ from team to team.
XCExpected cornersAn estimation of the number of corners that will be kicked in an average game under the same preconditions. Corners are quite difficult to predict due to their manifold occurrence though provide a noticeable indicator for attacking power.
CGActual goalsThe number of goals eventually scored.
CSActual shotsThe number of shots eventually taken. Blocked shots and shots off target are weighted half.
CCActual cornersThe number of corners eventually kicked.
SPScore probabilitiesDeprecated. Use 'PG' instead.
PGProbabilities of goalsProbability distribution of potential match results at full time. Correlates with the XG projection.
PSProbabilities of shotsProbability distribution of potential shot ratios at full time. Correlates with the XS projection.
PCProbabilities of cornersProbability distribution of potential corner ratios at full time. Correlates with the XC projection.

XMExpected moneylineStatistically fair odds for teams to win or end up in a tie.
XHExpected handicapsStatistically fair odds for goal spreads. A spread (line) is used to even out the playing field between teams that are not evenly matched.
XPExpected pointsStatistically fair odds for the number of goals to fall above or below a threshold (line).
CMActual moneylineThe latest average market odds for teams to win or end up in a tie.
CHActual handicapsThe latest average market odds for goal spreads. A spread (line) is used to even out the playing field between teams that are not evenly matched.
CPActual pointsThe latest average market odds for the number of goals to fall above or below a threshold (line).


Metric

Represents a numeric measure of a match characteristic. Used in metric expressions and filters. Bundled through projections to be included in API responses.

Metrics dedicated to a specific team require a reference to the team in question i.e. per parameter.
Some metrics become unique only by an additional discriminator called feature. A feature is a numeric add-on (shown as regular expression in a metric identifier) that lets distinguish different thresholds or points.

IdentifierNameProjectionTeam dedicatedDescription
TITTeam indexTIYThe main performance index of a team.
TIOOpponent indexTIYThe main performance index of a team's opponent.
TIHHome indexTINThe main performance index of the home team.
TIAAway indexTINThe main performance index of the away team.
TIVTTeam venue indexTIVYThe venue specific performance index of a team. For matches at home ground this is the home index, for matches at away ground the away index.
TIVOOpponent venue indexTIVYThe venue specific performance index of a team's opponent. For matches at home ground this is the home index, for matches at away ground the away index.
TIVHHome venue indexTIVNThe home performance index of the home team.
TIVAAway venue indexTIVNThe away performance index of the away team.
TITCLTeam index long-run changeTITYThe average change in the long-run trend of a team's main performance index.
TITCSTeam index short-run changeTITYThe average change in the short-run trend of a team's main performance index.
TIOCLOpponent index long-run changeTITYThe average change in the long-run trend of a team opponent's main performance index.
TIOCSOpponent index short-run changeTITYThe average change in the short-run trend of a team opponent's main performance index.
TIHCLHome index long-run changeTITNThe average change in the long-run trend of the home team's main performance index.
TIHCSHome index short-run changeTITNThe average change in the short-run trend of the home team's main performance index.
TIACLAway index long-run changeTITNThe average change in the long-run trend of the away team's main performance index.
TIACSAway index short-run changeTITNThe average change in the short-run trend of the away team's main performance index.
CICompetition indexCINThe performance index of the competition related to the match.

XGTExpected team goalsXGYThe estimated number of goals scored by a team in an average game under the same preconditions.
XGTVAExpected team goals venue advantageXGYThe advantage incorporated in a team's expected goals based on the venue where the team competes. Adjusting expected goals (XGT) for this advantage reflects the estimation as the match was played on neutral venue.
XGOExpected opponent goalsXGYThe estimated number of goals scored by a team's opponent in an average game under the same preconditions.
XGOVAExpected opponent goals venue advantageXGYThe advantage incorporated in a team opponent's expected goals based on the venue where the opponent competes. Adjusting expected goals (XGO) for this advantage reflects the estimation as the match was played on neutral venue.
XGHExpected home goalsXGNThe estimated number of goals scored by the home team in an average game under the same preconditions.
XGHVAExpected home goals venue advantageXGNThe advantage incorporated in home team's expected goals based on its home matches. Adjusting expected goals (XGH) for this advantage reflects the estimation as the match was played on neutral venue.
XGAExpected away goalsXGNThe estimated number of goals scored by the away team in an average game under the same preconditions.
XGAVAExpected away goals venue advantageXGNThe advantage incorporated in away team's expected goals based on its away matches. Adjusting expected goals (XGA) for this advantage reflects the estimation as the match was played on neutral venue.
XSTExpected team shotsXSYThe estimated number of shots taken by a team in an average game under the same preconditions.
XSTVAExpected team shots venue advantageXSYThe advantage incorporated in a team's expected shots based on the venue where the team competes. Adjusting expected shots (XST) for this advantage reflects the estimation as the match was played on neutral venue.
XSOExpected opponent shotsXSYThe estimated number of shots taken by a team's opponent in an average game under the same preconditions.
XSOVAExpected opponent shots venue advantageXSYThe advantage incorporated in a team opponent's expected shots based on the venue where the opponent competes. Adjusting expected shots (XSO) for this advantage reflects the estimation as the match was played on neutral venue.
XSHExpected home shotsXSNThe estimated number of shots taken by the home team in an average game under the same preconditions.
XSHVAExpected home shots venue advantageXSNThe advantage incorporated in home team's expected shots based on its home matches. Adjusting expected shots (XSH) for this advantage reflects the estimation as the match was played on neutral venue.
XSAExpected away shotsXSNThe estimated number of shots taken by the away team in an average game under the same preconditions.
XSAVAExpected away shots venue advantageXSNThe advantage incorporated in away team's expected shots based on its away matches. Adjusting expected shots (XSA) for this advantage reflects the estimation as the match was played on neutral venue.
XCTExpected team cornersXCYThe estimated number of corners kicked by a team in an average game under the same preconditions.
XCOExpected opponent cornersXCYThe estimated number of corners kicked by a team's opponent in an average game under the same preconditions.
XCHExpected home cornersXCNThe estimated number of corners kicked by the home team in an average game under the same preconditions.
XCAExpected away cornersXCNThe estimated number of corners kicked by the away team in an average game under the same preconditions.
CGTActual team goalsCGYThe number of goals eventually scored by a team.
CGOActual opponent goalsCGYThe number of goals eventually scored by a team's opponent.
CGHActual home goalsCGNThe number of goals eventually scored by the home team.
CGAActual away goalsCGNThe number of goals eventually scored by the away team.
CSTActual team shotsCSYThe number of shots eventually taken by a team.
CSOActual opponent shotsCSYThe number of shots eventually taken by a team's opponent.
CSHActual home shotsCSNThe number of shots eventually taken by the home team.
CSAActual away shotsCSNThe number of shots eventually taken by the away team.
CCTActual team cornersCCYThe number of corners eventually kicked by a team.
CCOActual opponent cornersCCYThe number of corners eventually kicked by a team's opponent.
CCHActual home cornersCCNThe number of corners eventually kicked by the home team.
CCAActual away cornersCCNThe number of corners eventually kicked by the away team.
SP[0-8]{2}Score probabilitySPNDeprecated. Use 'PG[0-8]{2}' instead.
PG[0-8]{2}Goal probabilityPGNThe probability of a potential match result at full time. E.g. 'PG20' corresponds to the probability of a 2-0 home win.
PS[0-9]{4}Shot probabilityPSNThe probability of a shot ratio at full time. E.g. 'PS1206' corresponds to the probability of a 12-6 ratio.
PC[0-9]{4}Corner probabilityPCNThe probability of a corner ratio at full time. E.g. 'PC0603' corresponds to the probability of a 6-3 ratio.

XMTExpected team oddsXMYStatistically fair odds for a team to win the match.
XMOExpected opponent oddsXMYStatistically fair odds for a team's opponent to win the match.
XMHExpected home oddsXMNStatistically fair odds for the home team to win the match.
XMDExpected draw oddsXMNStatistically fair odds for the match to end up in a tie.
XMAExpected away oddsXMNStatistically fair odds for the away team to win the match.
XHLExpected handicap lineXHNThe spread between home and away team goals supposed by statistically fair odds. This is usually the threshold where home and away odds closely mirror a 50/50 chance.
XHH(|+|-)\n{1-3}Expected home handicap oddsXHNStatistically fair home team odds for a given spread (line). The feature expresses an Asian handicap line multiplied by 100 and must be divisible by 25. E.g. 'XHH-025' corresponds to the estimated odds of a home team's -0.25 handicap.
XHA(|+|-)\n{1-3}Expected away handicap oddsXHNStatistically fair away team odds for a given spread (line). The feature expresses an Asian handicap line multiplied by 100 and must be divisible by 25. E.g. 'XHA025' corresponds to the estimated odds of an away team's +0.25 handicap.
XPLExpected points lineXPNThe total number of scored goals supposed by statistically fair odds. This is usually the threshold where over and under odds closely mirror a 50/50 chance.
XPO\n{1-3}Expected over odds XPNStatistically fair odds for the number of goals to fall above a given threshold (line). The feature expresses an Asian points line multiplied by 100 and must be divisible by 25. E.g. 'XPO275' corresponds to the estimated odds that more than 2.75 goals will be scored.
XPU\n{1-3}Expected under oddsXPNStatistically fair odds for the number of goals to fall below a given threshold (line). The feature expresses an Asian points line multiplied by 100 and must be divisible by 25. E.g. 'XPU275' corresponds to the estimated odds that less than 2.75 goals will be scored.
CMTActual team oddsCMYThe latest average market odds for a team to win the match.
CMOActual opponent oddsCMYThe latest average market odds for a team's opponent to win the match.
CMHActual home oddsCMNThe latest average market odds for the home team to win the match.
CMDActual draw oddsCMNThe latest average market odds for the match to end up in a tie.
CMAActual away oddsCMNThe latest average market odds for the away team to win the match.
CHLActual handicap lineCHNThe spread between home and away team goals supposed by the latest average market odds. This is usually the threshold where home and away odds closely mirror a 50/50 chance.
CHH(|+|-)\n{1-3}Actual home handicap oddsCHNThe latest average home team market odds for a given spread (line). The feature expresses an Asian handicap line multiplied by 100 and must be divisible by 25. E.g. 'CHH-025' corresponds to the market odds of a home team's -0.25 handicap.
CHA(|+|-)\n{1-3}Actual away handicap oddsCHNThe latest average away team market odds for a given spread (line). The feature expresses an Asian handicap line multiplied by 100 and must be divisible by 25. E.g. 'CHA025' corresponds to the market odds of an away team's +0.25 handicap.
CPLActual points lineCPNThe total number of scored goals supposed by the latest average market odds. This is usually the threshold where over and under odds closely mirror a 50/50 chance.
CPO\n{1-3}Actual over odds CPNThe latest average market odds for the number of goals to fall above a given threshold (line). The feature expresses an Asian points line multiplied by 100 and must be divisible by 25. E.g. 'CPO275' corresponds to the market odds that more than 2.75 goals will be scored.
CPU\n{1-3}Actual under oddsCPNThe latest average market odds for the number of goals to fall below a given threshold (line). The feature expresses an Asian points line multiplied by 100 and must be divisible by 25. E.g. 'CPU275' corresponds to the market odds that less than 2.75 goals will be scored.


Metric Attribute

A configurable setting used to customize metrics projections.

IdentifierNameDescription
PIFPerformance index formatThe format used to represent performance index values of both team and competition indices. See the index format enumeration.
XSQExpected scores qualityThe minimum quality of metric values for expected goals (XG), shots (XS) and corners (XC) as well as expected odds (XM, XH, XP). Quality depends on the model's input data and is metered on a scale between 0 and 1. Medium quality is around 0.5. The higher it is the more representative the expectation.
SPMMinimum scores probabilityThe minimum value of individual probabilities for possible match results. Optimizes payload in conjunction with high scores that have insignificant value.
OFOdds formatThe format used to represent expected and actual odds. See the odds format enumeration.
OLOdds linesThe number of lines covered by handicap and points odds. Applied to both expected and actual odds. Supported values are 1-9. Though an uneven number is recommended since returned lines are centered around even odds (50/50 probability) so that the medium line is the main line.
XOMExpected odds marginA custom margin by which expected (fair) odds are reduced. Market (actual) odds are not affected as these include the bookmaker's margin anyway.


Metric Function

Allows custom metric calculation and is applied on one or more arguments. Supported arguments are individual metrics, decimal numbers and metric functions.

IdentifierNameDescriptionExampleExample description
addAdditionSummates the numeric values of two or more arguments.add(TIH,TIA)Total teams' performance indices.
subSubtractionSubtracts the numeric value of the second argument from the first argument.sub(1,add(SP00,SP10,SP01))Probability of two or more goals.
mulMultiplicationMultiplies the numeric values of two or more arguments.add(mul(CGH,3),CSH)Custom scores weighing.
divDivisionDivides the numeric value of the first argument by the second argument.div(XGT,XST)A team's expected conversion rate.
absAbsoluteGets the absolute value of a single argument.abs(sub(XPL,CPL))Divergency between expected and market points line.
grtGreatestGets the highest numeric value of one or more arguments.grt(XGHVA,XGAVA)The higher venue advantage in expected goals.
lstLeastGets the lowest numeric value of one or more arguments.lst(CMH,CMD,CMA)The lowest moneyline market odds.


Odds Format

Defines the numeric styling of odds. Commonly depends on the region.

Note that all market (actual) odds include the bookmaker's margin. In reality a probability of 50% will never pay out even odds (i.e. decimal 2.00) but a little less (e.g. 1.95) as a consequence. Expected odds are by default represented as statistically fair odds (no margin). You may want to adapt this representation by setting the XOM metric attribute to a standard margin.

IdentifierNameDescription
DCDecimalThe probability's inverse. Payout equals risk at odds of 2.0 (= even odds or a 50/50 chance).
AMAmericanFavorites have negative, underdogs positive value. Positive indicates the payout of a one unit risk, negative the risk of a one unit payout. The lower the odds the better the chances to win. Even odds are at +100.
HKHong KongEqual to decimal odds minus 1. Even money is payed out at odds of 1.0.
IDIndonesianEqual to American odds divided by 100. Even money is payed out at odds of 1.0.
MYMalaysianFavorites have positive, underdogs negative value. Positive odds equal Hong Kong style, negative indicate the risk of a one unit payout. Even odds are at -1.0.
PBProbabilityThe implied probability. Inverse of decimal odds. Payout equals risk at a probability of 50%.


Relational operator

Allows compare numeric values and delivers a boolean value. Used for predicates.

IdentifierName
eqEqual
neNot equal
ltLess than
leLess equal
geGreater equal
gtGreater than


API error enums

Errors are basically mapped to API specific codes which are returned in the response model under /error/code.
Some errors are not mapped to codes and solely identifiable through HTTP status.

Error codeHTTP statusDescriptionExample
101401Failed authenticationAPI authentication failed. Provide a valid authentication token.
102401Failed authenticationAPI authentication failed. Provide a valid user login and password.
111401Failed authenticationAPI authentication failed. Provide a valid subscription token.
131403Unauthorized operationThe operation is not active for your subscription. Either ignore it or consider another subscription plan.
-404Invalid endpointThe requested URI represents an invalid endpoint which is not available. Refer to the docs to find valid paths.
-405Illegal methodNon-GET requests are not supported.
141429Exceeded rate limitRequest exceeded the maximum number of requests allowed for your subscription within a certain amount of time. Try again soon.

201400Missing parameter (obligatory)The 'teamId' parameter must be defined. Refer to the docs to find out parameter details.
202400Missing parameters (choice)At least one of the following parameters must be defined: 'countryId', 'nameLike'.
203400Missing parameter (dependent)If a team dedicated metric is defined then the 'teamId' parameter must be defined, too.
211400Illegal string parameterThe 'nameLike' parameter must at least consist of 4 letters/digits.
214400Illegal string parameter (expression)The 'metric' parameter contains an invalid expression. Refer to the docs to learn about eligible formats.
231400Illegal number parameterThe 'year' parameter must consist of 4 digits.
241400Illegal date parameterThe date format is unsupported for the 'minStart' parameter. Refer to the docs to find a valid format.
281400Too many entities parameterThe 'teamIds' parameter must not define more than two teams.

301400Invalid entityThe competition stage identifier is invalid. Use the 'Get Competitions' operation to find valid stages.
311400Unknown entityThe 'XY' projection is unknown. Refer to the docs to find valid projections.
331400Illegal match teamThe team does not compete in the requested match.
332400Illegal competition stageThe match is not competed in the requested competition stage.
333400Illegal match startThe match start is outside the requested or default time span.
341400Competition stage not groupedThe competition stage is not divided into groups.

401400Unsupported subscription projectionThe 'IT' projection is unsupported for your subscription. Either ignore it or consider another subscription plan.
411400Unsupported subscription formatThe performance index format is unsupported for your subscription. Refer to the docs to find an alternative format.
431400Exceeded subscription time spanThe time span between 'minDate' and 'maxDate' must not exceed 3 years for your subscription.
451400Exceeded subscription entitiesThe number of competitions must not exceed 50 for your subscription.

999500Unexpected errorAn unexpected error occurred. Try again later or contact our API support at [email protected] under specification of reference MX-202103145519.
-503API unavailableThe API server is not available due to maintenance. Check the 'Retry-After' response header to find out when it's planned to come back.


API Changelog

Version 1.1.0

New metrics projections PG, PS and PC for detailed probability distributions on goals, shots and corners.


Version 1.0.3

New competition stage property group.
New parameter group for endpoints Get Teams and Get Team Performance Indices.


Version 1.0.2

Short names for teams.


Version 1.0.1

Shorter match result and odds updates.
New metrics projection MD.
Format correction for score probabilities with scientific notation.


Version 1.0.0

Stable version. Minor schema additions to beta.
New match property schedule, new match time AW.


Version 0.9.1

Beta version. Metrics library support. Minor schema additions to alpha.


Version 0.8.3

Alpha test version. Base and performance index libraries support.



© 2023 metrx21.io  -  Predictive Sports Analytics