🎵 Unofficial Gaana API

A REST API wrapper for Gaana music streaming, built with Hono, Bun, and TypeScript. Provides access to songs, albums, playlists, artists, trending tracks, charts, and new releases metadata.

⚠️ Educational & Research Purpose Only: This project is created solely for educational and research purposes. It is a learning project to understand API development, web scraping concepts, and TypeScript/Bun ecosystem. This is not an official Gaana API. Use responsibly and respect Gaana's terms of service. The authors are not responsible for any misuse of this project.

✨ Features

✅ Unified Search - Search across all content types (songs, albums, playlists, artists)
✅ RESTful Endpoints - Clean, standard REST API design
✅ Detailed Info - Full metadata for songs, albums, playlists, and artists
✅ Stream URLs - Get decrypted HLS stream URLs for tracks
✅ URL Support - Accept both seokeys and full Gaana URLs for detail endpoints
✅ Trending & Charts - Get trending tracks and top charts
✅ New Releases - Browse new releases by language
✅ Type-Safe - Full TypeScript support
✅ Serverless Ready - Deploy directly to Vercel

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/notdeltaxd/Gaana-API.git
cd Gaana-API

# Install dependencies
bun install
# or
npm install

Development

# Start development server
bun run dev

# API will be available at http://localhost:3000/api

Deployment to Vercel

One-click deployment: Click the button above to deploy instantly to Vercel.

Manual deployment:

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel deploy

⚠️ Important - Set Function Region to Mumbai:

Since Gaana is an Indian music streaming platform, it's recommended to host your project in the Mumbai region for better performance:

Go to your Vercel project dashboard
Navigate to Settings → Functions
Under Function Region, select Asia Pacific (Mumbai) - ap-south-1
Unselect the default region
Click Save Changes
Redeploy your project

This ensures faster API response times when accessing Gaana's servers.

🔐 Authentication

