Metadata-Version: 2.4
Name: sportscore
Version: 0.2.0
Summary: Python client for the free SportScore sports-data API (football, basketball, cricket, tennis).
Project-URL: Homepage, https://sportscore.com/developers/
Project-URL: Documentation, https://sportscore.com/developers/api/
Project-URL: API Spec, https://sportscore.com/developers/openapi.yaml
Project-URL: Repository, https://github.com/Backspace-me/sportscore-py
Project-URL: Bug Tracker, https://github.com/Backspace-me/sportscore-py/issues
Project-URL: Attribution Badges, https://sportscore.com/developers/#badges
Author-email: SportScore <api@sportscore.com>
License: MIT License
        
        Copyright (c) 2026 SportScore
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
License-File: NOTICE
Keywords: api,basketball,cricket,football,live-scores,soccer,sports,sportscore,standings,tennis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# sportscore

Python client for the free **[SportScore](https://sportscore.com/)** sports-data
API — live scores, match details, standings, top scorers, brackets and
player stats across football, basketball, cricket and tennis.

[![PyPI version](https://img.shields.io/pypi/v/sportscore.svg)](https://pypi.org/project/sportscore/)
[![Python versions](https://img.shields.io/pypi/pyversions/sportscore.svg)](https://pypi.org/project/sportscore/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

- **No API key.** CORS-open. Free forever for reasonable usage (~10,000 req
  / 24h / IP).
- **Free in exchange for one thing:** a visible
  [`"Powered by SportScore"`](https://sportscore.com/developers/#badges)
  dofollow backlink on any page that renders the data. Commercial /
  white-label (no attribution) available at
  [sportscore.com/developers/terms/](https://sportscore.com/developers/terms/).
- **Sync + async**, typed, `py.typed` shipped.

## Install

```bash
pip install sportscore
```

Requires Python 3.9+.

## Quickstart

### Sync

```python
from sportscore import SportScoreClient

with SportScoreClient() as sc:
    matches = sc.get_matches("football", limit=5)
    for m in matches["data"]:
        print(m["home_team"], m["score"], m["away_team"])

    standings = sc.get_standings("football", "premier-league")
    scorers = sc.get_top_scorers("football", "premier-league", limit=10)
    messi = sc.get_player("football", "lionel-messi")

    # Surface the free-tier attribution line anywhere you render the data:
    print(sc.attribution_html())
    # <a href="https://sportscore.com/" rel="dofollow" ...>Powered by SportScore</a>
```

### Async

```python
import asyncio
from sportscore import AsyncSportScoreClient

async def main():
    async with AsyncSportScoreClient() as sc:
        matches = await sc.get_matches("basketball", limit=3)
        print(matches)

asyncio.run(main())
```

## API surface

Every method returns the parsed JSON body from the SportScore API. Non-2xx
responses raise `SportScoreError` with `status_code`, `body`, and `url`
attributes.

| Method | Description |
| --- | --- |
| `get_matches(sport, limit=10)` | Live + recent matches for a sport |
| `get_match_detail(sport, slug)` | Full data for one match |
| `get_team_schedule(sport, slug, limit=10)` | Team fixtures (past + upcoming) |
| `get_standings(sport, slug)` | League / competition table |
| `get_top_scorers(sport, slug, limit=20, stat="goals")` | Top scorers or assisters |
| `get_player(sport, slug)` | Player stats + metadata |
| `get_bracket(sport, slug)` | Knockout tournament bracket |
| `get_tracker(sport, match_id)` | Live match tracker (football) |

`sport` is one of `"football"`, `"basketball"`, `"cricket"`, `"tennis"`.

## Configuration

```python
SportScoreClient(
    api_base="https://sportscore.com",
    user_agent="my-app/1.0",
    timeout=15.0,
    http_client=None,  # pass your own httpx.Client if you want pooling
)
```

No API keys, no required env vars.

### Anonymous install-ping (opt-out)

On the first `SportScoreClient()` instantiation per process, the library
fires **one** fire-and-forget POST to `https://sportscore.com/api/mcp/ping/`
on a background thread:

```json
{
  "client": "sportscore-py",
  "version": "0.2.0",
  "transport": "python",
  "host": "linux",
  "python": "3.12.1"
}
```

That's the whole payload — no user id, no IP, no cookies, no per-call
telemetry. We use it to see rough weekly-active-installs and Python/OS
spread so we know what to support. The ping runs on a daemon thread and
has a 3 s timeout — it cannot delay your program.

Opt out by setting `SPORTSCORE_NO_TELEMETRY=1` in your environment:

```bash
export SPORTSCORE_NO_TELEMETRY=1
```

## Attribution — how the free tier works

The service is free in exchange for a visible dofollow backlink to
`https://sportscore.com/` on any page that renders the returned data. The
client ships helpers so the one line of code you need is literally one line:

```python
client.attribution_html()
# <a href="https://sportscore.com/" rel="dofollow" title="Sports data by SportScore">Powered by SportScore</a>
```

Prefer a pre-designed badge? Pick any of the six variants (dark pill, light
pill, minimal, tiny circle, amber accent, stat-block footer) at
[sportscore.com/developers/#badges](https://sportscore.com/developers/#badges).

Full terms: [sportscore.com/developers/terms/](https://sportscore.com/developers/terms/).

Commercial / white-label removal: `api@sportscore.com`.

## Error handling

```python
from sportscore import SportScoreClient, SportScoreError

with SportScoreClient() as sc:
    try:
        sc.get_standings("football", "made-up-league")
    except SportScoreError as exc:
        print(exc.status_code, exc.body)
```

## Related projects

- [`sportscore-mcp`](https://github.com/Backspace-me/sportscore-mcp) — the
  same 8-tool surface exposed as a Model Context Protocol server for Claude,
  Cursor, Zed, etc.
- [OpenAPI spec](https://sportscore.com/developers/openapi.yaml) — full
  REST spec if you'd rather skip the client altogether.
- [Interactive API reference](https://sportscore.com/developers/api/) —
  Redoc-rendered docs with live "Try it" for every endpoint.

## Contributing

Bugs, PRs, and example code all welcome:
[github.com/Backspace-me/sportscore-py](https://github.com/Backspace-me/sportscore-py).

Run the tests:

```bash
pip install -e ".[dev]"
pytest
```

## License

[MIT](./LICENSE) — client code.
Remote API usage is governed by the [SportScore API Terms of Use](https://sportscore.com/developers/terms/).
