{"id":33319449,"url":"https://github.com/johanverne/spotifyreadmestats","last_synced_at":"2026-05-01T20:33:03.121Z","repository":{"id":324194404,"uuid":"1096307278","full_name":"JohanVerne/SpotifyREADMEStats","owner":"JohanVerne","description":"Simple utility to collect Spotify stats with a Vercel instance and add an infographic to a GitHub READMEfile","archived":false,"fork":false,"pushed_at":"2025-11-16T15:32:03.000Z","size":75,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-16T16:17:33.825Z","etag":null,"topics":["ci-cd","flask","pytest","python","python3","readme","readme-profile","spotify","spotify-stats","spotipy","spotipy-library","stats","vercel"],"latest_commit_sha":null,"homepage":"https://spotify-stats-rose.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JohanVerne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-14T08:31:31.000Z","updated_at":"2025-11-16T15:32:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JohanVerne/SpotifyREADMEStats","commit_stats":null,"previous_names":["johanverne/spotifystats","johanverne/spotifyreadmestats"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/JohanVerne/SpotifyREADMEStats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohanVerne%2FSpotifyREADMEStats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohanVerne%2FSpotifyREADMEStats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohanVerne%2FSpotifyREADMEStats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohanVerne%2FSpotifyREADMEStats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JohanVerne","download_url":"https://codeload.github.com/JohanVerne/SpotifyREADMEStats/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohanVerne%2FSpotifyREADMEStats/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285319005,"owners_count":27151474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci-cd","flask","pytest","python","python3","readme","readme-profile","spotify","spotify-stats","spotipy","spotipy-library","stats","vercel"],"created_at":"2025-11-19T20:01:05.106Z","updated_at":"2025-11-19T20:03:04.506Z","avatar_url":"https://github.com/JohanVerne.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"images/Spotify.svg\", width=\"100px\" \u003e\n  \u003ch1\u003e SpotifyREADMEStats\u003c/h1\u003e\n\n\u003ca href=\"\"\u003e![Python](https://img.shields.io/badge/python-3.14-blue.svg)\u003c/a\u003e\n\u003ca href=\"\"\u003e![Flask](https://img.shields.io/badge/flask-3.1.0-green.svg)\u003c/a\u003e\n\u003ca href=\"\"\u003e![Spotipy](https://img.shields.io/badge/spotipy-2.25.0-1DB954.svg)\u003c/a\u003e\n\u003ca href=\"\"\u003e![Vercel](https://img.shields.io/badge/vercel-deployed-black.svg)\u003c/a\u003e\n\u003ca href=\"\"\u003e![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)\u003c/a\u003e\n\n\u003c/div\u003e\n\nA serverless API that collects your Spotify listening statistics using the spotipy library and makes them available for display in GitHub READMEs or other applications. Built with Python, Flask, and deployed on Vercel.\n\n[To deploy this solution for your own needs, jump to THIS section](#deployment-guide)\n\n## Endpoints preview\n\nUse the `/stats` endpoint to access the images API\n\n| Parameters | Description                                     | Possible values                         | Default values |\n| ---------- | ----------------------------------------------- | --------------------------------------- | -------------- |\n| `type`     | Select the stat to display (only one per query) | `artists`, `top_songs` or `last_albums` | `artists`      |\n| `range`    | Select the time range of selection              | `short_term` or `long_term`             | `short_term`   |\n\nYou can also use the `/json` endpoint to access the raw Spotify data as JSON.\n\n### Use examples\n\n#### Favorite recent artists\n\n```\nstats?type=artists\u0026range=short_term\n```\n\n\u003ca href=\"https://github.com/JohanVerne/SpotifyREADMEStats\"\u003e\n    \u003cimg src=\"https://spotify-stats-rose.vercel.app/stats?type=artists\u0026range=short_term\", alt=\"Top Artists Recent\" /\u003e\n\u003c/a\u003e\n\n#### Most listened-to songs ever\n\n```\nstats?type=top_songs\u0026range=long_term\n```\n\n\u003ca href=\"https://github.com/JohanVerne/SpotifyREADMEStats\"\u003e\n    \u003cimg src=\"https://spotify-stats-rose.vercel.app/stats?type=top_songs\u0026range=long_term\", alt=\"Top Songs All-Time\" /\u003e\n\u003c/a\u003e\n\n#### Last played albums\n\n```\nstats?type=last_albums\n```\n\n\u003ca href=\"https://github.com/JohanVerne/SpotifyREADMEStats\"\u003e\n    \u003cimg src=\"https://spotify-stats-rose.vercel.app/stats?type=last_albums\", alt=\"Last Albums\" /\u003e\n\u003c/a\u003e\n\n## Deployment Guide\n\nFollow these steps to deploy your own instance with your Spotify data.\n\n### Step 1: Create a Spotify Developer Application\n\n1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)\n2. Log in with your Spotify account\n3. Click **Create an App**\n4. Fill in the app name and description, select **Web API** and accept the TOS\n5. Once created, note your **Client ID** and **Client Secret**\n6. Click **Edit Settings**\n7. Add `http://localhost:8888/callback` to **Redirect URIs**\n8. Save the settings\n\n### Step 2: Get Your Spotify Refresh Token | ⚠️ INCONSISTENT ⚠️\n\nThe refresh token allows the API to access your Spotify data without requiring browser interaction.\n\n1. Clone this repository:\n\n```bash\ngit clone https://github.com/yourusername/SpotifyStats.git\ncd SpotifyStats\n```\n\n2. Create and activate a virtual environment:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n```\n\n3. Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n4. Edit `getRefreshToken.py` and replace the placeholders:\n\n```py\nclient_id=\"YOUR_CLIENT_ID\", # From Spotify Dashboard\nclient_secret=\"YOUR_CLIENT_SECRET\", # From Spotify Dashboard\n```\n\n5. Run the script:\n\n```bash\npython getRefreshToken.py\n```\n\n6. A browser window may open asking you to authorize the app\n7. The script will print your **refresh token** to the terminal- save this securely!\n\n### Step 3: Fork and Configure the Repository\n\n1. Fork this repository to your GitHub account\n2. Go to your forked repository settings\n3. Navigate to **Secrets and variables** → **Actions**\n4. Add the following secrets (these are for CI/CD testing):\n\n- `SPOTIPY_CLIENT_ID`: Your Spotify Client ID\n- `SPOTIPY_CLIENT_SECRET`: Your Spotify Client Secret\n- `SPOTIPY_REDIRECT_URI`: `http://localhost:8888/callback`\n\n### Step 4: Deploy to Vercel\n\n1. Go to [Vercel](https://vercel.com) and sign up/log in\n2. Click **Add New Project**\n3. Import your forked GitHub repository\n4. Vercel will detect the Python project automatically\n5. Create a Github Personal Access Token (PAT) --\u003e you can see the steps [from this repo](https://github.com/anuraghazra/github-readme-stats?tab=readme-ov-file#on-vercel)\n6. Before deploying, add **Environment Variables**:\n\n- `SPOTIPY_CLIENT_ID`: Your Spotify Client ID\n- `SPOTIPY_CLIENT_SECRET`: Your Spotify Client Secret\n- `SPOTIPY_REDIRECT_URI`: `http://localhost:8888/callback`\n- `SPOTIFY_REFRESH_TOKEN`: The refresh token from Step 2\n- `PAT_1`: The created PAT\n\n7. Click **Deploy**\n\n### Step 5: Test Your Deployment\n\nOnce deployed, Vercel will give you a URL like `https://your-project.vercel.app`\n\nTest your API:\n\n```bash\ncurl https://your-project.vercel.app/json\n```\n\nYou should get a JSON with your Spotify statistics!\n\n### Step 6: Use in Your GitHub README\n\nAdd the following to any GitHub README to display your stats:\n\n```html\n\u003ca href=\"https://github.com/JohanVerne/SpotifyREADMEStats\"\u003e\n  \u003cimg src=\"https://YOUR_VERCEL_DOMAIN_vercel.app/stats?PARAMS\" /\u003e\n\u003c/a\u003e\n```\n\nReplace YOUR_VERCEL_DOMAIN with the name of your API, present in your Vercel project dashboard, and PARAMS with the parameters [listed here](#endpoints-preview)\n\n## Try out locally\n\nCreate a .env file in the project root:\n\n```\nSPOTIPY_CLIENT_ID=your_client_id\nSPOTIPY_CLIENT_SECRET=your_client_secret\nSPOTIPY_REDIRECT_URI=http://localhost:8888/callback\nSPOTIFY_REFRESH_TOKEN=your_refresh_token\n```\n\nRun the collector directly:\n\n```bash\npython -m dotenv run -- python -m statsCollector\n```\n\nOr run the Flask API locally:\n\n```bash\npython -m dotenv run -- python api/index.py\n```\n\nRunning Tests\n\n```bash\npython -m dotenv run -- python -m pytest -q\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohanverne%2Fspotifyreadmestats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohanverne%2Fspotifyreadmestats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohanverne%2Fspotifyreadmestats/lists"}