Skip to main content
GET
/
api
/
v1
/
songs
Songs API
curl --request GET \
  --url https://api.topyappers.com/api/v1/songs \
  --header 'x-ty-api-key: <api-key>'
{
  "message": "OK",
  "action": "rankings",
  "credits_used": 10,
  "response": {}
}

Authorizations

​
x-ty-api-key
string
header
required

API key for TopYappers API authentication

Query Parameters

​
action
enum<string>
required

The action to perform

Available options:
countries,
weeks,
date-ranges,
rankings,
global,
new-entries,
search,
song-history,
compare
​
country
string

Country code (required for: rankings, new-entries, compare)

​
country_code
string

Country code (used for: weeks, song-history)

​
week
string

Week in ISO format (YYYY-Www) for rankings and global

​
week1
string

First week for comparison (required for: compare)

​
week2
string

Second week for comparison (required for: compare)

​
song_id
string

Song ID (required for: song-history)

​
q
string

Search query (used for: search)

Response

Successful response

​
message
string
required
Example:

"OK"

​
action
string
required

The action that was performed

Example:

"rankings"

​
credits_used
integer
required

Number of credits consumed by this request

Example:

10

​
response
object
required

The response data (varies by action)