# TheSportsDB Scraper — Teams, Players & Events API (`bovi/sportsdb-scraper`) Actor

Scrape teams, players, and match events from TheSportsDB official free API. Search teams by name or league, find players, and retrieve upcoming or past match results with scores. No proxy, no auth required. Supports optional premium API key. Pay per result.

- **URL**: https://apify.com/bovi/sportsdb-scraper.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.10 / 1,000 thesportsdb scraper — teams, players & match results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TheSportsDB Scraper — Teams, Players & Match Results | $2/1K | Free API

**For sports app developers, fantasy sports platforms, betting data pipelines, and sports analytics teams** that need clean, structured multi-sport data without managing API auth and rate limits.

**$2.00 per 1,000 results (teams, players, or match events).** Zero proxy cost — TheSportsDB has a public free API. Bring your own premium key for higher rate limits.

This actor calls TheSportsDB's official public API. No scraping, no access friction — pure structured JSON from the source. One actor, 20+ sports.

| Source | Cost | Structured JSON? | MCP-ready? | Multi-sport? |
|---|---|---|---|---|
| **This actor** | $2/1k | Yes | Yes | Yes |
| TheSportsDB directly | Free (rate-limited) | Yes | No | Yes |
| SportRadar API | $$$ (enterprise) | Yes | No | Yes |
| RapidAPI sports APIs | $5-50/mo | Partial | No | Partial |

Scrape sports data from **TheSportsDB** official free API. Search teams by name or
league, find players, and retrieve upcoming or past match results — all via the
official public JSON API with no proxy, no authentication, and zero COGS.

### Features

- **Teams** — search any team by name or browse all teams in a league. Returns team
  metadata: ID, sport, league, country, stadium, founding year, badge image URL.
- **Players** — search players by name. Returns position, nationality, DOB, status,
  photo URL.
- **Events** — retrieve upcoming or past match events for given team IDs. Past events
  include final scores; upcoming events show venue and kickoff date.
- **parse\_confidence** — every row carries a quality score (0.0–1.0) and a warnings
  list so you can detect drift or incomplete records automatically.
- **Optional API key** — works out of the box with the free public test key `3`. Supply
  your own premium key for higher rate limits.
- **Pay per result** — you only pay for records returned, not for empty pages.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `teams` | `teams` / `players` / `events` |
| `searchQueries` | string\[] | `["Arsenal"]` | Team or player names to search |
| `leagues` | string\[] | `[]` | League names to browse all teams for |
| `teamIds` | string\[] | `[]` | Team IDs for event mode |
| `eventType` | string | `next` | `next` (upcoming) or `last` (past with scores) |
| `maxItems` | integer | `100` | Max total items (0 = unlimited) |
| `apiKey` | string | *(test key)* | Optional premium API key |
| `requestDelayMs` | integer | `200` | ms between requests |

### Output schema

Every row has `entity_type` = `"team"` / `"player"` / `"event"` plus these fields:

| Field | Populated for |
|---|---|
| `name` | all |
| `team_id` / `event_id` / `player_id` | respective entity type |
| `sport` | all |
| `league` | teams, events; also holds team name for players |
| `country` / `nationality` | teams / players |
| `stadium` / `formed_year` / `badge_url` | teams |
| `position` / `date_of_birth` / `player_status` / `photo_url` | players |
| `date` / `home_team` / `away_team` / `home_score` / `away_score` / `venue` / `event_status` | events |
| `parse_confidence` | all (1.0 = all fields present) |
| `warnings` | all (list of missing-field codes) |

### Example: get all Premier League teams

```json
{
  "mode": "teams",
  "leagues": ["English Premier League"]
}
```

### Example: get upcoming Arsenal matches

```json
{
  "mode": "events",
  "teamIds": ["133604"],
  "eventType": "next"
}
```

### Pricing

Pay per result (`sports-item` event). Default: **$2.00 per 1,000 records**.

**Pricing example:** All 20 Premier League teams = **$0.04**. 5 teams × upcoming 5 events each = 25 events = **$0.05**. 1,000 player records = **$2.00**.

### FAQ

**Do I need an API key or proxy?** No. The actor works out of the box with TheSportsDB's free public test key `3` — no account, no proxy, no extra setup. Optionally supply your own premium key for higher rate limits.

**What sports are covered?** TheSportsDB covers 20+ sports: soccer, basketball, baseball, American football, hockey, tennis, cricket, rugby, and more. Use `mode=teams` with a league name to see all teams for any sport.

**How do I find a team ID?** Run `mode=teams` with `searchQueries: ["Arsenal"]` — the response includes `team_id` (e.g. `133604`). Use that ID in `mode=events` to get match results.

