geniURL-Mirror

geniURL

Simple JSON and XML REST API to search for song metadata and the lyrics URL on genius.com
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 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 sometimes get blatantly wrong top matches.
Make sure the search query is percent/URL-encoded.

?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.

?format=json/xml
Use this 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": 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/...",
            "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": 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 sometimes get a blatantly wrong top match.
Make sure the search query is percent/URL-encoded.

?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.

?format=json/xml
Use this 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,
    "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/...",
        "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": 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)