{
  "info": {
    "name": "BSD API v2",
    "_postman_id": "bsd-api-v2-collection",
    "description": "Bzzoiro Sports Data — public football API v2.\n\nStreamlined event endpoints with structured stats, decoded weather, and clean separation of concerns. v1 still works at /api/* — migrate when convenient.\n\nDocs: https://sports.bzzoiro.com/docs/v2/\nOpenAPI: https://sports.bzzoiro.com/api/schema/?format=json\n\nSet the `token` collection variable to your API key (free at https://sports.bzzoiro.com/register/).",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      { "key": "key", "value": "Authorization", "type": "string" },
      { "key": "value", "value": "Token {{token}}", "type": "string" },
      { "key": "in", "value": "header", "type": "string" }
    ]
  },
  "variable": [
    { "key": "base_url", "value": "https://sports.bzzoiro.com", "type": "string" },
    { "key": "token", "value": "YOUR_API_KEY", "type": "string" }
  ],
  "item": [
    {
      "name": "Events",
      "description": "Football events (matches). One endpoint per concern — fetch only what you need.",
      "item": [
        {
          "name": "List events",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/?league_id=17&status=finished&limit=20",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", ""],
              "query": [
                { "key": "league_id", "value": "17", "description": "Filter by league" },
                { "key": "status", "value": "finished", "description": "notstarted | inprogress | finished | postponed | cancelled" },
                { "key": "date_from", "value": "", "description": "YYYY-MM-DD or ISO 8601 UTC", "disabled": true },
                { "key": "date_to", "value": "", "description": "YYYY-MM-DD or ISO 8601 UTC", "disabled": true },
                { "key": "limit", "value": "20", "description": "Page size, default 50, max 200" },
                { "key": "offset", "value": "0", "disabled": true }
              ]
            },
            "description": "Paginated list of events. Each item has the same shape as the detail endpoint."
          }
        },
        {
          "name": "Event detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", ""]
            },
            "description": "Core match info, score, status, weather, neutral-ground/derby flags. Heavy data lives under sub-resources."
          }
        },
        {
          "name": "Event stats",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/stats/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", "stats", ""]
            },
            "description": "Per-side team stats (counters, percentages, ratio shapes), shotmap, momentum, xG per minute."
          }
        },
        {
          "name": "Event incidents",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/incidents/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", "incidents", ""]
            },
            "description": "Goals, cards, substitutions and other timeline incidents. player_id fields use BSD primary keys."
          }
        },
        {
          "name": "Event odds",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/odds/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", "odds", ""]
            },
            "description": "1X2, over/under, BTTS odds in decimal format."
          }
        },
        {
          "name": "Event metadata",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/metadata/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", "metadata", ""]
            },
            "description": "Jerseys, pre-match facts, AI-generated preview text."
          }
        },
        {
          "name": "Event lineups",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/lineups/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", "lineups", ""]
            },
            "description": "Starting XI + substitutes per side, plus the unavailable players list (injured / suspended / doubtful)."
          }
        },
        {
          "name": "Event player stats",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/events/204851/player-stats/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "events", "204851", "player-stats", ""]
            },
            "description": "Per-player statistics for every player who appeared (typically 22+ records). Sorted by team_id then descending minutes."
          }
        }
      ]
    },
    {
      "name": "Leagues",
      "description": "Competitions with seasons, standings, and venue assignments.",
      "item": [
        {
          "name": "List leagues",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/?country=England&is_women=false",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", ""],
              "query": [
                { "key": "country", "value": "England", "description": "Filter by country (case-insensitive)" },
                { "key": "is_women", "value": "false", "description": "Filter by women / men" },
                { "key": "is_active", "value": "true", "description": "Default: only active", "disabled": true },
                { "key": "limit", "value": "50", "disabled": true },
                { "key": "offset", "value": "0", "disabled": true }
              ]
            }
          }
        },
        {
          "name": "League detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/17/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", "17", ""]
            },
            "description": "Single league with embedded current_season."
          }
        },
        {
          "name": "Current season",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/17/season/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", "17", "season", ""]
            },
            "description": "The active season for a league. Returns null when none is flagged current."
          }
        },
        {
          "name": "All seasons",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/17/seasons/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", "17", "seasons", ""]
            },
            "description": "Every season on file for this league, newest first."
          }
        },
        {
          "name": "Standings",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/17/standings/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", "17", "standings", ""],
              "query": [
                { "key": "season_id", "value": "", "description": "Defaults to current season", "disabled": true }
              ]
            },
            "description": "League table for one season. Cup competitions return groups; league competitions return a flat standings array. Includes xG-based equivalents."
          }
        },
        {
          "name": "League venues",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/16/venues/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", "16", "venues", ""],
              "query": [
                { "key": "season_id", "value": "", "description": "Restrict to assignments in this season", "disabled": true }
              ]
            },
            "description": "Venues used by this league across one or more seasons. Each row is a tournament assignment with the venue object embedded."
          }
        },
        {
          "name": "League / season venues",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/leagues/16/seasons/82/venues/?round=F",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "leagues", "16", "seasons", "82", "venues", ""],
              "query": [
                { "key": "host_country_code", "value": "", "description": "ISO 3166-1 alpha-2", "disabled": true },
                { "key": "hosts_opening", "value": "true", "disabled": true },
                { "key": "hosts_final", "value": "true", "disabled": true },
                { "key": "hosts_third_place", "value": "true", "disabled": true },
                { "key": "round", "value": "F", "description": "R32 | R16 | QF | SF | 3RD | F" }
              ]
            },
            "description": "Replaces the legacy World Cup venues endpoint. Adds knockout-round and host-country filters."
          }
        }
      ]
    },
    {
      "name": "Teams",
      "description": "Football clubs and national teams.",
      "item": [
        {
          "name": "List teams",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/teams/?country_code=GB&league_id=17",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "teams", ""],
              "query": [
                { "key": "country_code", "value": "GB", "description": "ISO 3166-1 alpha-2" },
                { "key": "league_id", "value": "17", "description": "Teams with at least one event in this league" },
                { "key": "season_id", "value": "", "disabled": true },
                { "key": "in_competition", "value": "true", "description": "Requires league_id", "disabled": true },
                { "key": "is_women", "value": "false", "disabled": true },
                { "key": "name", "value": "", "disabled": true },
                { "key": "limit", "value": "50", "disabled": true },
                { "key": "offset", "value": "0", "disabled": true }
              ]
            }
          }
        },
        {
          "name": "Team detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/teams/267/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "teams", "267", ""]
            }
          }
        },
        {
          "name": "Team squad",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/teams/267/squad/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "teams", "267", "squad", ""]
            },
            "description": "Active players currently linked to this team via current_team."
          }
        },
        {
          "name": "Team fixtures",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/teams/267/fixtures/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "teams", "267", "fixtures", ""],
              "query": [
                { "key": "date_from", "value": "", "description": "ISO 8601 UTC", "disabled": true },
                { "key": "date_to", "value": "", "description": "ISO 8601 UTC", "disabled": true },
                { "key": "league_id", "value": "", "disabled": true },
                { "key": "status", "value": "finished", "disabled": true }
              ]
            },
            "description": "Defaults to a window of now − 3h to now + 7d when no date filters are provided."
          }
        }
      ]
    },
    {
      "name": "Players",
      "description": "Identity, per-match stats, transfers, career aggregates, and national-team data.",
      "item": [
        {
          "name": "List players",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/players/?team_id=267",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "players", ""],
              "query": [
                { "key": "team_id", "value": "267", "description": "Filter by current club" },
                { "key": "national_team_id", "value": "", "disabled": true },
                { "key": "nationality_code", "value": "BR", "description": "ISO 3166-1 alpha-2", "disabled": true },
                { "key": "position", "value": "F", "description": "Generic G/D/M/F or specific code", "disabled": true },
                { "key": "name", "value": "", "disabled": true },
                { "key": "limit", "value": "50", "disabled": true },
                { "key": "offset", "value": "0", "disabled": true }
              ]
            }
          }
        },
        {
          "name": "Player detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/players/5821/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "players", "5821", ""]
            }
          }
        },
        {
          "name": "Player per-match stats",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/players/5821/stats/?season_id=243",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "players", "5821", "stats", ""],
              "query": [
                { "key": "season_id", "value": "243" },
                { "key": "team_id", "value": "", "description": "Stats logged with this team (handles transfers)", "disabled": true },
                { "key": "league_id", "value": "", "disabled": true },
                { "key": "date_from", "value": "", "disabled": true },
                { "key": "date_to", "value": "", "disabled": true }
              ]
            },
            "description": "Per-match stats. Filtering by event_id is rejected — use /events/{id}/player-stats/ for that case."
          }
        },
        {
          "name": "Player transfers",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/players/5821/transfers/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "players", "5821", "transfers", ""]
            },
            "description": "Transfer history for the player, newest first."
          }
        },
        {
          "name": "Player career",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/players/5821/career/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "players", "5821", "career", ""]
            },
            "description": "Career totals aggregated by season — matches, goals, assists, minutes, average rating."
          }
        },
        {
          "name": "Player national team",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/players/5821/national-team/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "players", "5821", "national-team", ""]
            },
            "description": "National-team identifier plus aggregate caps and goals."
          }
        }
      ]
    },
    {
      "name": "Managers",
      "description": "Coaches with computed match aggregates plus tenure history.",
      "item": [
        {
          "name": "List managers",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/managers/?team_id=267",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "managers", ""],
              "query": [
                { "key": "team_id", "value": "267", "description": "Active tenure at this club" },
                { "key": "league_id", "value": "", "disabled": true },
                { "key": "nationality_code", "value": "ES", "disabled": true },
                { "key": "min_matches", "value": "50", "disabled": true },
                { "key": "tactical_profile", "value": "attacking", "description": "attacking | defensive | balanced", "disabled": true },
                { "key": "team_style", "value": "possession", "description": "possession | counter | pressing | defensive | wide | fan", "disabled": true },
                { "key": "name", "value": "", "disabled": true }
              ]
            }
          }
        },
        {
          "name": "Manager detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/managers/214/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "managers", "214", ""]
            }
          }
        },
        {
          "name": "Manager career",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/managers/214/career/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "managers", "214", "career", ""]
            },
            "description": "Tenure history at each club with date range and per-tenure record."
          }
        },
        {
          "name": "Manager matches",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/managers/214/matches/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "managers", "214", "matches", ""],
              "query": [
                { "key": "date_from", "value": "", "disabled": true },
                { "key": "date_to", "value": "", "disabled": true },
                { "key": "league_id", "value": "", "disabled": true },
                { "key": "team_id", "value": "", "description": "For managers with multiple tenures", "disabled": true },
                { "key": "status", "value": "finished", "disabled": true }
              ]
            },
            "description": "Defaults to a window of now − 3h to now + 7d when no date filters are provided."
          }
        }
      ]
    },
    {
      "name": "Referees",
      "description": "Match officials with computed aggregates over played matches.",
      "item": [
        {
          "name": "List referees",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/referees/?league_id=17&min_matches=10",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "referees", ""],
              "query": [
                { "key": "league_id", "value": "17", "description": "Aggregates scoped to this league when set" },
                { "key": "name", "value": "", "disabled": true },
                { "key": "country_code", "value": "GB", "disabled": true },
                { "key": "min_matches", "value": "10" }
              ]
            }
          }
        },
        {
          "name": "Referee detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/referees/1206/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "referees", "1206", ""]
            }
          }
        },
        {
          "name": "Referee matches",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/referees/1206/matches/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "referees", "1206", "matches", ""],
              "query": [
                { "key": "date_from", "value": "", "disabled": true },
                { "key": "date_to", "value": "", "disabled": true },
                { "key": "league_id", "value": "", "disabled": true },
                { "key": "season_id", "value": "", "disabled": true },
                { "key": "status", "value": "finished", "disabled": true }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Venues",
      "description": "Stadiums with location, capacity, pitch dimensions, and per-tournament assignments.",
      "item": [
        {
          "name": "List venues",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/venues/?country_code=GB&min_capacity=40000",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "venues", ""],
              "query": [
                { "key": "country_code", "value": "GB" },
                { "key": "city", "value": "", "disabled": true },
                { "key": "name", "value": "", "disabled": true },
                { "key": "min_capacity", "value": "40000" },
                { "key": "team_id", "value": "", "description": "Home stadium of this team", "disabled": true }
              ]
            }
          }
        },
        {
          "name": "Venue detail",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/venues/42/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "venues", "42", ""]
            },
            "description": "Single venue plus inline competition_assignments array."
          }
        },
        {
          "name": "Venue competitions",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/api/v2/venues/42/competitions/",
              "host": ["{{base_url}}"],
              "path": ["api", "v2", "venues", "42", "competitions", ""]
            },
            "description": "Paginated list of every tournament/season this venue is used in."
          }
        }
      ]
    }
  ]
}