# Rate Your Music — 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.

> Search for albums, artists, and genres to retrieve detailed information including release dates, ratings, and chart rankings from Rate Your Music. Browse music charts and explore genre-specific data to discover trends across the catalog.

**Category:** Music | **Website:** [rateyourmusic.com/](https://rateyourmusic.com/) | **Docs:** [parse.bot/marketplace/9949f5df-9804-46be-be85-52d6f118486c/rateyourmusic-com-api](https://parse.bot/marketplace/9949f5df-9804-46be-be85-52d6f118486c/rateyourmusic-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-rateyourmusic-com-api-9949f5df/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_artist_details

Extract detailed artist information and discography from an artist page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Artist URL path (e.g. /artist/radiohead). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/get_artist_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_charts

Extract charts data for albums or tracks. Returns paginated results with 40 items per page. Supports filtering by media type, chart type, and year.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chart_type` | string | No | Type of chart. |
| `media_type` | string | No | Type of media. |
| `page` | integer | No | Page number for pagination (1-indexed). |
| `year` | string | No | Year or year range (e.g. 2024, 2020-2024, all-time). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/get_charts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chart_type":"<string>","media_type":"<string>","page":"<integer>","year":"<string>"}'
```

### get_genre_details

Extract detailed genre information including description and parent genres from the genre hierarchy.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Genre URL path (e.g. /genre/art-rock/). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/get_genre_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_genres

Lists all music genres available on the site.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/get_genres \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_release_details

Extract detailed album/release information including tracklisting and metadata. Returns title, artist, genre classification (with separate primary genres, secondary genres, and movements), tracklist with durations, descriptors, and rating information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Release URL path (e.g. /release/album/kendrick-lamar/to-pimp-a-butterfly/). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/get_release_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_song_details

Extract song-level metadata including the song's own genre classification. Returns title, artist info, and genre tags (primary and secondary) as classified independently for the song page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Song URL path (e.g. /song/john-mayer/in-your-atmosphere/). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/get_song_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### search

Search for artists, releases, or genres on Rate Your Music.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword. |
| `search_type` | string | No | Search type filter. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-rateyourmusic-com-api-9949f5df/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","search_type":"<string>"}'
```