---
title: Get a tennis player profile
description: Search an ATP/WTA player, then pull ranking, recent matches, head-to-heads and photos.
badge: pro
---

# Get a tennis player profile

The tennis workflow mirrors football but lives under `/tennis/api/v2/` and
requires the [Sports Addon](/addons/) ($5/mo). Full reference:
[Tennis API](/docs/tennis/).

## 1. Find the player

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/tennis/api/v2/players/?search=alcaraz"
```

```json
{
  "count": 1,
  "results": [
    {
      "id": 1207, "name": "Carlos Alcaraz", "short_name": "C. Alcaraz",
      "country_code": "ES", "country_name": "Spain", "gender": "M",
      "current_ranking": { "position": 2, "points": 8805, "type": "ATP" }
    }
  ]
}
```

Filters: `search` (name), `country`, `gender` (`M`/`F`).

> **402?** Your token is valid but the Sports Addon is missing — see
> [Authentication](/docs/authentication/).

## 2. Profile detail

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/tennis/api/v2/players/1207/"
```

Adds bio fields (height, plays, turned pro, birthplace, current residence) to
the search shape.

## 3. Recent and upcoming matches

The matches list accepts a `player` filter. Without dates it defaults to the
next 7 days, so pass a date range for history:

```bash
# Upcoming matches
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sports.bzzoiro.com/tennis/api/v2/matches/?player=1207"

# Last month of results
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sports.bzzoiro.com/tennis/api/v2/matches/?player=1207&status=finished&date_from=2026-07-01&date_to=2026-08-02"
```

Each match includes tournament (with surface), round, set scores, winner and
decimal odds for both players. A match detail
(`/tennis/api/v2/matches/{id}/`) adds per-set statistics — aces, double
faults, serve percentages — and there are `/h2h/` and `/point-by-point/`
sub-resources for rivalry blocks and rally-level views.

## 4. Ranking history and context

```bash
# Current ATP top 100
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/tennis/api/v2/rankings/?type=ATP&limit=100"
```

`type` is `ATP` or `WTA`; pass `date` (`YYYY-MM-DD`) for a historical
snapshot. Cached ~5 minutes.

## 5. Predictions (optional)

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/tennis/api/v2/predictions/?upcoming=true"
```

Model win probabilities per match — useful for a "form outlook" widget.

## 6. Photo

```
https://sports.bzzoiro.com/img/tennis/player/1207/
https://sports.bzzoiro.com/img/tennis/player/1207/?bg=transparent
```

No auth needed; cached for you. See [Image API](/docs/images/).

## Putting it together

| Section | Request | Suggested cache |
|---|---|---|
| Header/bio + ranking | `/tennis/api/v2/players/{id}/` | 1 hour |
| Upcoming matches | `/tennis/api/v2/matches/?player={id}` | 60 s |
| Results | `…&status=finished&date_from=…` | 10 min |
| Rankings table | `/tennis/api/v2/rankings/?type=ATP` | 1 hour |
| Photo | `/img/tennis/player/{id}/` | handled for you |

Want live scores on the page? The tennis WebSocket channel streams
point-by-point — see [Tennis live channel](/docs/websocket/tennis/).