Skip to content

moddroid94/local-green-api

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
.gitignore
.gitignore
 
 
.python-version
.python-version
 
 
README.md
README.md
 
 
main.py
main.py
 
 
parquet_handler.py
parquet_handler.py
 
 
pyproject.toml
pyproject.toml
 
 
uv.lock
uv.lock
 
 

Repository files navigation

Local Green WebAPI Clone

Disclaimer

This project is not affiliated with, endorsed by, or connected to Spotify AB or any other music streaming service. This is independent open-source software that provides API infrastructure for querying music metadata databases.

Warning

This repository does not include any databases or copyrighted data. You must obtain the .parquet databases separately. This project only provides the API server code to query existing databases.

The author(s) of this project are not responsible for how you obtain or use the underlying data. Users are solely responsible for ensuring their use of any databases complies with applicable laws and terms of service. This software is provided "as is" without warranty of any kind.

Info

This is a simple project I've built to tag my own music with the immense catalog available.

After the blip the metadata dataset was made available as a parquet file, for the full 256M rows of metadata the whole db is now only ~30GB in size.

You can find it online. hint: check the db extension

Given the very low space needed I decided to try and emulate the responses of the API to leverage the already built integrations for metadata in tools like Beets or Picard.

Result: It worked quite well, apart from artworks, the most important infos are available and retrieved correctly, the only changes being the API url and an auth bypass.

This is still a rough demo, it mostly follows the specs but most methods are missing, so it may not work correctly with all the integrations yet.

Usage & Development

The project is managed using uv, more at installation

  • Download the datase and unzip it into the root folder
  • Sync the dependency with uv sync
  • Run with fastapi dev main.py
  • The API should be available at http://127.0.0.1:8000

Ps: the routes are not prefixed with /v1/ like the API.

Headers are ignored, market availability too.

Supported Methods

  • Get Several Tracks1 (Return Spec Compliant)
  • Get Albums (Full Spec Compliant)
  • Get Artist (Full Spec Compliant)
  • Search2 (Return Spec Compliant)

1) Only 1 track at a time, but with multi-track response schema
2) Allowed query types are:
  • track with query filters: artist: album: isrc:

Example Request-Response

Get Albums

Request: http://127.0.0.1:8000/albums/3EncU2oR8VzeuWvLKPIEQd

Response:

