# Billboard — 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.

> Get access to Billboard's music charts, latest news, and interviews to stay updated on chart rankings, industry stories, and artist content. Search and retrieve specific articles or page content to find the music news and information you need.

**Category:** Music | **Website:** [billboard.com/](https://billboard.com/) | **Docs:** [parse.bot/marketplace/f88193f3-460b-4033-b4a0-9a623b3f0b78/billboard-com-api](https://parse.bot/marketplace/f88193f3-460b-4033-b4a0-9a623b3f0b78/billboard-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-billboard-com-api-f88193f3/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_article

Extract the full content and metadata from a specific Billboard article URL. Returns the article title, author, publication date, and full body text. The URL must be a valid Billboard.com article page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full Billboard article URL to extract content from (e.g., https://www.billboard.com/music/music-news/taylor-swift-reveals-third-fragrance-taylor-by-taylor-swift-1565046/). |

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

### get_chart

Get Billboard chart data including song rankings, artists, and chart statistics. Supports any Billboard chart (e.g., hot-100, billboard-200, artist-100). Each entry includes rank, title, artist, last week position, peak position, weeks on chart, status (New, Re-Entry, or Stable), and trending info.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chart_name` | string | No | Billboard chart identifier as it appears in the URL path (e.g., hot-100, billboard-200, artist-100). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-billboard-com-api-f88193f3/get_chart \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chart_name":"<string>"}'
```

### get_latest_news

Get the most recent music news articles from Billboard.com. Returns paginated results sorted by publication date descending. Uses the same article format as search but without a query filter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of articles to retrieve per page. |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-billboard-com-api-f88193f3/get_latest_news \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>"}'
```

### get_page_content

Generic extractor for any Billboard URL. Automatically detects whether the URL is a chart page or an article and returns the appropriate structured data. For chart URLs (containing /charts/), returns chart rankings; for article URLs, returns article content with title, author, date, and body.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Any Billboard URL to extract content from (chart or article page). |

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

### search

Search for news articles, interviews, and other content on Billboard.com. Results are sorted by relevance when a query is provided, or by date when no query is given. Returns paginated results with article metadata including title, excerpt, author, date, categories, tags, and thumbnail URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Content category filter to narrow results. |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search query string. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-billboard-com-api-f88193f3/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","limit":"<integer>","page":"<integer>","query":"<string>"}'
```