geniURL-Mirror

geniURL

Simple JSON and XML REST API to search for song metadata, the lyrics URL and lyrics translations on genius.com
Authorization is not required and geniURL implements a fuzzy search that will greatly improve search results over the genius.com API.

Obtaining actual lyrics sadly isn't possible due to licensing and copyright reasons.

Try it out:

For trying out geniURL yourself, you can use this Postman workspace.
To download it and test locally, hover over the collection, click the three-dot-menu and then "Export"

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 within 10 seconds.
If you want to host your own and increase the values, look at the top of src/server.ts}

Routes:

All routes support gzip and deflate compression.

• Search
  • Search (only top result)
• Translations

GET /search

This endpoint gives you up to 10 results for a search query specified by search_text
The returned payload 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 or hyphen.
Sometimes the song name alone might be enough but the results vary greatly.
Using this parameter instead of ?artist and ?song means you will get slightly less accurate results.
Make sure the search query is percent/URL-encoded.

OR

?artist=name and ?song=name
Instead of ?q, you can use ?artist and ?song to help geniURL filter the search results a little better.
Make sure these parameters are percent/URL-encoded.

Optional URL Parameters:
?preferLang=en
Sometimes the genius API and geniURL's filtering will rank song translations or remixes higher than the original song. This optional parameter can help with that.
Specify a two-character ISO 639-1 language code here to tell geniURL to prefer results of that language.
Note that this only changes the ranking. Results of other languages will still be returned.

?format=json/xml
Use this optional parameter to change the response format from the default (json) to xml
The structure of the XML data is similar to the shown JSON data.

?threshold=0.65
This optional parameter can be used to change the fuzzy search threshold from the default of 0.65
It 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.
0.65 is a good middle ground but depending on your use-case you might want to play around with this.

Response:

Successful response (click to view)

{
    "error": false,
    "matches": 10,
    "top": {
        "url": "https://genius.com/Artist-Foo-song-name-lyrics",
        "path": "/Artist-Foo-song-name-lyrics",
        "language": "en",
        "meta": {
            "title": "Song Name",
            "fullTitle": "Song Name by Artist Foo (ft. Artist Bar)",
            "artists": "Artist Foo (ft. Artist Bar)",
            "primaryArtist": {
                "name": "Artist Foo",
                "url": "https://genius.com/artists/Artist-Foo",
                "headerImage": "https://images.genius.com/...",
                "image": "https://images.genius.com/..."
            },
            "featuredArtists": [
                {
                    "name": "Artist Bar",
                    "url": "https://genius.com/artists/Artist-Bar",
                    "headerImage": "https://images.genius.com/...",
                    "image": "https://images.genius.com/..."
                }
            ],
            "releaseDate": {
                "year": 2018,
                "month": 9,
                "day": 12
            }
        },
        "resources": {
            "thumbnail": "https://images.genius.com/...",
            "image": "https://images.genius.com/..."
        },
        "lyricsState": "complete",
        "id": 42069
    },
    "all": [
        // This array contains up to 10 objects with the same structure as 'top', sorted best match first
        // The amount of objects in here is the same as the 'matches' property
        // The first object of this array is exactly the same as 'top'
    ],
    "timestamp": 1234567890123
}

Errored response (click to view)

{
    "error": true,
    "matches": null,
    "message": "Something went wrong",
    "timestamp": 1234567890123
}

Response when no results found (click to view)

{
    "error": true,
    "matches": 0,
    "message": "Found no results matching your search query",
    "timestamp": 1234567890123
}

GET /search/top

This endpoint is similar to /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 or hyphen.
Sometimes the song name alone might be enough but the results vary greatly.
Using this parameter instead of ?artist and ?song means you will get slightly less accurate results.
Make sure the search query is percent/URL-encoded.

OR

?artist=name and ?song=name
Instead of ?q, you can use ?artist and ?song to help geniURL filter the search results a little better.
Make sure these parameters are percent/URL-encoded.

Optional URL Parameters:
?preferLang=en
Sometimes the genius API and geniURL's filtering will rank song translations or remixes higher than the original song. This optional parameter can help with that.
Specify a two-character ISO 639-1 language code here to tell geniURL to prefer results of that language.
Note that this only changes the ranking. Results of other languages will still be returned.

?format=json/xml
Use this optional parameter to change the response format from the default (json) to xml
The structure of the XML data is similar to the shown JSON data.

?threshold=0.65
This optional parameter can be used to change the fuzzy search threshold from the default of 0.65
It 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.
0.65 is a good middle ground but depending on your use-case you might want to play around with this.

Response:

Successful response (click to view)

{
    "error": false,
    "matches": 1,
    "url": "https://genius.com/Artist-Foo-song-name-lyrics",
    "path": "/Artist-Foo-song-name-lyrics",
    "language": "en",
    "meta": {
        "title": "Song Name",
        "fullTitle": "Song Name by Artist Foo (ft. Artist Bar)",
        "artists": "Artist Foo (ft. Artist Bar)",
        "primaryArtist": {
            "name": "Artist Foo",
            "url": "https://genius.com/artists/Artist-Foo",
            "headerImage": "https://images.genius.com/...",
            "image": "https://images.genius.com/..."
        },
        "featuredArtists": [
            {
                "name": "Artist Bar",
                "url": "https://genius.com/artists/Artist-Bar",
                "headerImage": "https://images.genius.com/...",
                "image": "https://images.genius.com/..."
            }
        ],
        "releaseDate": {
            "year": 2018,
            "month": 9,
            "day": 12
        }
    },
    "resources": {
        "thumbnail": "https://images.genius.com/...",
        "image": "https://images.genius.com/..."
    },
    "lyricsState": "complete",
    "id": 42069,
    "timestamp": 1234567890123
}

Errored response (click to view)

{
    "error": true,
    "matches": null,
    "message": "Something went wrong",
    "timestamp": 1234567890123
}

Response when no result found (click to view)

{
    "error": true,
    "matches": 0,
    "message": "Found no results matching your search query",
    "timestamp": 1234567890123
}

GET /translations/:songId

This endpoint returns all translations of a certain song.
Specify the song ID, gotten from the /search/ endpoints, in the URL path.
Example: /translations/3093344

Optional URL Parameters:
?preferLang=en
The filtering done by the genius API and geniURL will sometimes produce results that are ranked inconsistently. This optional parameter can help with that.
Specify a two-character ISO 639-1 language code here to tell geniURL to prefer results of that language.
Note that this only changes the ranking. Results of other languages will still be returned.

?format=json/xml
Use this optional parameter to change the response format from the default (json) to xml
The structure of the XML data is similar to the shown JSON data.

Response:

Successful response (click to view)

{
    "error": false,
    "matches": 1,
    "translations": [
        {
            "language": "es",
            "title": "Artist - Song (Traducción al Español)",
            "url": "https://genius.com/Genius-traducciones-al-espanol-artist-song-al-espanol-lyrics",
            "path": "/Genius-traducciones-al-espanol-artist-song-al-espanol-lyrics",
            "id": 6942
        }
    ],
    "timestamp": 1234567890123
}

Errored response (click to view)

{
    "error": true,
    "matches": null,
    "message": "Something went wrong",
    "timestamp": 1234567890123
}

Response when no result found (click to view)

{
    "error": false,
    "matches": 0,
    "translations": [],
    "timestamp": 1234567890123
}

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