**What happens if a query returns no results?** The actor logs a warning and continues to the next query — it never crashes. Empty results are not charged.

**Can I export results to Google Sheets or Airtable?** Yes — connect via the n8n or Make integration, or use the Apify dataset export (JSON, CSV, or Excel).

### Data source

[TheSportsDB](https://www.thesportsdb.com) — community-built sports database with
official REST API. Free test key `3` is publicly documented. Not affiliated with
TheSportsDB.

### parse\_confidence trust score

Every row carries a `parse_confidence` score (0.0–1.0) and a `warnings` list so you can detect drift or incomplete records automatically.

### Use with AI agents (MCP)

This actor is available as an MCP tool for Claude, GPT-4o, or any MCP-compatible agent.

Config: https://mcp.apify.com/?tools=bovi/sportsdb-scraper

### Integrations

Built for sports-app developers, fantasy platforms, and analytics teams ingesting multi-sport team, player, and match data — the JSON/dataset output drops into the tools you already run, no glue code:

- **n8n / Make / Zapier** — trigger a run or pipe every new dataset item into 500+ apps (Google Sheets, Airtable, Slack, HubSpot, your database) with no code: [n8n](https://docs.apify.com/platform/integrations/n8n), [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier).
- **Webhooks** — fire your own endpoint the moment a run finishes, to push results straight into your pipeline ([docs](https://docs.apify.com/platform/integrations/webhooks)).
- **MCP server** — expose this actor as a tool to Claude, Cursor, or any [MCP client](https://mcp.apify.com) so an AI agent can pull this data mid-conversation ([guide](https://blog.apify.com/how-to-use-mcp/)).
- **API & SDKs** — fetch the dataset as JSON, CSV, or Excel through the Apify REST API or the Python / JS SDKs.

See all [Apify integrations](https://apify.com/integrations).

### Legal

TheSportsDB data is community-maintained and publicly documented under their API terms.
Scraping public API endpoints of a service that explicitly provides a public API key
for that purpose is consistent with standard API usage.

# Actor input Schema

## `mode` (type: `string`):

What to scrape. teams: search teams by name or browse all teams in a league. events: get upcoming or recent match events for given team IDs. players: search players by name.

## `searchQueries` (type: `array`):

For mode=teams: team names to search (e.g. Arsenal, Lakers). For mode=players: player names to search (e.g. Ronaldo, Messi). Each query runs separately.

## `leagues` (type: `array`):

For mode=teams: league names to retrieve all teams for (e.g. 'English Premier League', 'NBA'). Each league is fetched separately. Leave empty if using searchQueries instead.

## `teamIds` (type: `array`):

For mode=events: TheSportsDB numeric team IDs. Example: '133604' for Arsenal, '134843' for Liverpool. Run mode=teams first to discover IDs.

## `eventType` (type: `string`):

For mode=events: next fetches upcoming events (no scores), last fetches recent past events (with scores).

## `maxItems` (type: `integer`):

Maximum total items to return across all queries. 0 = no limit. Default 100.

## `apiKey` (type: `string`):

TheSportsDB API key. Leave blank to use the free test key (3). Register at thesportsdb.com/api.php for a premium key with higher rate limits.

## `requestDelayMs` (type: `integer`):

Milliseconds to wait between API requests. Default 200ms is safe with the free key. Increase to 500ms+ if you see rate-limit errors.

## Actor input object example

```json
{
  "mode": "teams",
  "searchQueries": [
    "Arsenal"
  ],
  "teamIds": [
    "133604"
  ],
  "eventType": "next",
  "maxItems": 100,
  "requestDelayMs": 200
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing Sportsdb Scraper records (entity\_type, name, sport, league, country, date, home\_team, away\_team, home\_score, away\_score, status, parse\_confidence).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "teams",
    "searchQueries": [
        "Arsenal"
    ],
    "teamIds": [
        "133604"
    ],
    "eventType": "next",
    "maxItems": 100,
    "requestDelayMs": 200
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/sportsdb-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "teams",
    "searchQueries": ["Arsenal"],
    "teamIds": ["133604"],
    "eventType": "next",
    "maxItems": 100,
    "requestDelayMs": 200,
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/sportsdb-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "teams",
  "searchQueries": [
    "Arsenal"
  ],
  "teamIds": [
    "133604"
  ],
  "eventType": "next",
  "maxItems": 100,
  "requestDelayMs": 200
}' |
apify call bovi/sportsdb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bovi/sportsdb-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/LXlXfqoSwHpY7NHcD/builds/AZCufDbXjFpfewo8K/openapi.json