> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Access trending songs data, rankings, and chart history

# Songs API

The Songs API provides access to trending songs data, chart rankings, and historical performance across different countries and time periods.

## Pricing

Each API call costs **10 credits**, regardless of the action performed.

## Authentication

All requests require an API key passed in the `x-ty-api-key` header.

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=countries" \
  -H "x-ty-api-key: your-api-key"
```

## Available Actions

The Songs API uses an `action` parameter to determine what data to retrieve:

| Action         | Description                         | Required Parameters         |
| -------------- | ----------------------------------- | --------------------------- |
| `countries`    | Get list of available countries     | None                        |
| `weeks`        | Get available weeks for a country   | `country_code`              |
| `date-ranges`  | Get available date ranges           | None                        |
| `rankings`     | Get song rankings for a country     | `country`, optional: `week` |
| `global`       | Get global song rankings            | Optional: `week`            |
| `new-entries`  | Get new chart entries for a country | `country`                   |
| `search`       | Search for songs                    | `q`                         |
| `song-history` | Get historical data for a song      | `song_id`, `country_code`   |
| `compare`      | Compare rankings between two weeks  | `country`, `week1`, `week2` |

## Action Examples

### Get Available Countries

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=countries" \
  -H "x-ty-api-key: your-api-key"
```

### Get Available Weeks

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=weeks&country_code=US" \
  -H "x-ty-api-key: your-api-key"
```

### Get Rankings for a Country

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=rankings&country=US&week=2026-W04" \
  -H "x-ty-api-key: your-api-key"
```

### Get Global Rankings

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=global&week=2026-W04" \
  -H "x-ty-api-key: your-api-key"
```

### Get New Chart Entries

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=new-entries&country=US" \
  -H "x-ty-api-key: your-api-key"
```

### Search Songs

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=search&q=trending" \
  -H "x-ty-api-key: your-api-key"
```

### Get Song History

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=song-history&song_id=123456&country_code=US" \
  -H "x-ty-api-key: your-api-key"
```

### Compare Two Weeks

```bash theme={null}
curl "https://api.topyappers.com/api/v1/songs?action=compare&country=US&week1=2026-W03&week2=2026-W04" \
  -H "x-ty-api-key: your-api-key"
```

## Response Format

All responses follow this structure:

```json theme={null}
{
  "message": "OK",
  "action": "rankings",
  "credits_used": 10,
  "response": {
    // Action-specific data
  }
}
```

## Week Format

Weeks are specified in ISO week format: `YYYY-Www`

* `YYYY` - Four digit year
* `W` - Literal "W"
* `ww` - Two digit week number (01-53)

Examples:

* `2026-W01` - First week of 2026
* `2026-W04` - Fourth week of 2026
* `2025-W52` - Last week of 2025

## Error Handling

If required parameters are missing, you'll receive a helpful error response:

```json theme={null}
{
  "error": "Missing required parameter: action",
  "available_actions": [
    "countries",
    "weeks", 
    "date-ranges",
    "rankings",
    "global",
    "new-entries",
    "search",
    "song-history",
    "compare"
  ],
  "example_usage": {
    "countries": "/api/v1/songs?action=countries",
    "weeks": "/api/v1/songs?action=weeks&country_code=US",
    "rankings": "/api/v1/songs?action=rankings&country=US&week=2026-W04",
    "global": "/api/v1/songs?action=global&week=2026-W04",
    "search": "/api/v1/songs?action=search&q=trending",
    "song_history": "/api/v1/songs?action=song-history&song_id=123&country_code=US",
    "compare": "/api/v1/songs?action=compare&country=US&week1=2026-W03&week2=2026-W04"
  }
}
```