This API is ment to test and practise API structures. It is built to be a robust and dynamic database of songs in Rocksmith+, so that other developers could build apps and features, like song library page, or song request bots.
The API is partly maintained in worktime and partly on free time by Aun Johnsen, and any suggestions for improvements, bug reports, or ideas, can be sent to him on email skippern@gimnechiske.org.
Rocksmith+ is a guitar learning tool and game, published by Ubisoft. Anything related to the game itself should be transmitted to Ubisoft.
Any issues related to products using this API should be directed to the developers of the affected products. I will cooperate with the product developers in order to make the API service as smooth as possible, and make sure all the required data is available.
As a default, the data is presented in JSON format, but adding ?format= to the URL you can access any supported formats.
Supported formats:
We have divided access in 3 different levels. A read-only level using appid, a write level using token, and a moderator level with delete access, also using tokens.
For appid, just add ?appid={your key} to the URL to gain access.
Tokens are sent in the header. At time of writing this, one specific Authorization header is supported. If you require another specific header, contact the API administrator to see if it can be implemented.
The current supported Authorization header is similar to described in the python example:
header = {
'Authorization': "<your token here>"
}GET https://grip.gimnechiske.org/API/RSPLUS.php?appid=XXX where XXX is your appid. POST https://grip.gimnechiske.org/API/RSPLUS.php
Simple query is done through HTTP GET requests with an appid. This also accepts HTTP POST requests, all variables described for GET as put in the URL can also be sent in the POST request to obtain the same result.
By default this will return the song list with selected filters
Without any other arguments you will get only the first 20 entries. You can change the limit of entries per page by limit=15. You can use offset=20 to start at a particular number, or you can use page=2 for a certain page. Using too large limit value will result in slow response, or in worst case, server timeout.
Filters was added in version 0.1.4. Following filters are available:
arr: ai_chord, ai_bass, all_bass, bass, alt_bass, guitar, rhythm, lead, alt_lead, alt_rhythm, simple_guitar, all_keyboard, keyboard, simple_keyboard - arrangements to show. guitar is an alias for rhythm & lead + alt_rhythm & alt_lead. all_bass have been introduced as alias for bass & alt_bass. all_keyboard have been introduced as alias for keyboard & simple_keyboard.region: ISO 6133-1 alpha-2 code for individual country https://www.iso.org/obp/ui/#searchhide: hidden, workshop, noworkshop - hidden will hide songs that have been tagged as not available, workshop will hide songs that are available in the workshop, noworkshop will hide songs that not available on the workshop.q: fuzzy search in artist_name, artist_sort_name, title, and album_title collumns. Search is case insensitive, so searching for Winter and winter will yeald the same results.artist: fuzzy search in artist column only. Search is case insensitive.start_year: Show only songs released this year or later.end_year: Show only songs released until this year.genre: Show only songs of selected genre. String, comma separated list, or array of stringssort_by: Default sort order is Artist ASC Song ASC, you can alter that by the values song (Song ASC) to sort by song title, album (Album ASC Song ASC) to sort by album title, duration (Duration ASC Song ASC) to sort by song duration, and year to sort by release year (Year ASC Artist ASC Song ASC), id sorts by latest (ID DESC), plays sorts by most popular DESC (total plays all arrangements), new_arr to sort by songs by latest added arrangement, random gives a random order.id: Get data of a certain song only. If the song id doesn’t match all other search parameters, it will return an empty search.The topic keyword can be used to give other output than the songlist. The different keywords are:
admin: Meant for database maintenance, give a list of items that needs to be looked at. These lists have max size so it doesn’t give a complete picture of how much needs attention.album: Get a list of albums, or a specific album with album_id
album_id: for particular album, optionalalbum_list: an array of all album titles as an associated array with album_id as key - no metadataartist: Get a list of artists, or a specific artist with artist_id
artist_id: for particular artist, optionalartist_list: an array of all artists as an associated array with artist_id as key - no metadata
letter: a-z and #, lists artists by first letter, paginatedcredits: lists of persons given credits on songs, with list of songs, can take person ID as argument for list of songs credited to a specific person.charter: Get a list of community charters (1 is Ubisoft official), or a specific charter by charter_id
charter_id: for particular charter, optionalcharter_list an array of all charter as an associated array with charter_id as key - no metadatafeedback: Get feedback for a particular song, require rs+.
song_id: song to get feedback from, requiredfeedback_list: Get a list of open feedback and associated songs.PUT https://grip.gimnechiske.org/API/RSPLUS.php
Inserting new data is done through HTTP PUT requests with a token in the header.
Add a new song:
{
"insert": "song", // Mandatory
"new": {
"song_ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional temporarilly, will be mandatory, Ubisoft ID of song
"artist": "Iron Maiden", // Mandatory, alternatively "artist_id"
"title": "Number of the Beast", // Mandatory
"duration": "265", // Optional, song length in seconds
"album_id": "123", // Optional
"song_year": "1992", // Optional
"note": "something about this song", // Optional
"video": "https://youtube.com/?", // Optional, must be YouTube video
"genre": ["metal"], // Optional
"is_available": true, // Optional, defaults to true
"is_official_rs1": false, // Optional, defaults to false
"is_official_rs2014": false, // Optional, defaults to false
"was_in_beta": false, // Optional, defaults to false
"is_on_workshop": true, // Optional, defaults to true
"has_lyrics": true // Optional, defaults to false
}
}Add a new arrangement:
{
"insert": "arrangement", // Mandatory
"song_id": 54, // Mandatory, song_id of song from the list
"new": {
"ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional temporarilly, will be mandatory, Ubisoft ID of arrangement
"type": "lead", // Mandatory, enum, only values ai_chord, lead, rhythm, bass, or piano accepted
"verified": true, // Optional
"charter_id": "1", // Mandatory, ID of charterer, official charts should be named 1 for Ubisoft
"tuning": "Drop D", // Optional
"note": "Something about the chart", // Optional, i.e. "All solos", or "As played by Murray"
"video": "https://youtube.com/?", // Optional, link to youtube or similar with playthrough
}
}Add a new artist:
{
"insert": "artist", // Mandatory
"new": {
"ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional, currently doesn't seem to be used
"name": "(HED) Planet Earth", // Mandatory
"sort_name": "HED Planet Earth", // Optional
"alt_names": "H.E.D. Planet Earth\nHED PE", // Alternative spellings
"bio": "Something about the band, wiki type entry", // Optional
"nationality": "US" // Optional
}
}Add a new album:
{
"insert": "album", // Mandatory
"new": {
"ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional for now, will be mandatory, Ubisoft ID of album
"title": "Dark Side of the Moon", // Mandatory
"artist_id": 42, // Optional, corresponding artist ID
"year": "1973", // Optional
"cover": "https://mediawiki.com/", // Optional
"type": "studio", // Optional, default studio, other values compilation, live, extended play, single, setlist
"lable": "Harvest Records" // Optional
}
}Add a new charter:
{
"insert": "charter", // Mandatory
"new": {
"ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional
"name": "Ubisoft" // Mandatory
}
}Add feedback (Read access to send):
{
"insert": "feedback", // Mandatory
"new": {
"song_id": 1, // Mandatory
"feedback": "Something to report" // Mandatory
}
}import is a special entry meant for importing a batch of songs in one go, such as from a website scraper. All fields can, except item ID, can be omitted, but inserting items without mandatory fields (see over) will cause import to be rejected. This note does not count for imports that only UPDATE existing entries. The import engine determines if it is an INSERT or UPDATE.
{
"import": "songlist",
"batch": {
"09bf6996-bca7-45a4-bb6e-6e1b07c3b250": { // Ubi ID of song
"album_ubi_id": "749db322-489c-840b-c4f9-eb3ad9832602", // Ubi ID of album
"album_title": "Avalanche", // Name of album
"artist_name": "Mountain", // Name of artist
"song_name": "Alisan", // Song name
"song_year": 1974, // Released year
"duration": 281, // Song duration in seconds (int)
"genre": [ "rock" ], // Genres as array, all lower case
"vocals": 0, // Vocals tags, True/False or 1/0 (bool)
"is_official_rs1": 0, // RS1 DLC, True/False or 1/0 (bool)
"is_official_rs2014": 0, // RS2014 DLC, True/False or 1/0 (bool)
"was_in_beta": 0, // RS+ Beta, True/False or 1/0 (bool)
"hasOfficialBassArrangement": 1, // Has official bass arrangements, True/False or 1/0 (bool)
"hasOfficialGuitarArrangement": 1, // Has official guitar arrangements, True/False or 1/0 (bool)
"hasUGCGuitarArrangement": 0, // Has community guitar arrangements, True/False or 1/0 (bool)
"hasUGCBassArrangement": 0, // Has community bass arrangements, True/False or 1/0 (bool)
"totalArrangements": 2, // Number of arrangements on track
"videoRequest": 0, // Video request, unknown purpose, True/False or 1/0 (bool)
"bonusAvailable": 0, // Bonus available, unknown purpose, True/False or 1/0 (bool)
"tempoMapLock": 0, // Tempo Map Lock, unknown purpose, True/False or 1/0 (bool)
}
}
}{
"import": "album",
"batch": {
"e5f8f174-c8f5-caa0-8511-70b518f2c260": {
"artist": "Bill Withers",
"album_title": "Just As I Am",
"album_year": 1971
}
}
}{
"import": "regions",
"batch": {
"e5f8f174-c8f5-caa0-8511-70b518f2c260": {
"US": true,
"DE": true,
"GB": true,
"FR": true,
"CA": true,
"BR": true,
"AU": true,
"ES": true,
"DK": true,
"CO": true
}
}
}{
"import": "arrangements",
"batch": {
"e5f8f174-c8f5-caa0-8511-70b518f2c260": [
{
// Arrangement data here
"arrangement_ubi_id": "8f498819-e1cb-4d89-9b08-e77dbf808de5", // Mandatory
"charter": "Rocksmith+ Team", // Mandatory
"charter_ubi_id": "1102c4b5-91c4-4b35-aec9-ca64bde6b89d", // Mandatory for community charts
"type": "bass", // Mandatory chart type
}
]
}
}If you want to add a song and arrangement, you need to do it in two operations.
PATCH https://grip.gimnechiske.org/API/RSPLUS.php
Updating data is done through HTTP PATCH requests with a token in the header.
Edit a song:
{
"update": "song", // Mandatory
"ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional, Ubisoft ID of song
"song_id": 247, // Mandatory, song_id from the list
"update_note": "Reason for Update", // Mandatory
"artist": "Heart", // Optional, correcting the spelling of artist
"title": "Barracuda", // Optional, correcting spelling of song title
"duration": "283", // Optional, song duration in seconds
"album": "Little Queen", // Optional, alternatively "album_id"
"album_year": "1977", // Optional, not read with album_id
"album_cover": "https://commons.wikipedia.org/", // Optional, not read with album_id
"note": "Something about the song", // Optional
"video": "https://youtube.com/?", // Optional
"genre": ["rock"], // Optional
"is_available": true, // Optional
"is_official_rs1": true, // Optional
"is_official_rs2014": false, // Optional
"is_on_workshop": true, // Optional
"was_in_beta": false, // Optional
"has_lyrics": true // Optional
}Edit an arrangement:
{
"update": "arrangement", // Mandatory
"ubi_id": "cb329ea8-3d38-4680-ea2b-aa66434fed71", // Optional, Ubisoft ID of arrangement
"song_id": 2, // Mandatory
"arrangement_id": 9, // Mandatory
"type": "lead", // Optional
"charter": "Ubisoft", // Optional ---- should be removed
"tuning": "E Standard", // Optional
"note": "Something about the arrangement", // Optional
"video": "https://youtube.com/?" // Optional
}Edit region
{
"update": "region", // Mandatory
"song_id": 1, // Mandatory
"region": {
"BR": true // Mandatory, the key "BR" must be the ISO 3166-Alpha-2 code of country.
}
}For now, region only handles one argument for each call, but a future update might accept bulk edits. The key must be ISO 3166-Alpha-2, so United Kingdoms are GB for Great Britain. Unset values (NULL) can be handled as both True or False in the search, depending on the desires of the consumer app. Edited values must be set to True/False. Server default handles NULL as True.
Edit artist
{
"update": "artist", // Mandatory
"artist_id": 124, // Mandatory
"ubi_id": "", // Optional
"artist_name": "The Guess Who", // Optional
"artist_sort_name": "Guess Who, The", // Optional
"artist_alt_names": "Guess Who?", // Optional
"artist_bio": "Something about the band", // Optional, wiki-style entry in plain text or markdown
"artist_nationality": "CA", // Optional, ISO 3166-2 code if known
}Edit album
{
"update": "album", // Mandatory
"album_id": 124, // Mandatory
"ubi_id": "", // Optional
"album_title": "Smash", // Optional
"album_year": "1994", // Optional
"album_cover": "http://wikimedia.com/", // Optional URL to cover art
"album_label": "Universal Music", // Optional
"album_type": "studio" // Optional, one of studio/compilation/live/extended play/single/setlist
}Edit Album songlist order
{
"update": "album_song_order", // Mandatory
"album_id": 123, // Mandatory
"song_id": 123, // Mandatory
"position": 3 // Mandatory
}Edit charter
{
"update": "charter", // Mandatory
"charter_id": 3, // Mandatory
"ubi_id": "", // Optional
"charter_name": "ACHII", // Optional
"type": "official", // Optional, one of official/community/ai
}Edit feedback
{
"update": "feedback", // Mandatory
"feedback_id": 1, // Mandatory
"status": "completed" // Mandatory, one of read/todo/completed/spam
}The following PATCH calls require rs+mod permissions
{
"set_insert": "arrangement_type",
"arrangement_type": "piano"
}Inserts new arrangement type to arrangements enum list
{
"set_insert": "genre",
"genre": "pop"
}Inserts a new genre into songlist genre set
DELETE https://grip.gimnechiske.org/API/RSPLUS.php
Those with mod rights can delete entries through an HTTP DELETE request with a token in the header. Mind this requires a different level of access than PUT and PATCH requests.
Two inputs are accepted:
{
"delete": "song",
"song_id": 123
}This will delete a single song entry from the songlist, with all assosiated region informations and arrangements.
{
"delete": "arrangement",
"arrangement_id": 123
}This will delete one single arrangement.
{
"delete": "arrangement",
"arrangement_type": "piano"
}This will delete one arrangement type and all arrangements of that type.
{
"delete": "genre",
"genre": "pop"
}This will delete one artist and all songs of that artist
{
"delete": "artist",
"artist_id": 123
}This will delete one album and unassociate all songs from it
{
"delete": "album",
"album_id": 123
}This will delete one genre and adjust all genre entries accordingly.
Improvements to the API can be suggested to Skippern in Rocksmith community discord, or by email as described in first chapter.
This document is updated to API version 0.2.0