{
  "rowid": 767985,
  "id": "3EncU2oR8VzeuWvLKPIEQd",
  "name": "Pivot (Camo & Krooked Remix) / Sinkhole (Skeptical Remix)",
  "type": "album",
  "tracks": {
    "href": "*/albums/3EncU2oR8VzeuWvLKPIEQd/tracks",
    "next": null,
    "total": 2,
    "previous": null,
    "items": [
      {
        "rowid": 9368406,
        "album_rowid": 767985,
        "artists": [
          {
            "rowid": 2501390,
            "id": "54qqaSH6byJIb8eFWxe3Pj",
            "name": "Mefjus",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 72765
            },
            "popularity": 52,
            "href": "*/artists/54qqaSH6byJIb8eFWxe3Pj",
            "uri": "*:artist:54qqaSH6byJIb8eFWxe3Pj",
            "external_url": {
              "*": "*/artist/54qqaSH6byJIb8eFWxe3Pj"
            }
          },
          {
            "rowid": 4929842,
            "id": "2N8IPNZTiNo3nj4mreOlHU",
            "name": "Camo & Krooked",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 237761
            },
            "popularity": 54,
            "href": "*artists/2N8IPNZTiNo3nj4mreOlHU",
            "uri": "*:artist:2N8IPNZTiNo3nj4mreOlHU",
            "external_url": {
              "*": "*/artist/2N8IPNZTiNo3nj4mreOlHU"
            }
          }
        ],
        "id": "5w5Yy1iT2oAHMHi0ecFGRV",
        "name": "Pivot - Camo & Krooked Remix",
        "type": "track",
        "external_url": {
          "*": "*/track/5w5Yy1iT2oAHMHi0ecFGRV"
        },
        "href": "*/tracks/5w5Yy1iT2oAHMHi0ecFGRV",
        "uri": "*:track:5w5Yy1iT2oAHMHi0ecFGRV",
        "preview_url": null,
        "explicit": 0,
        "external_ids": {
          "isrc": "UKACT1830493"
        },
        "popularity": 11,
        "duration_ms": 266181,
        "disc_number": 1,
        "track_number": 1
      },
      {
        "rowid": 9368407,
        "album_rowid": 767985,
        "artists": [
          {
            "rowid": 2501390,
            "id": "54qqaSH6byJIb8eFWxe3Pj",
            "name": "Mefjus",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 72765
            },
            "popularity": 52,
            "href": "*/artists/54qqaSH6byJIb8eFWxe3Pj",
            "uri": "*:artist:54qqaSH6byJIb8eFWxe3Pj",
            "external_url": {
              "*": "*/artist/54qqaSH6byJIb8eFWxe3Pj"
            }
          },
          {
            "rowid": 5138393,
            "id": "28ee6rnxMl8AqwcroPfivP",
            "name": "Skeptical",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 26163
            },
            "popularity": 37,
            "href": "https://api.*.com/v1/artists/28ee6rnxMl8AqwcroPfivP",
            "uri": "*:artist:28ee6rnxMl8AqwcroPfivP",
            "external_url": {
              "*": "https://open.*.com/artist/28ee6rnxMl8AqwcroPfivP"
            }
          }
        ],
        "id": "4pQp4qcip75nJACmwsDstb",
        "name": "Sinkhole - Skeptical Remix",
        "type": "track",
        "external_url": {
          "*": "https://open.*.com/track/4pQp4qcip75nJACmwsDstb"
        },
        "href": "https://api.*.com/v1/tracks/4pQp4qcip75nJACmwsDstb",
        "uri": "*:track:4pQp4qcip75nJACmwsDstb",
        "preview_url": null,
        "explicit": 0,
        "external_ids": {
          "isrc": "UKACT1830494"
        },
        "popularity": 16,
        "duration_ms": 277674,
        "disc_number": 1,
        "track_number": 2
      }
    ]
  },
  "album_type": "single",
  "external_ids": {
    "upc": "5057272089689"
  },
  "external_url": {
    "*": "https://open.*.com/album/3EncU2oR8VzeuWvLKPIEQd"
  },
  "href": "https://api.*.com/v1/albums/3EncU2oR8VzeuWvLKPIEQd",
  "uri": "*:album:3EncU2oR8VzeuWvLKPIEQd",
  "copyrights": [
    {
      "text": "2018 Vision Recordings",
      "type": "C"
    },
    {
      "text": "2018 Vision Recordings",
      "type": "P"
    }
  ],
  "images": [],
  "genres": [],
  "label": "Vision Recordings",
  "popularity": 7,
  "release_date": "2018-11-02",
  "release_date_precision": "day",
  "total_tracks": 2,
  "artists": [
    {
      "rowid": 2501390,
      "id": "54qqaSH6byJIb8eFWxe3Pj",
      "name": "Mefjus",
      "type": "artist",
      "genres": [],
      "followers": {
        "href": null,
        "total": 72765
      },
      "popularity": 52,
      "href": "https://api.*.com/v1/artists/54qqaSH6byJIb8eFWxe3Pj",
      "uri": "*:artist:54qqaSH6byJIb8eFWxe3Pj",
      "external_url": {
        "*": "https://open.*.com/artist/54qqaSH6byJIb8eFWxe3Pj"
      }
    },
    {
      "rowid": 4929842,
      "id": "2N8IPNZTiNo3nj4mreOlHU",
      "name": "Camo & Krooked",
      "type": "artist",
      "genres": [],
      "followers": {
        "href": null,
        "total": 237761
      },
      "popularity": 54,
      "href": "https://api.*.com/v1/artists/2N8IPNZTiNo3nj4mreOlHU",
      "uri": "*:artist:2N8IPNZTiNo3nj4mreOlHU",
      "external_url": {
        "*": "https://open.*.com/artist/2N8IPNZTiNo3nj4mreOlHU"
      }
    },
    {
      "rowid": 5138393,
      "id": "28ee6rnxMl8AqwcroPfivP",
      "name": "Skeptical",
      "type": "artist",
      "genres": [],
      "followers": {
        "href": null,
        "total": 26163
      },
      "popularity": 37,
      "href": "https://api.*.com/v1/artists/28ee6rnxMl8AqwcroPfivP",
      "uri": "*:artist:28ee6rnxMl8AqwcroPfivP",
      "external_url": {
        "*": "https://open.*.com/artist/28ee6rnxMl8AqwcroPfivP"
      }
    }
  ]
}

Get Several Tracks

