Sports & Leagues API Endpoints

Overview

Core endpoints for retrieving sports and league hierarchy data. These form the foundation for filtering and navigating the API.

Endpoint Summary

Endpoint Method Auth Description
/v1/sports GET None Get all available sports
/v1/leagues GET Optional Get all leagues
/v1/leagues/breakdown/level GET Optional Get league breakdown levels

Detailed Endpoint Documentation

1. GET /v1/sports

Description: Retrieves a list of all available sports with their metadata.

Authentication: None required

Query Parameters: Uses AppFilter

Parameter Type Description
Limit int Maximum results (default: 100)

Response: IEnumerable<Sport>

[
  {
    "id": 1,
    "name": "Football",
    "code": "NFL",
    "imageUrl": "https://cdn.example.com/sports/football.svg"
  },
  {
    "id": 2,
    "name": "Basketball",
    "code": "NBA",
    "imageUrl": "https://cdn.example.com/sports/basketball.svg"
  }
]

Response Fields:

Field Type Description
id long Unique sport identifier
name string Sport display name
code string Short sport code (e.g., "NFL", "NBA")
imageUrl string URL to sport icon image

2. GET /v1/leagues

Description: Retrieves all available leagues with optional filtering.

Authentication: API key optional (logs usage if provided)

Query Parameters:

Parameter Type Description
SportId long[] Filter by sport IDs
Limit int Maximum results (default: 100, max: 10000)
LocationCountry string Filter by country
LocationState string Filter by state

Response: IEnumerable<League>

[
  {
    "id": 1,
    "name": "National Football League",
    "details": "Professional American football league",
    "code": "NFL",
    "sport": {
      "id": 1,
      "name": "Football",
      "code": "NFL",
      "imageUrl": "https://..."
    },
    "sportId": 1,
    "sportCode": "FOOTBALL",
    "sportLogoUrl": "https://...",
    "logoUrl": "https://cdn.example.com/leagues/nfl.png",
    "oneMatchPerWeek": true,
    "isSwapSportTeams": false,
    "summaryText": "The NFL is the premier...",
    "seasonTypeId": 1,
    "countryFlagUrl": "https://cdn.example.com/flags/us.png"
  }
]

Response Fields:

Field Type Description
id long Unique league identifier
name string Full league name
details string League description
code string Short league code
sport Sport Nested sport object
sportId long? Sport identifier
sportCode string Sport code
sportLogoUrl string Sport logo URL
logoUrl string League logo URL
oneMatchPerWeek bool? Weekly schedule indicator
isSwapSportTeams bool Team position swap flag
summaryText string League summary
seasonTypeId long? Current season type
countryFlagUrl string Country flag image

Error Responses:

Status Error Description
400 invalid_limit Limit must be between 0 and 10000

3. GET /v1/leagues/breakdown/level

Description: Retrieves league breakdown levels (divisions, conferences, etc.).

Authentication: API key optional

Query Parameters:

Parameter Type Description
LeagueId long[] Filter by league IDs
Limit int Maximum results

Response: IEnumerable<LeagueBreakdownLevel>

[
  {
    "id": 1,
    "name": "AFC",
    "code": "AFC",
    "leagueId": 1,
    "parentId": null,
    "level": 1
  },
  {
    "id": 2,
    "name": "AFC East",
    "code": "AFC_EAST",
    "leagueId": 1,
    "parentId": 1,
    "level": 2
  }
]

Response Fields:

Field Type Description
id long Unique breakdown level ID
name string Level name (e.g., "AFC East")
code string Level code
leagueId long Parent league ID
parentId long? Parent breakdown level ID
level int Hierarchy depth level

Examples

Get All Sports

curl -X GET "https://api.example.com/v1/sports"

Get NFL Leagues Only

curl -X GET "https://api.example.com/v1/leagues?SportId=1"

Get League Divisions for NFL

curl -X GET "https://api.example.com/v1/leagues/breakdown/level?LeagueId=1"

Get Leagues with Location Filter

curl -X GET "https://api.example.com/v1/leagues?LocationCountry=USA"

Related Endpoints