🎶 GaanaPy

GaanaPy is an unofficial JSON API for Gaana, an Indian music streaming service.

📖 Table Of Contents

• 🎧 Features
• 👨‍🔧 Usage
• 💻 Local Development
• 🏥 Contributing
• 🐳 Docker Deployment

🎧 Features

The API provides structured JSON responses for:

• Tracks – Search and retrieve details for specific tracks.
• Albums – Search and fetch album information.
• Artists – Search, view artist details, and find similar artists.
• Playlists – Retrieve playlist details (search not supported).
• Top Charts – Curated playlists across all languages.
• Trending Tracks – Per-language trends.
• New Releases – Latest music by language.

Example Track Response

[
  {
    "seokey": "tyler-herro",
    "album_seokey": "tyler-herro",
    "track_id": "32408795",
    "title": "Tyler Herro",
    "artists": "Jack Harlow",
    "artist_seokeys": "jack-harlow",
    "artist_ids": "817522",
    "artist_image": "https://a10.gaanacdn.com/gn_img/artists/XYybzrb2gz/Yybzn4Bgb2/size_m_1607927137.webp",
    "album": "Tyler Herro",
    "album_id": "3487503",
    "duration": "156",
    "popularity": "18444~18444",
    "genres": "Hip Hop",
    "is_explicit": true,
    "language": "English",
    "label": "Generation Now/Atlantic",
    "release_date": "2020-10-22",
    "play_count": "<100K",
    "favorite_count": 231,
    "song_url": "https://gaana.com/song/tyler-herro",
    "album_url": "https://gaana.com/album/tyler-herro",
    "images": {
      "urls": {
        "large_artwork": "https://a10.gaanacdn.com/gn_img/albums/4Z9bqo3yQn/Z9bq2AG1Ky/size_l.jpg",
        "medium_artwork": "https://a10.gaanacdn.com/gn_img/albums/4Z9bqo3yQn/Z9bq2AG1Ky/size_m.jpg",
        "small_artwork": "https://a10.gaanacdn.com/gn_img/albums/4Z9bqo3yQn/Z9bq2AG1Ky/size_s.jpg"
      }
    },
    "stream_urls": {
      "urls": {
        "very_high_quality": "https://vodhlsgaana-ebw.akamaized.net/hls/3/3487503/32408795/320.mp4.master.m3u8?hdnts=st=1750835850~exp=1750850250~acl=/*~hmac=ebd312837a89763eb967627048071b22ee619be14219ff402143d023c50cf7bb",
        "high_quality": "https://vodhlsgaana-ebw.akamaized.net/hls/3/3487503/32408795/128.mp4.master.m3u8?hdnts=st=1750835850~exp=1750850250~acl=/*~hmac=ebd312837a89763eb967627048071b22ee619be14219ff402143d023c50cf7bb",
        "medium_quality": "https://vodhlsgaana-ebw.akamaized.net/hls/3/3487503/32408795/64.mp4.master.m3u8?hdnts=st=1750835850~exp=1750850250~acl=/*~hmac=ebd312837a89763eb967627048071b22ee619be14219ff402143d023c50cf7bb",
        "low_quality": "https://vodhlsgaana-ebw.akamaized.net/hls/3/3487503/32408795/16.mp4.master.m3u8?hdnts=st=1750835850~exp=1750850250~acl=/*~hmac=ebd312837a89763eb967627048071b22ee619be14219ff402143d023c50cf7bb"
      }
    }
  }
]

👨‍🔧 Usage

API documentation (when running locally): http://127.0.0.1:8000/docs

Search For Songs: (Requires a search query, limit is optional)

http://127.0.0.1:8000/songs/search?query=<insert-query-here>&limit=<insert-limit-here, eg. 5>

Example: Create a GET request or navigate to http://127.0.0.1:8000/songs/search?query=tyler herro to get a JSON response of song results in return.

---

Search For Albums: (Requires a search query, limit is optional)

http://127.0.0.1:8000/albums/search?query=<insert-query-here>&limit=<insert-limit-here, eg. 5>

Example: Create a GET request or navigate to http://127.0.0.1:8000/albums/search?query=all over the place to get a JSON response of album results in return.

---

Search For Artists: (Requires a search query, limit is optional)

http://127.0.0.1:8000/artists/search?query=<insert-query-here>&limit=<insert-limit-here, eg. 5>

Example: Create a GET request or navigate to http://127.0.0.1:8000/artists/search?query=KSI to get a JSON response of artist results in return.

---

Get Similar Artists: (Requires an Artist ID)

http://127.0.0.1:8000/artists/similar?artist_id=ARTIST_ID

How do I find an artist's ID?:

• Using Search For Songs or Search For Albums, locate:

