Skip to main content

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.

​
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. 
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:
ActionDescriptionRequired Parameters
countriesGet list of available countriesNone
weeksGet available weeks for a countrycountry_code
date-rangesGet available date rangesNone
rankingsGet song rankings for a countrycountry, optional: week
globalGet global song rankingsOptional: week
new-entriesGet new chart entries for a countrycountry
searchSearch for songsq
song-historyGet historical data for a songsong_id, country_code
compareCompare rankings between two weekscountry, week1, week2

​
Action Examples

​
Get Available Countries

curl "https://api.topyappers.com/api/v1/songs?action=countries" \
  -H "x-ty-api-key: your-api-key"

​
Get Available Weeks

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

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

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

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

​
Search Songs

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

​
Get Song History

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

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: 
{
  "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: 
{
  "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"
  }
}