Request: http://127.0.0.1:8000/tracks?ids=4pQp4qcip75nJACmwsDstb

Response:

{
  "tracks": [
    {
      "album": {
        "rowid": 767985,
        "id": "3EncU2oR8VzeuWvLKPIEQd",
        "name": "Pivot (Camo & Krooked Remix) / Sinkhole (Skeptical Remix)",
        "type": "album",
        "album_type": "single",
        "popularity": 7,
        "release_date": "2018-11-02",
        "release_date_precision": "day",
        "total_tracks": 2,
        "artists": [
          {
            "rowid": 2501390,
            "id": "54qqaSH6byJIb8eFWxe3Pj",
            "name": "Mefjus",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 72765
            },
            "popularity": 52,
            "href": "https://api.*.com/v1/artists/54qqaSH6byJIb8eFWxe3Pj",
            "uri": "*:artist:54qqaSH6byJIb8eFWxe3Pj",
            "external_url": {
              "*": "https://open.*.com/artist/54qqaSH6byJIb8eFWxe3Pj"
            }
          },
          {
            "rowid": 5138393,
            "id": "28ee6rnxMl8AqwcroPfivP",
            "name": "Skeptical",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 26163
            },
            "popularity": 37,
            "href": "https://api.*.com/v1/artists/28ee6rnxMl8AqwcroPfivP",
            "uri": "*:artist:28ee6rnxMl8AqwcroPfivP",
            "external_url": {
              "*": "https://open.*.com/artist/28ee6rnxMl8AqwcroPfivP"
            }
          }
        ],
        "external_url": {
          "*": "https://open.*.com/album/3EncU2oR8VzeuWvLKPIEQd"
        },
        "href": "https://api.*.com/v1/albums/3EncU2oR8VzeuWvLKPIEQd",
        "uri": "*:album:3EncU2oR8VzeuWvLKPIEQd",
        "images": []
      },
      "artists": [
        {
          "rowid": 2501390,
          "id": "54qqaSH6byJIb8eFWxe3Pj",
          "name": "Mefjus",
          "type": "artist",
          "genres": [],
          "followers": {
            "href": null,
            "total": 72765
          },
          "popularity": 52,
          "href": "https://api.*.com/v1/artists/54qqaSH6byJIb8eFWxe3Pj",
          "uri": "*:artist:54qqaSH6byJIb8eFWxe3Pj",
          "external_url": {
            "*": "https://open.*.com/artist/54qqaSH6byJIb8eFWxe3Pj"
          }
        },
        {
          "rowid": 5138393,
          "id": "28ee6rnxMl8AqwcroPfivP",
          "name": "Skeptical",
          "type": "artist",
          "genres": [],
          "followers": {
            "href": null,
            "total": 26163
          },
          "popularity": 37,
          "href": "https://api.*.com/v1/artists/28ee6rnxMl8AqwcroPfivP",
          "uri": "*:artist:28ee6rnxMl8AqwcroPfivP",
          "external_url": {
            "*": "https://open.*.com/artist/28ee6rnxMl8AqwcroPfivP"
          }
        }
      ],
      "id": "4pQp4qcip75nJACmwsDstb",
      "name": "Sinkhole - Skeptical Remix",
      "type": "track",
      "external_url": {
        "*": "https://open.*.com/track/4pQp4qcip75nJACmwsDstb"
      },
      "href": "https://api.*.com/v1/tracks/4pQp4qcip75nJACmwsDstb",
      "uri": "*:track:4pQp4qcip75nJACmwsDstb",
      "preview_url": null,
      "explicit": 0,
      "external_ids": {
        "isrc": "UKACT1830494"
      },
      "popularity": 16,
      "duration_ms": 277674,
      "disc_number": 1,
      "track_number": 2,
      "is_playable": true
    }
  ]
}

Get Artist

Request: http://127.0.0.1:8000/artists/54qqaSH6byJIb8eFWxe3Pj

Response:

{
  "rowid": 2501390,
  "id": "54qqaSH6byJIb8eFWxe3Pj",
  "name": "Mefjus",
  "type": "artist",
  "genres": [],
  "followers": {
    "href": null,
    "total": 72765
  },
  "popularity": 52,
  "href": "https://api.*.com/v1/artists/54qqaSH6byJIb8eFWxe3Pj",
  "uri": "*:artist:54qqaSH6byJIb8eFWxe3Pj",
  "external_url": {
    "*": "https://open.*.com/artist/54qqaSH6byJIb8eFWxe3Pj"
  }
}

