{"id":13911067,"url":"https://github.com/Sv443/geniURL","last_synced_at":"2025-07-18T10:32:15.901Z","repository":{"id":97407701,"uuid":"462902874","full_name":"Sv443/geniURL","owner":"Sv443","description":"REST API that searches for song metadata, including the lyrics URL, translations and more from genius.com - supports JSON and XML","archived":false,"fork":false,"pushed_at":"2025-01-30T22:35:03.000Z","size":811,"stargazers_count":8,"open_issues_count":8,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-01T03:06:44.814Z","etag":null,"topics":["api","json","lyrics-search","music","music-information-retrieval","music-search","rest-api","song-data","xml"],"latest_commit_sha":null,"homepage":"https://api.sv443.net/geniurl/search?q=Michael%20Jackson%20Thriller\u0026disableFuzzy","language":"TypeScript","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/Sv443.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2022-02-23T20:56:21.000Z","updated_at":"2025-04-27T23:10:06.000Z","dependencies_parsed_at":"2024-12-10T13:35:46.831Z","dependency_job_id":"4e518e0c-6c1b-4680-b227-fe47f5b9d343","html_url":"https://github.com/Sv443/geniURL","commit_stats":{"total_commits":105,"total_committers":4,"mean_commits":26.25,"dds":"0.37142857142857144","last_synced_commit":"14dc2841c2eea8be3fff161be4e733f00c2d4980"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Sv443/geniURL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sv443%2FgeniURL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sv443%2FgeniURL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sv443%2FgeniURL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sv443%2FgeniURL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sv443","download_url":"https://codeload.github.com/Sv443/geniURL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sv443%2FgeniURL/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265742388,"owners_count":23820836,"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","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":["api","json","lyrics-search","music","music-information-retrieval","music-search","rest-api","song-data","xml"],"created_at":"2024-08-07T00:01:56.099Z","updated_at":"2025-07-18T10:32:15.550Z","avatar_url":"https://github.com/Sv443.png","language":"TypeScript","readme":"# geniURL\nSimple JSON and XML REST API to search for song metadata, the lyrics URL and lyrics translations on [genius.com](https://genius.com/)  \nAuthorization is not required and geniURL implements a fuzzy search that will greatly improve search results over the genius.com API.  \nObtaining actual lyrics sadly isn't possible.  \n  \nLike geniURL? Please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)  \n  \nDisclaimer: this project is not affiliated with or endorsed by Genius.\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Try it out:\nFor trying out geniURL yourself, you can use [this Postman workspace.](https://www.postman.com/sv443/workspace/geniurl)  \nTo download it and test locally, hover over the collection, click the three-dot-menu and then \"Export\"\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Base URL:\nI host a public instance on this base URL:\n```\nhttps://api.sv443.net/geniurl/\n```\n\nNote: this instance is rate limited to 25 requests within a 30 second timeframe.  \nTo always know how many requests you are able to send, refer to the response headers `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`\n\n\n\u003cbr\u003e\u003cbr\u003e\n\n## Routes:\nAll routes support gzip, deflate and brotli compression.  \n  \nAlso all routes always return the properties `error` and `matches`.  \nThey can be used to determine whether a response has succeeded (error = false, matches \u003e 0), is errored (error = true, matches = null) or just didn't yield any results (error = true, matches = 0).  \n  \nThese are the available routes:\n- [Search](#get-search)\n    - [Search (only top result)](#get-searchtop)\n- [Translations](#get-translationssongid)\n- [Associated Album](#get-albumsongid)\n\n\u003cbr\u003e\u003cbr\u003e\n\n### GET `/search`\n\nThis route gives you up to 10 results for a provided search query.  \nThe returned payload contains various data like the lyrics website URL, song and thumbnail metadata and more (see below).\n\n\u003cbr\u003e\n\n**URL Parameters:**  \n`?q=search%20query`  \nThis parameter should contain both the song and artist name. For best result artist name should come first, separate with a whitespace or hyphen.  \nSometimes the song name alone might be enough but the results vary greatly.  \nIf you want to search for a remix (like `?q=Artist - Song (Artist2 Remix)`), this parameter will yield better results.  \nMake sure the search query is [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding)  \n\n**OR**\n\n`?artist=name` and `?song=name`  \nInstead of `?q`, you can also use `?artist` and `?song`.  \nMake sure these parameters are [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding)\n\n\u003cbr\u003e\n\n**Optional URL Parameters:**  \n`?format=json/xml`  \nUse this optional parameter to change the response format from the default (`json`) to `xml`  \nThe structure of the XML data is similar to the shown JSON data.\n  \n`?threshold=0.65`  \nThis optional parameter can be used to change the fuzzy search threshold from the default of 0.65  \nIt has to be between 0.0 and 1.0; the lower the number, the less results you'll get but the more accurate the top results will be.  \n0.65 is a good middle ground but depending on your use-case you might want to play around with this.\n  \n`?disableFuzzy`  \nThis optional and value-less parameter can be used to disable the fuzzy search entirely.  \nBecause the current fuzzy search implementation is not as accurate as it should be, your application might need the search results as they come from the genius API.\n\n\u003cbr\u003e\n\n**Response:**  \n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eSuccessful response (click to view)\u003c/b\u003e\u003c/summary\u003e\n\n```jsonc\n{\n    \"error\": false,\n    \"matches\": 10,\n    \"top\": {\n        \"url\": \"https://genius.com/Artist-Foo-song-name-lyrics\",\n        \"path\": \"/Artist-Foo-song-name-lyrics\",\n        \"language\": \"en\",\n        \"meta\": {\n            \"title\": \"Song Name\",\n            \"fullTitle\": \"Song Name by Artist Foo (ft. Artist Bar)\",\n            \"artists\": \"Artist Foo (ft. Artist Bar)\",\n            \"primaryArtist\": {\n                \"name\": \"Artist Foo\",\n                \"url\": \"https://genius.com/artists/Artist-Foo\",\n                \"headerImage\": \"https://images.genius.com/...\",\n                \"image\": \"https://images.genius.com/...\"\n            },\n            \"featuredArtists\": [\n                {\n                    \"name\": \"Artist Bar\",\n                    \"url\": \"https://genius.com/artists/Artist-Bar\",\n                    \"headerImage\": \"https://images.genius.com/...\",\n                    \"image\": \"https://images.genius.com/...\"\n                }\n            ],\n            \"releaseDate\": {\n                \"year\": 2018,\n                \"month\": 9,\n                \"day\": 12\n            }\n        },\n        \"resources\": {\n            \"thumbnail\": \"https://images.genius.com/...\",\n            \"image\": \"https://images.genius.com/...\"\n        },\n        \"lyricsState\": \"complete\",\n        \"id\": 42069\n    },\n    \"all\": [\n        // This array contains up to 10 objects with the same structure as 'top', sorted best match first\n        // The amount of objects in here is the same as the 'matches' property\n        // The first object of this array is exactly the same as 'top'\n    ]\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eErrored response (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": null,\n    \"message\": \"Something went wrong\"\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eResponse when no results found (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": 0,\n    \"message\": \"Found no results matching your search query\"\n}\n```\n\n\u003c/details\u003e\u003cbr\u003e\n\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\n\n### GET `/search/top`\n\nThis route is similar to `/search`, but it only gives the top result.  \nUse this if you are only interested in the top result and want to reduce traffic.\n\n\u003cbr\u003e\n\n**URL Parameters:**  \n`?q=search%20query`  \nThis parameter should contain both the song and artist name. For best result artist name should come first, separate with a whitespace or hyphen.  \nSometimes the song name alone might be enough but the results vary greatly.  \nIf you want to search for a remix (like `?q=Artist - Song (Artist2 Remix)`), this parameter will yield better results.  \nMake sure the search query is [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding)  \n\n**OR**\n\n`?artist=name` and `?song=name`  \nInstead of `?q`, you can also use `?artist` and `?song`.  \nMake sure these parameters are [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding)\n\n\u003cbr\u003e\u003cbr\u003e\n\n**Optional URL Parameters:**  \n`?format=json/xml`  \nUse this optional parameter to change the response format from the default (`json`) to `xml`  \nThe structure of the XML data is similar to the shown JSON data.\n  \n`?threshold=0.65`  \nThis optional parameter can be used to change the fuzzy search threshold from the default of 0.65  \nIt has to be between 0.0 and 1.0; the lower the number, the less results you'll get but the more accurate the top results will be.  \n0.65 is a good middle ground but depending on your use-case you might want to play around with this.\n  \n`?disableFuzzy`  \nThis optional and value-less parameter can be used to disable the fuzzy search entirely.  \nBecause the current fuzzy search implementation is not as accurate as it should be, your application might need the search results as they come from the genius API.\n\n\u003cbr\u003e\n\n**Response:**  \n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eSuccessful response (click to view)\u003c/b\u003e\u003c/summary\u003e\n\n```jsonc\n{\n    \"error\": false,\n    \"matches\": 1,\n    \"url\": \"https://genius.com/Artist-Foo-song-name-lyrics\",\n    \"path\": \"/Artist-Foo-song-name-lyrics\",\n    \"language\": \"en\",\n    \"meta\": {\n        \"title\": \"Song Name\",\n        \"fullTitle\": \"Song Name by Artist Foo (ft. Artist Bar)\",\n        \"artists\": \"Artist Foo (ft. Artist Bar)\",\n        \"primaryArtist\": {\n            \"name\": \"Artist Foo\",\n            \"url\": \"https://genius.com/artists/Artist-Foo\",\n            \"headerImage\": \"https://images.genius.com/...\",\n            \"image\": \"https://images.genius.com/...\"\n        },\n        \"featuredArtists\": [\n            {\n                \"name\": \"Artist Bar\",\n                \"url\": \"https://genius.com/artists/Artist-Bar\",\n                \"headerImage\": \"https://images.genius.com/...\",\n                \"image\": \"https://images.genius.com/...\"\n            }\n        ],\n        \"releaseDate\": {\n            \"year\": 2018,\n            \"month\": 9,\n            \"day\": 12\n        }\n    },\n    \"resources\": {\n        \"thumbnail\": \"https://images.genius.com/...\",\n        \"image\": \"https://images.genius.com/...\"\n    },\n    \"lyricsState\": \"complete\",\n    \"id\": 42069\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eErrored response (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": null,\n    \"message\": \"Something went wrong\"\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eResponse when no result found (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": 0,\n    \"message\": \"Found no results matching your search query\"\n}\n```\n\n\u003c/details\u003e\u003cbr\u003e\n\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\n\n### GET `/translations/:songId`\n\nThis route returns all translations of a certain song.  \nGet the song ID from one of the [search routes.](#routes)  \nExample: `/translations/1644`\n\n\u003cbr\u003e\n\n**Optional URL Parameters:**  \n`?format=json/xml`  \nUse this optional parameter to change the response format from the default (`json`) to `xml`  \nThe structure of the XML data is similar to the shown JSON data.\n\n\u003cbr\u003e\n\n**Response:**  \n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eSuccessful response (click to view)\u003c/b\u003e\u003c/summary\u003e\n\n```jsonc\n{\n    \"error\": false,\n    \"matches\": 1,\n    \"translations\": [\n        {\n            \"language\": \"es\",\n            \"title\": \"Artist - Song (Traducción al Español)\",\n            \"url\": \"https://genius.com/Genius-traducciones-al-espanol-artist-song-al-espanol-lyrics\",\n            \"path\": \"/Genius-traducciones-al-espanol-artist-song-al-espanol-lyrics\",\n            \"id\": 6942\n        }\n    ]\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eErrored response (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": null,\n    \"message\": \"Something went wrong\"\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eResponse when no result found (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": 0,\n    \"translations\": []\n}\n```\n\n\u003c/details\u003e\u003cbr\u003e\n\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\n\n### GET `/album/:songId`\n\nThis route returns any associated album for a specified song.  \nGet the song ID from one of the [search routes.](#routes)  \nExample: `/album/1644`\n\n\u003cbr\u003e\n\n**Optional URL Parameters:**  \n`?format=json/xml`  \nUse this optional parameter to change the response format from the default (`json`) to `xml`  \nThe structure of the XML data is similar to the shown JSON data.\n\n\u003cbr\u003e\n\n**Response:**  \n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eSuccessful response (click to view)\u003c/b\u003e\u003c/summary\u003e\n\n```jsonc\n{\n    \"error\": false,\n    \"matches\": 1,\n    \"album\": {\n        \"name\": \"Album\",\n        \"fullTitle\": \"Song by Artist\",\n        \"url\": \"https://genius.com/albums/Artist/Album\",\n        \"coverArt\": \"https://images.genius.com/...\",\n        \"id\": 12345,\n        \"artist\": {\n            \"name\": \"Artist\",\n            \"url\": \"https://genius.com/artists/Artist\",\n            \"image\": \"https://images.genius.com/...\",\n            \"headerImage\": \"https://images.genius.com/...\"\n        }\n    }\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eErrored response (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": null,\n    \"message\": \"Something went wrong\"\n}\n```\n\n\u003c/details\u003e\n\u003cbr\u003e\n\u003cdetails\u003e\u003csummary\u003eResponse when no result found (click to view)\u003c/summary\u003e\n\n```json\n{\n    \"error\": true,\n    \"matches\": 0,\n    \"message\": \"Couldn't find any associated album for this song\"\n}\n```\n\n\u003c/details\u003e\u003cbr\u003e\n\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\n\n\u003cdiv align=\"center\" style=\"text-align:center;\"\u003e\n\nMade with ❤️ by [Sv443](https://sv443.net/)  \nIf you like geniURL, please consider [supporting the development](https://github.com/sponsors/Sv443)\n\n\u003c/div\u003e\n","funding_links":["https://github.com/sponsors/Sv443"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSv443%2FgeniURL","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSv443%2FgeniURL","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSv443%2FgeniURL/lists"}