[
  {
    "artist_ids": "817522", (There may be more than 1 artist ID depending on the number of artists in the song/album.) 
  }
]

Example: Create a GET request or navigate to http://127.0.0.1:8000/artists/similar?artist_id=817522 to get a JSON response of similar artists in return.

---

Get Song Info: (Requires a SEOKEY)

http://127.0.0.1:8000/songs/info?seokey=SEOKEY

How do I find a song's seokey?:

• In a URL, for example, https://gaana.com/song/tyler-herro, tyler-herro is the song's seokey.
• Using Search For Songs, locate:

[
  {
    "seokey": "tyler-herro", 
  }
]

Example: Create a GET request or navigate to http://127.0.0.1:8000/songs/info?seokey=tyler-herro to get a JSON response of the song's info in return.

---

Get Album Info: (Requires a SEOKEY)

http://127.0.0.1:8000/albums/info?seokey=ALBUM_SEOKEY

How do I find an albums's seokey?:

• In a URL, for example, https://gaana.com/album/tyler-herro, tyler-herro is the albums's seokey.
• Using Search For Albums, locate:

[
  {
    "seokey": "tyler-herro", 
  }
]

• Using Search For Songs, locate:

[
  {
    "album_seokey": "tyler-herro", 
  }
]

Example: Create a GET request or navigate to http://127.0.0.1:8000/albums/info?seokey=tyler-herro to get a JSON response of the album's info in return.

---

Get Artist Info: (Requires a SEOKEY)

http://127.0.0.1:8000/artists/info?seokey=SEOKEY

How do I find an artist's seokey?:

• In a URL, for example, https://gaana.com/artist/jack-harlow, jack-harlow is the song's seokey.
• Using Search For Songs or Search For Albums, locate:

[
  {
    "artist_seokeys": "jack-harlow", (There may be more than 1 seokey depending on the number of artists in the song/album.) 
  }
]

Example: Create a GET request or navigate to http://127.0.0.1:8000/artists/info?seokey=jack-harlow to get a JSON response of the artist's info in return.

---

Get Playlist Info: (Requires a SEOKEY)

http://127.0.0.1:8000/playlists/info?seokey=SEOKEY

How do I find a playlists's seokey?:

• In a URL, for example, https://gaana.com/playlist/gaana-dj-gaana-international-top-50, gaana-dj-gaana-international-top-50 is the playlist's seokey.

Example: Create a GET request or navigate to http://127.0.0.1:8000/playlists/info?seokey=gaana-dj-gaana-international-top-50 to get a JSON response of the playlist's info in return.

---

Get Trending Tracks: (Requires a LANGUAGE)

http://127.0.0.1:8000/trending?lang=LANGUAGE

Language Options: English, Hindi, Punjabi, Telugu, Tamil etc. (Warning: Case sensitive!). Defaults to Hindi if no language is provided or if an invalid language is entered.

Example: Create a GET request or navigate to http://127.0.0.1:8000/trending?lang=English to get a JSON response of the trending English songs in return.

---

Get New Releases: (Requires a language)

http://127.0.0.1:8000/newreleases?lang=LANGUAGE

Language Options: English, Hindi, Punjabi, Telugu, Tamil etc. (Warning: Case sensitive!). Defaults to Hindi if no language is provided or if an invalid language is entered.

Example: Create a GET request or navigate to http://127.0.0.1:8000/newreleases?lang=English to get a JSON response of both new English songs and English albums in return.

---

Get Charts (Returns a list of popular playlists):

http://127.0.0.1:8000/charts

Example: Create a GET request or navigate to http://127.0.0.1:8000/charts to get a JSON response of the top charts.

📦 Installation

You can install GaanaPy directly via pip:

pip install gaanapy

👨‍🔧 Local Development & Usage

1. Run the API Server

After installation, you can launch the API server using the built-in command:

gaanapy-api --host 127.0.0.1 --port 8000

Alternatively, from the source directory:

python3 -m uvicorn gaanapy.app:app --reload

2. Using as a Library

You can also integrate GaanaPy into your own Python applications:

import asyncio
from gaanapy import GaanaPy

async def main():
    gaana = GaanaPy()
    results = await gaana.search_songs("Tyler Herro", limit=5)
    print(results)
    await gaana.aiohttp.close()

if __name__ == "__main__":
    asyncio.run(main())

Navigate to: http://127.0.0.1:8000/docs to see the full API documentation after starting the server.

🐳 Docker Deployment

Deploy the API locally using the following Docker-Compose stack:

services:
  gaanapy:
    image: zingytomato/gaanapy:main
    container_name: gaanapy
    ports:
      - 8000:8000 # External port can be changed
    restart: unless-stopped

Navigate to: http://SERVER_IP:8000 to get started.

🏥 Contributing

Feel free to create an issue if you encounter any bugs or would like to suggest something!