# Leagues Sport leagues related endpoints ## Get recommended leagues > Returns personalized league recommendations.\ > \ > Only leagues with events starting between the requested time range will be considered.\ > \ > {% hint style="info" %}\ > \ > \## Confidence\ > \ > \ > Each returned item is associated with a number from 0 to 1 indicating the confidence\ > of the system in this specific recommendation. The higher the number the more confident\ > the recommendation of it.\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Filtering example\ > \ > \ > In this example we get all recommended leagues for user with id \`1\`,\ > starting till \`12 hours\` from now.\ > \ > \`\`\`bash\ > $ curl --request GET \\\ > \--url ' > \`\`\`\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Result processing\ > \ > \ > It is important to clarify that filtering and processing takes place on an event level,\ > and the events satisfying the given conditions are then grouped on league level.\ > \ > {% endhint %}\
````json {"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport leagues related endpoints","name":"Leagues"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"RecommendedLeague":{"additionalProperties":false,"description":"A recommended league object","properties":{"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"}},"type":"object"},"Error":{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/sports/leagues/recommended":{"get":{"description":"Returns personalized league recommendations.\n\nOnly leagues with events starting between the requested time range will be considered.\n\n{% hint style=\"info\" %}\n\n## Confidence\n\n\nEach returned item is associated with a number from 0 to 1 indicating the confidence\nof the system in this specific recommendation. The higher the number the more confident\nthe recommendation of it.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Filtering example\n\n\nIn this example we get all recommended leagues for user with id `1`,\nstarting till `12 hours` from now.\n\n```bash\n$ curl --request GET \\\n --url 'https://api.vaix.ai/api/sports/leagues/recommended?user=1&to_offset=12h'\n```\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Result processing\n\n\nIt is important to clarify that filtering and processing takes place on an event level,\nand the events satisfying the given conditions are then grouped on league level.\n\n{% endhint %}\n\n","operationId":"get_recommended_leagues","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"The user to get recommendations for.","in":"query","name":"user","required":true,"schema":{"type":"string"}},{"description":"Leagues with events starting after this datetime will be returned.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to one day (24 hours).\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"description":"Number of leagues to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"minimum":1,"type":"integer"}},{"description":"Optional filtering of the leagues to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["league","league_id","sport","sport_id","country","country_id","status","booking_status","event_type","participants","participant_ids","user_country","user_state","user_age_group","user_gender"],"type":"string"}},{"description":"The operator to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored.\n","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"description":"The bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`sub_bookmaker_id` parameter.\n","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"The sub-bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`bookmaker_id` parameter.\n","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"Applies a limit to a group of items. For more information, head to\n`Limiting -> Group Limiting` section of the docs.\n`country:5,country_id:2`.\n","in":"query","name":"group_limit","required":false,"schema":{"enum":["country","country_id","sport","sport_id"],"type":"string"}},{"description":"The columns to sort the results by. It expects a string adhering to\nthe ordering format, as described in the ordering section, e.g.\n`+league_confidence,-sport_confidence`.\n","in":"query","name":"order_by","required":false,"schema":{"enum":["league_confidence","sport_confidence","country_confidence"],"type":"string"}},{"description":"Optional selection of the object fields to retrieve. It expects a comma\nseparated list of strings, as described in the field selection section,\ne.g. `country,country_id`.\n","in":"query","name":"fields","required":false,"schema":{"enum":["country","country_id","league","league_id","sport","sport_id","confidence"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Comma separated list of keywords. If given, this input will be used\nas user demographics data for the recommendations, e.g `country:gr,city:ath`.\n","in":"query","name":"raw","required":false,"schema":{"enum":["age_group","city","country"],"type":"string"}},{"description":"Optional re ordering of the results based on one or more metrics.\nExpected format is a comma separated list of keywords where each value\nshould be a float in the range [0,1]. e.g. `popular:0.3,trending:0.2`.\nFor more information head to the ordering documentation section.\n","in":"query","name":"reorder_by","required":false,"schema":{"enum":["popular","trending"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/RecommendedLeague"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get recommended leagues","tags":["Leagues"]}}}} ```` ## Get popular leagues > Returns popular leagues for the given time frame.\ > \ > Only leagues with events starting between the requested time range will be considered.\ > \ > The results are sorted by popularity.\ > \ > {% hint style="info" %}\ > \ > \## Popularity\ > \ > \ > The metric used to measure popularity is the number of bets placed on\ > events of each league.\ > \ > The normalized value of its total bets is also assigned to each league as its confidence.\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Filtering example\ > \ > \ > In this example we get all popular \`Soccer\` leagues.\ > \ > \`\`\`bash\ > $ curl --request GET \\\ > \--url ' > \`\`\`\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Result processing\ > \ > \ > It is important to clarify that filtering and processing takes place on an event level,\ > and the events satisfying the given conditions are then grouped on league level.\ > \ > {% endhint %}\
````json {"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport leagues related endpoints","name":"Leagues"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"PopularLeague":{"additionalProperties":false,"description":"A popular league object","properties":{"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"total_bets":{"description":"Number of bets including this event","type":"integer"}},"type":"object"},"Error":{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/sports/leagues/popular":{"get":{"description":"Returns popular leagues for the given time frame.\n\nOnly leagues with events starting between the requested time range will be considered.\n\nThe results are sorted by popularity.\n\n{% hint style=\"info\" %}\n\n## Popularity\n\n\nThe metric used to measure popularity is the number of bets placed on\nevents of each league.\n\nThe normalized value of its total bets is also assigned to each league as its confidence.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Filtering example\n\n\nIn this example we get all popular `Soccer` leagues.\n\n```bash\n$ curl --request GET \\\n --url 'https://api.vaix.ai/api/sports/leagues/popular?filters=sport%3Aeq%3ASoccer'\n```\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Result processing\n\n\nIt is important to clarify that filtering and processing takes place on an event level,\nand the events satisfying the given conditions are then grouped on league level.\n\n{% endhint %}\n\n","operationId":"get_popular_leagues","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"The user to get recommendations for.","in":"query","name":"user","required":false,"schema":{"type":"string"}},{"description":"Leagues with events starting after this datetime will be returned.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to one day (24 hours).\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"description":"Number of leagues to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"minimum":1,"type":"integer"}},{"description":"Optional filtering of the leagues to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["league","league_id","sport","sport_id","country","country_id","status","booking_status","event_type","participants","participant_ids","user_country","user_state","user_age_group","user_gender"],"type":"string"}},{"description":"The operator to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored.\n","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"description":"The bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`sub_bookmaker_id` parameter.\n","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"The sub-bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`bookmaker_id` parameter.\n","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"Applies a limit to a group of items. For more information, head to\n`Limiting -> Group Limiting` section of the docs.\n`country:5,country_id:2`.\n","in":"query","name":"group_limit","required":false,"schema":{"enum":["country","country_id","sport","sport_id"],"type":"string"}},{"description":"Optional dynamic filtering of the items to retrieve. If any dynamic filter is set,\nthe filter's value will be dynamically calculated and used. Notice that for `user`\nrelated filters, the `user` query parameter must be provided. For example,\n`dynamic_filters=user_country` will return data related only to the user's specific country.\n","in":"query","name":"dynamic_filters","required":false,"schema":{"enum":["user_country","user_state","user_language","user_brand","user_city","game_country"],"type":"string"}},{"description":"The columns to sort the results by. It expects a string adhering to\nthe ordering format, as described in the ordering section, e.g.\n`+league_confidence,-sport_confidence`.\n","in":"query","name":"order_by","required":false,"schema":{"enum":["league_confidence","sport_confidence","country_confidence"],"type":"string"}},{"description":"Optional selection of the object fields to retrieve. It expects a comma\nseparated list of strings, as described in the field selection section,\ne.g. `country,country_id`.\n","in":"query","name":"fields","required":false,"schema":{"enum":["country","country_id","league","league_id","sport","sport_id","confidence","total_bets"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Optional re ordering of the results based on one or more metrics.\nExpected format is a comma separated list of keywords where each value\nshould be a float in the range [0,1]. e.g. `recommended:0.3,trending:0.2`.\nFor more information head to the ordering documentation section.\n","in":"query","name":"reorder_by","required":false,"schema":{"enum":["recommended","trending"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/PopularLeague"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get popular leagues","tags":["Leagues"]}}}} ```` ## Get trending leagues > Returns trending leagues for the given time frame.\ > \ > Only leagues with events starting between the requested time range will be considered.\ > \ > The results are sorted by \`trending score\`.\ > \ > {% hint style="info" %}\ > \ > \## Trending score\ > \ > \ > To calculate trending score for a league, each bet placed on an event of\ > this league, contributes a value determined by how recently the bet was\ > placed.\ > \ > Recent bets add more value than older ones.\ > \ > The normalized value of its score is also assigned to each league as its confidence.\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Filtering example\ > \ > \ > In this example we get all trending \`Soccer\` leagues.\ > \ > \`\`\`bash\ > $ curl --request GET \\\ > \--url ' > \`\`\`\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Result processing\ > \ > \ > It is important to clarify that filtering and processing takes place on an event level,\ > and the events satisfying the given conditions are then grouped on league level.\ > \ > {% endhint %}\
````json {"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport leagues related endpoints","name":"Leagues"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"TrendingLeague":{"additionalProperties":false,"description":"A trending league object","properties":{"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"score":{"description":"Trending score, the highest the score the more trending the item","type":"number"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"}},"type":"object"},"Error":{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/sports/leagues/trending":{"get":{"description":"Returns trending leagues for the given time frame.\n\nOnly leagues with events starting between the requested time range will be considered.\n\nThe results are sorted by `trending score`.\n\n{% hint style=\"info\" %}\n\n## Trending score\n\n\nTo calculate trending score for a league, each bet placed on an event of\nthis league, contributes a value determined by how recently the bet was\nplaced.\n\nRecent bets add more value than older ones.\n\nThe normalized value of its score is also assigned to each league as its confidence.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Filtering example\n\n\nIn this example we get all trending `Soccer` leagues.\n\n```bash\n$ curl --request GET \\\n --url 'https://api.vaix.ai/api/sports/leagues/trending?filters=sport%3Aeq%3ASoccer'\n```\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Result processing\n\n\nIt is important to clarify that filtering and processing takes place on an event level,\nand the events satisfying the given conditions are then grouped on league level.\n\n{% endhint %}\n\n","operationId":"get_trending_leagues","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"The user to get recommendations for.","in":"query","name":"user","required":false,"schema":{"type":"string"}},{"description":"Leagues with events starting after this datetime will be returned.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to one day (24 hours).\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"description":"Number of leagues to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"minimum":1,"type":"integer"}},{"description":"Optional filtering of the leagues to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["league","league_id","sport","sport_id","country","country_id","status","booking_status","event_type","participants","participant_ids","user_country","user_state","user_age_group","user_gender"],"type":"string"}},{"description":"The operator to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored.\n","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"description":"The bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`sub_bookmaker_id` parameter.\n","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"The sub-bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`bookmaker_id` parameter.\n","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"Applies a limit to a group of items. For more information, head to\n`Limiting -> Group Limiting` section of the docs.\n`country:5,country_id:2`.\n","in":"query","name":"group_limit","required":false,"schema":{"enum":["country","country_id","sport","sport_id"],"type":"string"}},{"description":"Optional dynamic filtering of the items to retrieve. If any dynamic filter is set,\nthe filter's value will be dynamically calculated and used. Notice that for `user`\nrelated filters, the `user` query parameter must be provided. For example,\n`dynamic_filters=user_country` will return data related only to the user's specific country.\n","in":"query","name":"dynamic_filters","required":false,"schema":{"enum":["user_country","user_state","user_language","user_brand","user_city","game_country"],"type":"string"}},{"description":"The columns to sort the results by. It expects a string adhering to\nthe ordering format, as described in the ordering section, e.g.\n`+league_confidence,-sport_confidence`.\n","in":"query","name":"order_by","required":false,"schema":{"enum":["league_confidence","sport_confidence","country_confidence"],"type":"string"}},{"description":"Optional selection of the object fields to retrieve. It expects a comma\nseparated list of strings, as described in the field selection section,\ne.g. `country,country_id`.\n","in":"query","name":"fields","required":false,"schema":{"enum":["country","country_id","league","league_id","sport","sport_id","confidence","score"],"type":"string"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Considers bets placed after the current timestamp minus the given\nminutes/hours/days. If not set defaults to `2 days`.\nThe value must be in range [1m - 7d].\n","in":"query","name":"trending_within","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Optional re ordering of the results based on one or more metrics.\nExpected format is a comma separated list of keywords where each value\nshould be a float in the range [0,1]. e.g. `recommended:0.3,popular:0.2`.\nFor more information head to the ordering documentation section.\n","in":"query","name":"reorder_by","required":false,"schema":{"enum":["recommended","popular"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/TrendingLeague"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get trending leagues","tags":["Leagues"]}}}} ```` ## Get similar leagues > Returns similar leagues for the given league id(s). Only leagues\ > with events starting between the requested time range will be considered.\ > \ > The leagues are sorted by \`distance\` ascending.\ > \ > {% hint style="info" %}\ > \ > \## Distance\ > \ > \ > The metric used to measure similarity between items is called distance.\ > It is a system indicator on how similar the item is to the input.\ > \ > The smaller the number the more similar the item.\ > \ > The normalized value of the item's distance to the input\ > is also assigned to each event as its \`confidence\`.\ > \ > {% endhint %}\ > \ > \ > {% hint style="info" %}\ > \ > \## Query example\ > \ > \ > In this example we get the similar league to the league with id \`sr:tournament:1\`\ > \ > \`\`\`bash\ > $ curl --request GET \\\ > \--url ' > \`\`\`\ > \ > {% endhint %}\
````json {"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Sport leagues related endpoints","name":"Leagues"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"SimilarLeague":{"additionalProperties":false,"description":"A similar league object","properties":{"confidence":{"description":"Confidence score, the highest the value the more confident the recommendation of the item\n","type":"number"},"country":{"description":"The country the event takes place at","nullable":true,"type":"string"},"country_id":{"description":"The id of the country the event takes place at","nullable":true,"type":"string"},"distance":{"description":"Distance of the item from the given inputs, the lowest the value the more\nsimilar the item.\n","type":"number"},"league":{"description":"The league associated with the current event","nullable":true,"type":"string"},"league_id":{"description":"The id of the event's league","nullable":true,"type":"string"},"sport":{"description":"The sport of the event, e.g. `soccer`","nullable":true,"type":"string"},"sport_id":{"description":"The id of the event's sport","nullable":true,"type":"string"},"total_bets":{"description":"Number of bets including this event","type":"integer"}},"type":"object"},"Error":{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},"Errors":{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/sports/leagues/similar":{"get":{"description":"Returns similar leagues for the given league id(s). Only leagues\nwith events starting between the requested time range will be considered.\n\nThe leagues are sorted by `distance` ascending.\n\n{% hint style=\"info\" %}\n\n## Distance\n\n\nThe metric used to measure similarity between items is called distance.\nIt is a system indicator on how similar the item is to the input.\n\nThe smaller the number the more similar the item.\n\nThe normalized value of the item's distance to the input\nis also assigned to each event as its `confidence`.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Query example\n\n\nIn this example we get the similar league to the league with id `sr:tournament:1`\n\n```bash\n$ curl --request GET \\\n --url 'https://api.vaix.ai/api/sports/leagues/similar?league_ids=sr:tournament:1'\n```\n\n{% endhint %}\n\n","operationId":"get_similar_leagues","parameters":[{"description":"Custom client header, the value should be the name of the group the user belongs to","in":"header","name":"x-vaix-client-id","required":true,"schema":{"type":"string"}},{"description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","in":"header","name":"x-vaix-authentication-method","required":false,"schema":{"type":"string"}},{"description":"Comma separated list of league ids for which to return similar leagues.\nIf multiple leagues are provided the leagues returned are going to be\nthe ones with the shortest average distance to all of the provided leagues.\n","in":"query","name":"league_ids","required":true,"schema":{"type":"string"}},{"description":"Leagues with events starting after this datetime will be returned.","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Considers events starting after the from timestamp plus the given minutes/hours/days.\nIf not set defaults to `0 minutes`.\nThe value must be in range [-7d - 7d].\n","in":"query","name":"from_offset","required":false,"schema":{"default":"0","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"Considers events starting till the `from` timestamp plus the given\nminutes/hours/days. If not set defaults to one day (24 hours).\nThe value must be in range [`-7d` - `7d`].\n","in":"query","name":"to_offset","required":false,"schema":{"default":"2d","pattern":"^[+-]?[0-9]+([.][0-9]+)?[smhd]?$","type":"string"}},{"description":"DEPRECATED: Considers events starting till the `from` timestamp plus the given\nhours. If not set defaults to one day (24 hours).\n","in":"query","name":"hours","required":false,"schema":{"maximum":72,"minimum":1,"type":"integer"}},{"description":"Number of leagues to return.\n","in":"query","name":"count","required":false,"schema":{"default":5,"minimum":1,"type":"integer"}},{"description":"Optional filtering of the leagues to retrieve. It expects a string\nadhering to the filtering format, as described in the filtering\nsection, e.g. `sport:eq:Soccer`.\n","in":"query","name":"filters","required":false,"schema":{"enum":["league","league_id","sport","sport_id","country","country_id","status","booking_status","event_type","participants","participant_ids"],"type":"string"}},{"description":"The operator to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored.\n","in":"query","name":"operator","required":false,"schema":{"type":"string"}},{"description":"The bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`sub_bookmaker_id` parameter.\n","in":"query","name":"bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"The sub-bookmaker id to use for querying data. Notice that this is applied only\nif your account has access to multiple operators. In a different case\nthe assigned operator to your account is used and the value of this\nfield is ignored. Note that this parameter is used together with the\n`bookmaker_id` parameter.\n","in":"query","name":"sub_bookmaker_id","required":false,"schema":{"type":"integer"}},{"description":"List of event types to consider when generating recommendations.\nOne or more types can be provided.\nAvailable options are:\n* `match`: Standard matches to be considered.\n* `seasonal`: Seasonal events to be considered.\n* `forced_events`: Handpicked events to be considered regardless of their start_time.\n","in":"query","name":"event_types","required":false,"schema":{"default":"match,forced_events","enum":["match","seasonal","forced_events"],"type":"string"}},{"description":"Optional selection of the object fields to retrieve. It expects a comma\nseparated list of strings, as described in the field selection section,\ne.g. `country,country_id`.\n","in":"query","name":"fields","required":false,"schema":{"enum":["country","country_id","league","league_id","sport","sport_id","confidence","distance"],"type":"string"}},{"description":"If it's true include input items in response. By default is set to `false`.\n","in":"query","name":"include_input","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"The location of the page where the request takes place.\n","in":"query","name":"location","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"API response","properties":{"data":{"description":"Array of objects","items":{"$ref":"#/components/schemas/SimilarLeague"},"type":"array"},"status":{"description":"The status of the request","enum":["success","error"],"type":"string"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden"},"406":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Not Acceptable"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Request Entity Too Large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}},"description":"Unprocessable Entity"},"425":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}},"description":"Too Early"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Internal Server Error"}},"summary":"Get similar leagues","tags":["Leagues"]}}}} ```` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sportradar.com/personalization/api-reference/sports/leagues.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.