API Reference

Build your own music dashboards and applications powered by pure, unadulterated listening data. No algorithms, no AI push—just raw global scrobbles.

Overview

The Echo Charts API is a RESTful JSON interface providing aggregated charting data. All endpoints are publicly accessible and return data in a consistent JSON format.

Base URL

https://stats.echomusic.fun/api/v1

Authentication & Rate Limiting

Currently, no API key is required to access the v1/trending endpoints. However, to ensure fair usage, we enforce strict rate limits based on your IP address.

Limit Type Quota Window
Global Rate Limit 60 requests 1 minute
Burst Limit 10 requests 1 second

Note If you exceed these limits, the API will return a 429 Too Many Requests status.

Endpoints

GET/trending

Fetches the current trending music data. This endpoint is highly customizable, allowing you to fetch tracks, artists, albums, or all combined, filtered by region.

Query Parameters

Parameter Type Required Description
type string Yes Specifies the entity to fetch. Allowed values: tracks, artists, albums, all.
limit integer No Number of results to return. Default is 10. Max is 50.
country string No Filter results by region (e.g., united states, japan). If omitted, returns global charts.

Example Request

curl -X GET "https://stats.echomusic.fun/api/v1/trending?type=tracks&limit=5&country=japan" \ -H "Accept: application/json"

Example Response

{ "success": true, "timestamp": "2026-07-14T11:32:00Z", "data": { "tracks": [ { "rank": 1, "title": "Blinding Lights", "artist": "The Weeknd", "listeners": 1540324, "playcount": 34910243, "coverUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/.../300x300bb.jpg", "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/..." }, { "rank": 2, "title": "Shape of You", "artist": "Ed Sheeran", "listeners": 1420102, "playcount": 31201944, "coverUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music125/.../300x300bb.jpg", "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/..." } ] } }
GET/historical

Fetches the top charts for a historical time period (e.g., specific decades or years).

Query Parameters

Parameter Type Required Description
period string Yes The historical timeframe. Examples: 2010s, 2000s, 1990s.
limit integer No Number of results to return. Default is 10. Max is 50.

Errors

The API uses standard HTTP status codes to indicate the success or failure of an API request.

Status Code Meaning
200 OK - The request was successful.
400 Bad Request - Missing or invalid parameters.
429 Too Many Requests - You have hit the rate limit.
500 Internal Server Error - Upstream API failure (Last.fm/iTunes).