To generate your own data card, simply navigate to the website and click the "Generate Card" button. This will prompt you to log in to your Spotify account and allow the service to access your Spotify account data and activity. After clicking "Agree" your data card will be generated.
On the home page, you can click the "Copy Code" button to copy the HTML which you would then paste into your README.md file or website code to embed the data card. You can also click the "Full Card View" button to view the "card page," which displays an interactive version of your data card.
Most markdown applications should be able to render the HTML copied by the "Copy Code" button. If this isn't the case or if you'd prefer to use Markdown instead of HTML, you can convert the HTML to Markdown like so:
Change
<a href="card_page_link">
<img src="card_image_link" alt="Data Card for Spotify">
</a>
to
[![Data Card for Spotify](card_image_link)](card_page_link)
You can customize the data that's shown on your data card with URL parameters. These are all the possible customization options:
-
show_border
- (boolean) whether or not to show a white border around the data card; default value:false
-
show_date
- (boolean) whether or not to show the date and time that the data card was generated; default value:false
-
time_zone
- (string) the time zone to use whenshow_date
is set to true; example:America/Los_Angeles
(full list); default value:UTC
-
custom_title
- (string) a custom title to use for the data card; must be URL-encoded which can be done with an online tool like urlencoder.org; default value: none -
hide_title
- (boolean) whether or not to hide the title; default value:false
-
hide_explicit
- (boolean) whether or not to hide explicit tracks from all sections; default value:false
-
hide_playing
- (boolean) whether or not to hide the "Currently Listening To" section; default value:false
-
hide_recents
- (boolean) whether or not to hide the "Recently Played Tracks" section; default value:false
-
hide_top_tracks
- (boolean) whether or not to hide the "Top Tracks" section; default value:false
-
hide_top_artists
- (boolean) whether or not to hide the "Top Artists" section; default value:false
-
limit
- (number) the number of items to show for the "Recently Played Tracks," "Top Tracks," and "Top Artists" sections; minimum value:1
, maximum value:10
, default value:5
To render a data card with any of the customization options, simply append them to the URL as query parameters. Example:
URL for basic data card:
https://data-card-for-spotify.herokuapp.com/api/card?user_id=12146253656
URL for data card with border (&show_border=true
):
https://data-card-for-spotify.herokuapp.com/api/card?user_id=12146253656&show_border=true
Note 1: Setting a boolean option to
1
has the same effect as setting it totrue
.
Note 2: The card page of the website at data-card-for-spotify.herokuapp.com/card grabs the query params of the page's URL and passes them along to the URL of the interactive data card that gets rendered on the page. This means that you can customize data cards on the site itself and share them from there.
Apple's WebKit browser engine is extremely buggy when rendering CSS animations for SVGs embedded as images. You've probably already noticed this if you're viewing this on one of the following WebKit-based browsers:
- Safari
- Any browser on iOS and iPadOS
My original solution to this problem was to disable animations for data cards requested by browsers that were detected to be WebKit-based. However, since GitHub uses anonymized URLs for the images it hosts, this approach doesn't work for data cards embedded in GitHub READMEsβthe bugginess is unavoidable for WebKit users. The only remaining options were to either disable animations on all browsers or to just let the issue persist until Apple addresses the issues with their engine. Given that less than 5% of traffic on GitHub comes from Safari or other WebKit-based browsers, the second option was the obvious choice.
In some circumstances, on mobile devices, logging in to your Spotify account after clicking the "Generate Card" button on the website fails with an error message. This is due to an issue with Spotify's Accounts service. For the best experience, please use the website on a desktop or laptop.
This project was inspired by the following projects and uses some of their code. This section is meant to give credit to the original authors and specify which code was used.
- Repo: kittinan/spotify-github-profile
- Code used:
- "Natemoo-re theme" SVG template (translated from Jinja to TSX and modified)
- "Novatorem theme" SVG template (translated from Jinja to TSX and modified)
- "Bar" HTML generation code (translated from Python to TypeScript)
- "Bar" CSS generation code (translated from Python to TypeScript)
- Repo: bchiang7/spotify-profile
- Code used:
- Loading animation markup (translated from JSX to SVG and modified)
getHashParams()
function