Search

Request: http://127.0.0.1:8000/search?q=Crank%20-%20Kasra%20album:Resonance%20&type=track&limit=1

Response:

{
  "track": {
    "href": "",
    "limit": 1,
    "next": null,
    "offset": 0,
    "previous": null,
    "total": 1,
    "items": [
      {
        "rowid": 9329915,
        "album_rowid": 762445,
        "album": {
          "rowid": 762445,
          "id": "1vqbno1uvn9oBuE6nPD5MR",
          "name": "The Resonance V",
          "type": "album",
          "album_type": "album",
          "popularity": 11,
          "release_date": "2023-02-17",
          "release_date_precision": "day",
          "total_tracks": 15,
          "artists": [
            {
              "rowid": 2968258,
              "id": "4YWj8sohRDjL9deiuRvEEY",
              "name": "Noisia",
              "type": "artist",
              "genres": [],
              "followers": {
                "href": null,
                "total": 283349
              },
              "popularity": 50,
              "href": "https://api.*.com/v1/artists/4YWj8sohRDjL9deiuRvEEY",
              "uri": "*:artist:4YWj8sohRDjL9deiuRvEEY",
              "external_url": {
                "*": "https://open.*.com/artist/4YWj8sohRDjL9deiuRvEEY"
              }
            },
            {
              "rowid": 3902266,
              "id": "3W1ubrHvNSMltB1l7zo6xt",
              "name": "Kasra",
              "type": "artist",
              "genres": [],
              "followers": {
                "href": null,
                "total": 19665
              },
              "popularity": 34,
              "href": "https://api.*.com/v1/artists/3W1ubrHvNSMltB1l7zo6xt",
              "uri": "*:artist:3W1ubrHvNSMltB1l7zo6xt",
              "external_url": {
                "*": "https://open.*.com/artist/3W1ubrHvNSMltB1l7zo6xt"
              }
            }
          ],
          "external_url": {
            "*": "https://open.*.com/album/1vqbno1uvn9oBuE6nPD5MR"
          },
          "href": "https://api.*.com/v1/albums/1vqbno1uvn9oBuE6nPD5MR",
          "uri": "*:album:1vqbno1uvn9oBuE6nPD5MR",
          "images": []
        },
        "artists": [
          {
            "rowid": 2968258,
            "id": "4YWj8sohRDjL9deiuRvEEY",
            "name": "Noisia",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 283349
            },
            "popularity": 50,
            "href": "https://api.*.com/v1/artists/4YWj8sohRDjL9deiuRvEEY",
            "uri": "*:artist:4YWj8sohRDjL9deiuRvEEY",
            "external_url": {
              "*": "https://open.*.com/artist/4YWj8sohRDjL9deiuRvEEY"
            }
          },
          {
            "rowid": 3902266,
            "id": "3W1ubrHvNSMltB1l7zo6xt",
            "name": "Kasra",
            "type": "artist",
            "genres": [],
            "followers": {
              "href": null,
              "total": 19665
            },
            "popularity": 34,
            "href": "https://api.*.com/v1/artists/3W1ubrHvNSMltB1l7zo6xt",
            "uri": "*:artist:3W1ubrHvNSMltB1l7zo6xt",
            "external_url": {
              "*": "https://open.*.com/artist/3W1ubrHvNSMltB1l7zo6xt"
            }
          }
        ],
        "id": "16Ek7OlxiIipZ59CYT3vVG",
        "name": "Crank - Kasra Remix",
        "type": "track",
        "external_url": {
          "*": "https://open.*.com/track/16Ek7OlxiIipZ59CYT3vVG"
        },
        "href": "https://api.*.com/v1/tracks/16Ek7OlxiIipZ59CYT3vVG",
        "uri": "*:track:16Ek7OlxiIipZ59CYT3vVG",
        "preview_url": null,
        "explicit": 0,
        "external_ids": {
          "isrc": "UKU932390011"
        },
        "popularity": 5,
        "duration_ms": 248372,
        "disc_number": 1,
        "track_number": 10,
        "is_playable": true
      }
    ]
  }
}

About

Locally hosted Green WebAPI clone

Topics

api metadata spotify clone offline

Resources

Readme
Activity

Stars

67 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases 1

v0.1.0 - Initial Latest
Jan 28, 2026

Contributors 1

Languages