sportapi-python

Official Python client for the SportAPI Sport Line API — Prematch and Live sports odds, scores and live statistics, with typed models and a demo mode that works without an API key.

from sportapi import SportAPI

api = SportAPI()                                  # no key yet? demo data
match = api.event(746146992, "live")
print(match.name, match.score_full)               # Arsenal — Coventry City 3:0
print(match.outcome("Total", "Over 3.5").odds)    # 1.23

The library is free and MIT-licensed. The SportAPI data service it talks to is a commercial product: live data needs a personal API key (how to get one).

Features

• Every documented Sport Line endpoint: menu, events, the match calendar, event, search, plus the optional sports, countries, tournaments, topmatches, toplist, topchampionships and account.
• Typed models (dataclasses, py.typed) for sports, countries, tournaments, matches, markets, outcomes, live statistics, sub-events and account keys. The original JSON is kept in .raw.
• Demo mode: without credentials the client serves the full example responses published in the SportAPI documentation, so you can build and test before you have a key.
• Documented errors as exceptions: InvalidKeyError, KeyExpiredError, LanguageNotAvailableError, GameFinishedError… mapped from error_code / error_message and from event service messages, not just from HTTP status codes.
• Odds helpers: find markets and outcomes by name or group_id, decimal odds, blocked selections, oc_pointer lookups, the API's column layout preserved.
• Polite polling: watch_events() / watch_event() and poll() follow the documented minimum intervals and back off 5 → 10 → 20 → 40 s on temporary failures only.
• Sync and async clients (SportAPI, AsyncSportAPI) on top of httpx. Python 3.9+.

Install

pip install sportapi

Quick start (60 seconds, no key needed)

With no SPORTAPI_KEY / SPORTAPI_BASE_URL set, the client runs in demo mode and emits one SportAPIDemoWarning, so demo data is never mistaken for live data.

from sportapi import LIVE, SportAPI

with SportAPI() as api:
    # 1. Navigation: sports -> countries -> tournaments that have matches right now
    for sport in api.menu(LIVE)[:3]:
        print(sport.name, sport.counter)

    # 2. Live football matches, grouped by tournament, with a short list of main markets
    for group in api.events(1, LIVE):
        for match in group.matches:
            print(f"{match.timer // 60:>3}' {match.score_full}  {match.name}")

    # 3. One match with every market, live statistics and sub-events
    match = api.event(746146992, LIVE)
    total = match.market("Total")
    for over, under in zip(*total.column_outcomes):   # columns as arranged by the API
        print(over.name, over.odds, "|", under.name, under.odds)
    print(match.stat(29))                             # Stat(id=29, name='Possession %', ...)

Demo mode answers exactly the requests that have a published example response (all in English):

odds=False is emulated on top of these files. Any other call raises DemoDataUnavailableError with the list of available calls and how to switch to live data.

Live data

You get a personal base URL and an API key from the SportAPI manager. Set them as environment variables (or pass them to the constructor):

export SPORTAPI_BASE_URL="https://YOUR_API_DOMAIN"
export SPORTAPI_KEY="your-api-key"

from sportapi import SportAPI

api = SportAPI()                     # reads SPORTAPI_KEY and SPORTAPI_BASE_URL
# or: SportAPI(api_key="...", base_url="https://YOUR_API_DOMAIN", lang="en")

print(api.account().current_key.days_left)
print(api.key_expires)               # from the X-Key-Expires header of the last response

• The key is sent only in the Package HTTP header — never in the URL — and is hidden from repr() and exception messages. Keep it in environment variables or a secrets manager, and call the API from your backend, not from a browser.
• Setting only one of the two variables raises ConfigurationError; SportAPI(demo=False) refuses to fall back to demo data.
• lang is any language enabled for your key. The API supports 69 languages with SportAPI-specific codes (for example ua, cn, br); see Languages.

Step-by-step setup: Authentication and access.

API coverage

line_type is "live" or "line" (Prematch); the constants LIVE, LINE and PREMATCH are exported. lang defaults to the client's lang ("en"). AsyncSportAPI has the same methods as coroutines.

Helpers: iter_live_matches(), watch_events(), watch_event(), iter_matches(), poll() / apoll(), recommended_interval(), and icon URLs in sportapi.media (media assets).

Working with odds

match = api.event(730321837, "line")

w1 = match.outcome("1X2", "W1")          # case-insensitive market and outcome names
w1.odds, w1.odds_decimal                 # 1.525, Decimal('1.525')
w1.blocked                               # oc_block: True means unavailable
w1.pointer                               # oc_pointer: '730321837|1|1|0'

match.market(id=17)                      # by group_id (names are localised)
match.find_markets("Fouls")              # several markets can share a name
match.outcome_by_pointer(w1.pointer)     # track a selection across refreshes
[o.size_value for o in match.market("Total").outcomes]   # oc_size as float (str or int in JSON)

• events returns a short market list per match (Market.column_outcomes is None); event returns all markets with columns already arranged and sorted by the API.
• Market sets differ by sport: don't assume 1X2 or a draw exists (tennis has none).
• oc_pointer identifies a selection for bet placement with the SportAPI Coupon API; see Bet pointer.

Data models: match · odds · live statistics · sub-events · field reference.

Polling and update intervals

The API is REST: each response is a snapshot. The documented minimum intervals are built in:

from sportapi import LIVE, GameFinishedError, SportAPI

api = SportAPI()
try:
    for match in api.watch_event(746146992, LIVE):     # every 5 s, never overlapping
        print(match.score_full, match.timer // 60)
except GameFinishedError:
    print("No longer in the line under this game_id: refresh the match list")

watch_* refuses intervals below the documented minimum. Temporary failures (network, HTTP 5xx) back off 5 → 10 → 20 → 40 s; key, language, sport and parameter errors are raised, not retried. Update a displayed match clock locally from timer instead of polling every second. Details: Data update guidelines.

Errors

SportAPIError
├── ConfigurationError, DemoDataUnavailableError
├── TransportError                       network error or timeout (retryable)
├── UnexpectedResponseError
│   └── HTTPStatusError                  HTTP 4xx/5xx without error_code (5xx retryable)
├── APIError                             error_code + error_message
│   ├── AuthenticationError              MissingKeyError, InvalidKeyError, KeyExpiredError,
│   │                                    KeyBlockedError, KeyNotActiveError, AccessRestrictedError
│   ├── PermissionDeniedError            AccessDeniedError, LanguageNotAvailableError
│   └── InvalidRequestError              InvalidLanguageError, InvalidLineTypeError
└── EventUnavailableError                GameNotFoundError, GameFinishedError

An empty list is not an error: nothing is available for that request right now. See Error handling.

Examples

All examples run in demo mode out of the box:

python examples/live_board.py
python examples/match_odds.py 730321837 --line

Documentation

• Quick start · Core concepts · Integration guide
• API methods overview · Full JSON responses · Sports and sport_id values
• SportAPI documentation — Sport Line API, Coupon API and more

Get an API key

Live data requires a personal base URL and API key. Plans start from $30/month, and there is a free 2-day trial.

• Request access from the SportAPI manager on Telegram: @sportapinet_bot
• Product page: Sport Line API on sportapi.net
• Related: bet placement and settlement, results

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Please never include an API key in an issue, log or test fixture.

License

MIT © 2026 SportAPI