If API_KEY is configured in your environment, all requests to /api/* endpoints must include a valid token. The API uses timing-safe comparison to protect against side-channel attacks and supports multiple API keys.

Unauthorized requests will return a 401 Unauthorized response with a professional error message.

You can provide the token in two ways:

Authorization Header (Recommended)

Authorization: Bearer your_secret_key_here

Query Parameter

GET /api/search?q=despacito&apiKey=your_secret_key_here

Tip

You can set multiple valid API keys in your .env by separating them with commas: API_KEY=key1,key2,key3.

🛠️ Error Handling

The API uses a standardized, production-ready error format designed for clarity and easy client-side integration. All error responses include a unique Request ID for server-side correlation and debugging.

Error Response Structure

{
  "success": false,
  "error": {
    "message": "Full authentication is required to access this resource.",
    "code": "UNAUTHORIZED",
    "status": 401,
    "requestId": "MWO0DMS0"
  },
  "timestamp": "2026-03-27T06:24:04.971Z"
}

Common Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Access to the resource is denied
`NOT_FOUND`	404	The requested resource could not be found
`BAD_REQUEST`	400	The request is malformed or missing parameters
`INTERNAL_SERVER_ERROR`	500	An unexpected server-side error occurred

📚 API Documentation

Base URL

Development:  http://localhost:3000/api
Production:   https://your-domain.vercel.app/api

🔍 Search Endpoint

GET /api/search

Unified search across all content types (songs, albums, playlists, artists) in parallel.

Query Parameters:

q (required) - Search query string
limit (optional) - Results per type (default: 10, max: 25)

Example:

curl "http://localhost:3000/api/search?q=despacito&limit=20"

Response:

{
  "success": true,
  "data": {
    "songs": [...],
    "albums": [...],
    "playlists": [...],
    "artists": [...]
  },
  "timestamp": "..."
}

Type-Specific Search

GET /api/search/songs?q=query&limit=10
GET /api/search/albums?q=query&limit=10
GET /api/search/playlists?q=query&limit=10
GET /api/search/artists?q=query&limit=10

📕 Songs

GET /api/songs/:id or GET /api/songs?url=... or GET /api/songs?seokey=...

Get detailed information about a specific song.

Examples:

# Path parameter
curl "http://localhost:3000/api/songs/manjha"

# Query parameter with URL
curl "http://localhost:3000/api/songs?url=https://gaana.com/song/manjha"

Response:

{
  "seokey": "...",
  "track_id": "...",
  "title": "...",
  "artists": "...",
  "album": "...",
  "duration": 0,
  "language": "...",
  "is_explicit": false,
  "artworkUrl": "..."
}

📚 Albums

GET /api/albums/:id or GET /api/albums?url=... or GET /api/albums?seokey=...

Get album information with all tracks.

Response:

{
  "seokey": "...",
  "title": "...",
  "artists": "...",
  "track_count": 0,
  "release_date": "...",
  "play_count": 0,
  "tracks": [...]
}

📋 Playlists

GET /api/playlists/:id or GET /api/playlists?url=... or GET /api/playlists?seokey=...

Get playlist information with all tracks.

Response:

{
  "playlist": {
    "title": "...",
    "playlist_id": "...",
    "track_count": 0,
    "tracks": [...]
  }
}

🎤 Artists

GET /api/artists/:id or GET /api/artists?url=... or GET /api/artists?seokey=...

Get artist information with top tracks.

Response:

{
  "artist_id": "...",
  "seokey": "...",
  "name": "...",
  "artwork": "...",
  "artist_url": "...",
  "top_tracks": [...]
}

🔥 Trending

GET /api/trending?language=hi&limit=20

Get currently trending tracks.

Response:

{
  "success": true,
  "data": [...],
  "count": 0,
  "timestamp": "..."
}

📊 Charts

GET /api/charts?limit=20

Get top charts/playlists.

Response:

{
  "success": true,
  "data": [...],
  "count": 0,
  "timestamp": "..."
}

🎁 New Releases

Get newly released albums and songs with pagination and language filtering.

Endpoint: /api/new-releases

Query Parameters:

language (optional) - Language slug (default: english)
- Supported: Same as Album List
page (optional) - Zero-based page index (default: 0)
limit (optional) - Number of items per page (default: 40)

Example:

curl "http://localhost:3000/api/new-releases?language=punjabi&page=0&limit=10"

Response:

{
  "success": true,
  "data": [
    {
      "type": "track",
      "entity_id": "73030303",
      "seokey": "song-seokey",
      "title": "Song Title",
      "artists": "Artist Name",
      "language": "Punjabi",
      "artworkUrl": "...",
      "album": "Album Name",
      "duration": 210,
      "song_url": "..."
    }
  ],
  "count": 40,
  "page": 0,
  "limit": 10,
  "timestamp": "..."
}

📜 Lyrics

Get a list of songs with lyrics or specific song lyrics.

GET /api/lyrics?page=0 - Get paginated list of songs with lyrics.
GET /api/lyrics/:seokey - Get lyrics for a specific song.

Example (Lyrics List):

curl "http://localhost:3000/api/lyrics?page=0"

Example (Song Lyrics):

curl "http://localhost:3000/api/lyrics/eena-meena-deeka-18"

Response (Song Lyrics):

{
  "success": true,
  "album": "...",
  "title": "...",
  "lyrics": "Line 1\n\nLine 2\n\n...",
  "language": "Hindi",
  "timestamp": "..."
}

Response (Lyrics List):

{
  "success": true,
  "data": [
    {
      "track_id": "...",
      "seokey": "...",
      "title": "...",
      "artworkUrl": "...",
      "song_url": "...",
      "lyrics_url": "..."
    }
  ],
  "count": 312278,
  "page": 0,
  "timestamp": "..."
}

💿 Album List By Language

GET /api/album-list?language=hindi&page=0

Fetches Gaana's language-specific album list (type=albumList) and returns a normalized response.

Query Parameters:

language (optional) - Language slug (default: hindi)
- Supported: all, hindi, english, punjabi, telugu, tamil, bhojpuri, bengali, malayalam, kannada, marathi, gujarati, haryanvi, urdu, assamese, rajasthani, odia
page (optional) - Zero-based page index (default: 0)

Examples:

curl "http://localhost:3000/api/album-list?language=hindi&page=0"
curl "http://localhost:3000/api/album-list?language=punjabi&page=0"
curl "http://localhost:3000/api/album-list?language=all&page=0"

Response:

{
  "success": true,
  "data": [
    {
      "album_id": "13923727",
      "seokey": "dhurandhar-hindi-2025",
      "title": "Dhurandhar",
      "language": "Hindi",
      "release_date": "2025-12-05",
      "year": "2025",
      "track_count": 11,
      "duration": 2335,
      "artists_string": "Shashwat Sachdev",
      "artworkUrl": "http://a10.gaanacdn.com/images/albums/27/13923727/crop_480x480_13923727.jpg",
      "album_url": "https://gaana.com/album/dhurandhar-hindi-2025",
      "artists": [{ "name": "Shashwat Sachdev", "seokey": "shashwat-sachdev", "artist_id": "1295950" }]
    }
  ],
  "count": 14821780,
  "language": "hindi",
  "page": 0,
  "timestamp": "2026-03-20T00:00:00.000Z"
}

🎧 Stream URL

GET /api/stream/:trackId or GET /api/stream?track_id=...

Get decrypted HLS stream URL for a track by its track ID.

Query Parameters:

track_id (required if not using path param) - Numeric track ID
quality (optional) - Audio quality: low, medium, high (default: high)

Examples:

# Path parameter
curl "http://localhost:3000/api/stream/29797868"

# Query parameter
curl "http://localhost:3000/api/stream?track_id=29797868"

# With quality
curl "http://localhost:3000/api/stream/29797868?quality=medium"

Response:

{
  "quality": "high",
  "bitRate": "128",
  "hlsUrl": "https://vodhlsgaana-ebw.akamaized.net/hls/.../index.m3u8",
  "url": "https://vodhlsgaana-ebw.akamaized.net/hls/.../segment-0.m4s",
  "initUrl": "https://vodhlsgaana-ebw.akamaized.net/hls/.../init.mp4",
  "segments": [
    {
      "url": "https://vodhlsgaana-ebw.akamaized.net/hls/.../segment-0.m4s",
      "durationMs": 6000
    },
    ...
  ],
  "durationMs": 180000,
  "format": "m4s"
}

Note: The track_id can be obtained from the song details endpoint (/api/songs/:seokey).

🏥 Health

GET /api/health

Check API health status.

Response:

{
  "status": "ok",
  "uptime": 0,
  "environment": "...",
  "timestamp": "..."
}

Credits

If you use this API in your project, please credit:

Unofficial Gaana API by notdeltaxd
https://github.com/notdeltaxd/Gaana-API

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

⚠️ Important Disclaimer

This project is for educational and research purposes only. It is not affiliated with, endorsed by, or connected to Gaana in any way. This is a learning project created to understand API development, TypeScript, and web technologies. Users are responsible for ensuring their use complies with applicable laws and Gaana's terms of service. The authors assume no liability for misuse of this project.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
api		api
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
package.json		package.json
prettier.config.js		prettier.config.js
tsconfig.json		tsconfig.json
vercel.json		vercel.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🎵 Unofficial Gaana API

✨ Features

🚀 Quick Start

Installation

Development

Deployment to Vercel

🔐 Authentication

🛠️ Error Handling

Error Response Structure

Common Error Codes

📚 API Documentation

Base URL

🔍 Search Endpoint

Type-Specific Search

📕 Songs

📚 Albums

📋 Playlists

🎤 Artists

🔥 Trending

📊 Charts

🎁 New Releases

📜 Lyrics

💿 Album List By Language

🎧 Stream URL

🏥 Health

Credits

📄 License

⚠️ Important Disclaimer

About

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🎵 Unofficial Gaana API

✨ Features

🚀 Quick Start

Installation

Development

Deployment to Vercel

🔐 Authentication

🛠️ Error Handling

Error Response Structure

Common Error Codes

📚 API Documentation

Base URL

🔍 Search Endpoint

Type-Specific Search

📕 Songs

📚 Albums

📋 Playlists

🎤 Artists

🔥 Trending

📊 Charts

🎁 New Releases

📜 Lyrics

💿 Album List By Language

🎧 Stream URL

🏥 Health

Credits

📄 License

⚠️ Important Disclaimer

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages