Wraps the free TheSportsDB API for team logos, player photos, and stadium info. No API key, no signup.
Quick Start
sports-skills metadata get_team_logo --team_name="Arsenal"
sports-skills metadata get_team_info --team_name="Real Madrid"
sports-skills metadata get_player_photo --player_name="Messi"
sports-skills metadata search_teams --query="Manchester"
sports-skills metadata search_players --query="LeBron"
Python SDK:
from sports_skills import metadata
metadata.get_team_logo(team_name="Arsenal") metadata.get_team_info(team_name="Real Madrid") metadata.get_player_photo(player_name="Messi") metadata.search_teams(query="Manchester") metadata.search_players(query="LeBron")
## CRITICAL: Before Any Query
CRITICAL: Before calling any metadata command, verify:
- Team names use the **full official name** — especially for NBA (e.g., `"Los Angeles Lakers"`, **not** `"Lakers"`).
- For `get_team_logo`, the `sport` parameter defaults to `"Soccer"`. Pass `sport="Basketball"`, `"American Football"`, `"Baseball"`, `"Ice Hockey"`, `"Motorsport"`, or `"Cricket"` when the team is not a soccer team — otherwise the lookup falls back to a close name match in any sport. If no result is close to the requested name, it returns an error listing what TheSportsDB offered.
- Player searches use just the player name (e.g., `"Messi"`, `"LeBron James"`, `"Tiger Woods"`).
## Coverage
**Teams (logos, banners, stadium info):**
- Soccer: 100+ leagues worldwide (Premier League, La Liga, Bundesliga, Serie A, MLS, and many more)
- NFL (American Football)
- NBA (Basketball) — requires full team names
- MLB (Baseball)
- NHL (Ice Hockey)
- F1 (Motorsport)
- Cricket (IPL, international)
**Players (photos, bios):**
- All team sports above
- Tennis (ATP/WTA players)
- Golf (PGA/LPGA players)
**Not covered:** MMA/UFC, Rugby, Esports, Boxing.
## Commands
| Command | Required | Optional | Description |
|---|---|---|---|
| `get_team_logo` | team_name | sport | Team logo / badge URL |
| `get_team_info` | team_name | | Full team info: stadium, description, social links, banner |
| `get_player_photo` | player_name | | Player photo URL |
| `search_teams` | query | | Fuzzy search for teams across sports |
| `search_players` | query | | Fuzzy search for players across sports |
## Workflows
### Enrich a Standings Response
1. Call the sport-specific skill (e.g., `football get_season_standings`) for the standings table.
2. For each team in the standings, call `get_team_logo --team_name=<name>` to attach a badge URL.
3. Render the standings with logos alongside team names.
### Build a Team Profile Page
1. Call `get_team_info --team_name="<name>"` for stadium, description, founding year, social links.
2. The same response includes `badge` and `banner` URLs — no second call needed.
### Resolve an Ambiguous Team Name
1. Call `search_teams --query="<partial-name>"` to disambiguate.
2. Use the exact `name` field from the result for follow-up `get_team_info` calls.
## Examples
Example 1: Get a Premier League team logo
User says: "What does the Arsenal logo look like?"
Actions:
1. Call `get_team_logo(team_name="Arsenal")` — `sport` defaults to "Soccer", which is correct here.
Result: Logo URL, sport, league, and country.
Example 2: NBA team — full name required
User says: "Get the Lakers logo"
Actions:
1. Call `get_team_logo(team_name="Los Angeles Lakers", sport="Basketball")` — both the full name AND the sport filter are needed.
Result: Lakers badge from the NBA branch of TheSportsDB.
Example 3: Player photo
User says: "Show me a photo of Messi"
Actions:
1. Call `get_player_photo(player_name="Messi")`.
Result: Player photo URL, sport, team, and nationality.
Example 4: Disambiguate "Manchester"
User says: "Find me Manchester teams"
Actions:
1. Call `search_teams(query="Manchester")`.
Result: List of teams matching "Manchester" — Manchester United, Manchester City, etc. — each with sport, league, and country.
## Commands that DO NOT exist — never call these
- ~~`get_stadium_info`~~ — does not exist. Stadium info is included in `get_team_info`.
- ~~`get_league_logo`~~ — does not exist. Use `get_team_logo` for team badges only.
- ~~`get_player_stats`~~ — does not exist on this skill. TheSportsDB metadata does not include stats; use the sport-specific skill (e.g., `football get_player_profile`, `nba get_player_stats`).
- ~~`search_leagues`~~ — does not exist.
If a command is not listed in the Commands table above, it does not exist.
## Troubleshooting
Error: `get_team_logo` returns the wrong team
Cause: A short or ambiguous team name (e.g., "Lakers", "Arsenal") matched a different sport first
Solution: Pass an explicit `sport` parameter and use the team's full official name
Error: `get_team_logo` / `get_team_info` say "No team named ... found"
Cause: TheSportsDB's free search returned only teams whose names are not close to the query (e.g. "St. Louis Cardinals" -> "Louisville")
Solution: Use the team's full official name, or `search_teams --query=<partial>` to find it
Error: `get_player_photo` returns null / empty
Cause: Player not in TheSportsDB, or the name spelling differs (e.g., "Cristiano Ronaldo" vs "Ronaldo")
Solution: Use `search_players --query=<partial>` first to find the canonical spelling, then retry
Error: Logo URL works but the image is low resolution
Cause: TheSportsDB returns the badge as-is from contributors
Solution: This is an upstream limitation. Most badges are 200×200 or larger; very small icons indicate a low-quality submission. No workaround.
Error: "TheSportsDB rate limit: the free API key allows 30 requests per minute" (`status_code: 429`)
Cause: The free key answers HTTP 429 from the 31st request in a minute, then locks out for about 2 minutes. The client paces itself below that (bursts of 5, then about one request every 2.4 s), so this error means a long batch outran the pacing or another process shares the key
Solution: Wait for the time in the message, then retry. Repeated lookups are cached for 5 minutes, so reuse earlier results rather than re-querying in a loop