# geniURL Simple JSON and XML REST API to search for song metadata and the lyrics URL on [genius](https://genius.com/) Obtaining actual lyrics sadly isn't possible yet (suggestions are welcome lol)

## Base URL: I host a public instance on this URL: ``` https://api.sv443.net/geniurl/ ``` Note that this instance is rate limited to 5 requests in 10 seconds. If you want to host your own and increase the values, look at the top of `src/server.js`

## Routes: All routes support gzip and deflate compression.
> ### GET `/search` > > This endpoint gives you the top 10 results for a search query specified by `search_text` > The returned data contains various data like the lyrics website URL, song and thumbnail metadata and more (see below). > >
> > **URL Parameters:** > `?q=search%20query` > This parameter should contain both the song and artist name (for best result artist name should come first, separate with a whitespace). > Sometimes the song name alone might be enough but the results vary greatly. > Using this parameter instead of `?artist` and `?song` will not modify the search results and so you will rarely get blatantly wrong top matches. > Make sure the search query is [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding) > > `?artist=name` and `?song=name` > Instead of `?q`, you can use `?artist` and `?song` to tell geniURL to preemptively filter the search results. > This is done using a fuzzy search to greatly increase the chances the correct search result will be at the top. > Make sure these parameters are [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding) > > `?format=json/xml` > Use this parameter to change the response format from the default (`json`) to `xml` > The structure of the data closely resembles that of the shown JSON data. > >
>
Successful response (click to view) > > ```json > { > "error": false, > "matches": 10, > "top": { > "url": "https://genius.com/Artist-1-song-name-lyrics", > "path": "/Artist-1-song-name-lyrics", > "language": "en", > "meta": { > "title": "Song Name", > "fullTitle": "Song Name by Artist 1 (ft. Artist 2)", > "artists": "Artist 1 (ft. Artist 2)", > "primaryArtist": { > "name": "Artist 1", > "url": "https://genius.com/artists/Artist-1", > "headerImage": "https://images.genius.com/...", > "image": "https://images.genius.com/..." > }, > "featuredArtists": [ > { > "name": "Featured Artist 1", > "url": "https://genius.com/artists/Featured-Artist-1", > "headerImage": "https://images.genius.com/...", > "image": "https://images.genius.com/..." > } > ], > "releaseDate": { > "year": 2018, > "month": 9, > "day": 12 > } > }, > "resources": { > "thumbnail": "https://images.genius.com/8485557225af0345d2c550af8bae731b.300x300x1.png", > "image": "https://images.genius.com/13d7b13ef827a9f007a5d24c115b9ebb.1000x1000x1.png" > }, > "lyricsState": "complete", > "id": 42069 > }, > "all": [ > "// This array contains up to 10 objects with the same structure as 'top', sorted best match first", > "// The first item of this array is exactly the same as 'top'" > ], > "timestamp": 1234567890123 > } > ``` > >
>
>
Errored response (click to view) > > ```json > { > "error": true, > "matches": null, > "message": "Something went wrong", > "timestamp": 1234567890123 > } > ``` > >
>
>
Response when no results found (click to view) > > ```json > { > "error": false, > "matches": 0, > "message": "Found no results matching your search query", > "timestamp": 1234567890123 > } > ``` > >



> ### GET `/search/top` > > This endpoint is the same as `/search`, but it only gives the top result. > Use this if you are only interested in the top result and want to reduce traffic. > >
> > **URL Parameters:** > `?q=search%20query` > This parameter should contain both the song and artist name (for best result artist name should come first, separate with a whitespace). > Sometimes the song name alone might be enough but the results vary greatly. > Using this parameter instead of `?artist` and `?song` will not modify the search result and so you will rarely get a blatantly wrong top match. > Make sure the search query is [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding) > > `?artist=name` and `?song=name` > Instead of `?q`, you can use `?artist` and `?song` to tell geniURL to preemptively filter the search results. > This is done using a fuzzy search to greatly increase the chances the correct search result will be returned. > Make sure these parameters are [percent/URL-encoded.](https://en.wikipedia.org/wiki/Percent-encoding) > > `?format=json/xml` > Use this parameter to change the response format from the default (`json`) to `xml` > The structure of the data closely resembles that of the shown JSON data. > >
>
Successful response (click to view) > > ```json > { > "error": false, > "matches": 1, > "url": "https://genius.com/Artist-1-song-name-lyrics", > "path": "/Artist-1-song-name-lyrics", > "language": "en", > "meta": { > "title": "Song Name", > "fullTitle": "Song Name by Artist 1 (ft. Artist 2)", > "artists": "Artist 1 (ft. Artist 2)", > "primaryArtist": { > "name": "Artist 1", > "url": "https://genius.com/artists/Artist-1", > "headerImage": "https://images.genius.com/...", > "image": "https://images.genius.com/..." > }, > "featuredArtists": [ > { > "name": "Featured Artist 1", > "url": "https://genius.com/artists/Featured-Artist-1", > "headerImage": "https://images.genius.com/...", > "image": "https://images.genius.com/..." > } > ], > "releaseDate": { > "year": 2018, > "month": 9, > "day": 12 > } > }, > "resources": { > "thumbnail": "https://images.genius.com/8485557225af0345d2c550af8bae731b.300x300x1.png", > "image": "https://images.genius.com/13d7b13ef827a9f007a5d24c115b9ebb.1000x1000x1.png" > }, > "lyricsState": "complete", > "id": 42069, > "timestamp": 1234567890123 > } > ``` > >
>
>
Errored response (click to view) > > ```json > { > "error": true, > "matches": null, > "message": "Something went wrong", > "timestamp": 1234567890123 > } > ``` > >
>
>
Response when no result found (click to view) > > ```json > { > "error": false, > "matches": 0, > "message": "Found no results matching your search query", > "timestamp": 1234567890123 > } > ``` > >



Made with ❤️ by [Sv443](https://sv443.net/) If you like geniURL, please consider [supporting the development](https://github.com/sponsors/Sv443)