# FIDE Ratings — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Find chess players and track their FIDE ratings, rankings, and performance history by searching the official ratings database or browsing the world's top-ranked players. Get detailed player profiles with complete rating trends and game statistics to analyze any player's competitive record.

**Category:** Sports | **Website:** [ratings.fide.com/](https://ratings.fide.com/) | **Docs:** [parse.bot/marketplace/6bbce1ef-d137-46c5-ba78-fda6015026e1/ratings-fide-com-api](https://parse.bot/marketplace/6bbce1ef-d137-46c5-ba78-fda6015026e1/ratings-fide-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-ratings-fide-com-api-6bbce1ef/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_player_profile

Retrieve complete profile information for a player by FIDE ID, including ratings across all time controls, ranking history, game statistics (wins/draws/losses by color and time control), opponents list, and top ranking records. The profile also includes the player's photo, title, federation, and birth year.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fide_id` | string | Yes | The unique FIDE ID of the player (numeric string, e.g. 1503014) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-ratings-fide-com-api-6bbce1ef/get_player_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fide_id":"<string>"}'
```

### get_player_titles

Retrieve a player's non-playing FIDE titles and designations (arbiter, trainer, etc.) by their FIDE ID. Returns the player's name and a list of titles/designations from the 'FIDE Arbiter/Trainer' section of their profile, including license level, license status, and title entries such as National Arbiter (NA), FIDE Arbiter (FA), International Arbiter (IA), and trainer designations. Returns an empty titles array if the player has no non-playing titles.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fide_id` | string | Yes | The unique FIDE ID of the player (numeric string, e.g. 1503545) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-ratings-fide-com-api-6bbce1ef/get_player_titles \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fide_id":"<string>"}'
```

### get_top_players

Fetch the top 100 players list for a given category. Returns rank, name, FIDE ID, federation, rating, and birth year for each player. The category determines which ranking list is returned (e.g. open, women, juniors). Results are ordered by rank descending.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Ranking category. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-ratings-fide-com-api-6bbce1ef/get_top_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>"}'
```

### search_players

Search for players in the FIDE database by name or FIDE ID. Returns all matching players with their title, federation, ratings across all time controls (standard, rapid, blitz), and birth year. Partial name matches are supported.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query (player name or FIDE ID) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-ratings-fide-com-api-6bbce1ef/search_players \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```