Hooktheory's API exposes the chord probability data used in Hooktheory's TheoryTab Search by Chords page. The API contains two endpoints: one for "next chord probabilities" and one for "songs containing a chord progression".
child_path documentationThe Hooktheory API endpoint is:
All URLs in this documentation are relative to the API endpoint shown above. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
The Hooktheory API supports JSON and XML formats. For JSON formatting please set the Accept and Content-Type request headers to "application/json". For XML formatting please set the Accept and Content-Type request headers to"application/xml". All requests in this documentation use JSON formatting.
You authenticate to the Hooktheory API by providing an HTTP Bearer Token, according to the OAuth 2 protocol. Your HTTP Bearer Token is retrieved through the API with your www.hooktheory.com username and password. To retrieve your HTTP Bearer Token, make the following request:
The body of the request must contain your www.hooktheory.com username and password:
{
"username": "Hooktheory",
"password": "0123456789"
}The response will contain three fields, as shown below:
{
"id": 1234,
"username": "Hooktheory",
"activkey": "aoa6jjacz34kcta3aomeqwuz89"
}The “activkey” property contains your HTTP Bearer Token. To authenticate future requests to the API, include the following authorization header:
| Header Name | Header Value |
Authorization
|
Bearer activkey_value
|
|---|
The name of the header is “Authorization” and its value is the string “Bearer” followed by the value of “activkey”.
The Hooktheory API limits requests to 10 every 10 seconds. Each response is sent with three headers containing the current rate limiting information:
X-Rate-Limit-Limit, the maximum number of requests allowed in the current time periodX-Rate-Limit-Remaining, the number of remaining requests in the current time periodX-Rate-Limit-Reset, the number of seconds to wait in order to get the maximum number of allowed requestsThe entry point is
The response contains an array of "node" objects, each with four properties, as shown below
[
{
"chord_ID":"1",
"chord_HTML":"I",
"probability":0.189,
"child_path":"1"
},
{
"chord_ID":"4",
"chord_HTML":"IV",
"probability":0.172,
"child_path":"4"
},
{
"chord_ID":"5",
"chord_HTML":"V",
"probability":0.157,
"child_path":"5"
},
{
"chord_ID":"6",
"chord_HTML":"vi",
"probability":0.147,
"child_path":"6"
},
{
"chord_ID":"2",
"chord_HTML":"ii",
"probability":0.049,
"child_path":"2"
},
...
]Each node contains a chord and the frequency that it occurs in the database. For example, the I chord makes up 18.9% of all chords in the database. IV is the next most frequently occurring chord and 17.2% of chords are IV. If you are not familiar with Roman numerals, you can pretend all songs in the universe were transposed to the key of C. This would say 18.9% of the chords are C Major and 17.2% of the chords are F Major.
To see what chords are most likely to come after a chord or chord progression, append its child_path to the URL as the param "cp" (short for "child path"). For example, the following request shows the chords that are most likely to come after IV, which has a child_path of 4:
[
{
"chord_ID":"1",
"chord_HTML":"I",
"probability":0.324,
"child_path":"4,1"
},
{
"chord_ID":"5",
"chord_HTML":"V",
"probability":0.289,
"child_path":"4,5"
},
{
"chord_ID":"6",
"chord_HTML":"vi",
"probability":0.102,
"child_path":"4,6"
},
{
"chord_ID":"16",
"chord_HTML":"I6",
"probability":0.053,
"child_path":"4,16"
},
{
"chord_ID":"3",
"chord_HTML":"iii",
"probability":0.045,
"child_path":"4,3"
},
...
]The I chord comes after IV chords most often, 32% of the time, the V chord next most often, 29% of the time and so on.
You can keep “propagating” down the nodes. For example, to so see what chords are most likely to follow the IV → I progression, set the value of the cp parameter to "4,1"
[
{
"chord_ID":"5",
"chord_HTML":"V",
"probability":0.436,
"child_path":"4,1,5"
},
{
"chord_ID":"4",
"chord_HTML":"IV",
"probability":0.221,
"child_path":"4,1,4"
},
{
"chord_ID":"6",
"chord_HTML":"vi",
"probability":0.105,
"child_path":"4,1,6"
},
{
"chord_ID":"3",
"chord_HTML":"iii",
"probability":0.063,
"child_path":"4,1,3"
},
{
"chord_ID":"2",
"chord_HTML":"ii",
"probability":0.037,
"child_path":"4,1,2"
},
...
]V is most likely to follow IV → I and it happens a remarkable 44% of the time.
The entry point is
The response from the entry point is an empty array. To receive a non-empty response, a "cp" parameter must be provided. To retrieve songs that use IV → I, for example, make the following request:
[
{
"artist":"Adele",
"song":"Someone Like You",
"section":"Chorus",
"url":"http://local.www.hooktheory.com/theorytab/view/adele/someone-like-you#chorus"
},
{
"artist":"Adele",
"song":"Someone Like You",
"section":"Verse",
"url":"http://local.www.hooktheory.com/theorytab/view/adele/someone-like-you#verse"
},
{
"artist":"Aerosmith",
"song":"Cryin'",
"section":"Pre-Chorus",
"url":"http://local.www.hooktheory.com/theorytab/view/aerosmith/cryin#pre-chorus"
},
{
"artist":"Aerosmith",
"song":"Cryin'",
"section":"Verse",
"url":"http://local.www.hooktheory.com/theorytab/view/aerosmith/cryin#verse"
},
{
"artist":"Alt-J",
"song":"Something Good",
"section":"Verse",
"url":"http://local.www.hooktheory.com/theorytab/view/alt-j/something-good#verse"
},
...
]Each song object contains the artist, song, section, and a URL to view the TheoryTab of the song. The response is paginated to 20 results per page. If your original response contains 20 songs, there may be more results. You can access the next page of results (#21 - #40) by appending a page number to the URL:
[
{
"artist":"Buddy Holly",
"song":"That'll Be The Day",
"section":"Verse",
"url":"http://local.www.hooktheory.com/theorytab/view/buddy-holly/thatll-be-the-day#verse"
},
{
"artist":"Carly Rae Jepsen",
"song":"Call Me Maybe",
"section":"Chorus",
"url":"http://local.www.hooktheory.com/theorytab/view/carly-rae-jepsen/call-me-maybe#chorus"
},
{
"artist":"Carrie Underwood",
"song":"So Small",
"section":"Chorus",
"url":"http://local.www.hooktheory.com/theorytab/view/carrie-underwood/so-small#chorus"
},
{
"artist":"Carrie Underwood",
"song":"So Small",
"section":"Verse",
"url":"http://local.www.hooktheory.com/theorytab/view/carrie-underwood/so-small#verse"
},
{
"artist":"Cascada",
"song":"Every Time We Touch",
"section":"Chorus",
"url":"http://local.www.hooktheory.com/theorytab/view/cascada/every-time-we-touch#chorus"
},
...
]If you go page 200, for example, the API will return an empty array since there are not 200*20 songs with IV → I (at least at the time of writing this).
child_path documentationOur user, HertzDevil, created a comprehensive child_path EBNF metasyntax that describes how to create the "cp" URL parameter of any chord. Another user, jtullis, created a similar list of API chord inputs that you may find helpful.
No and it is not on our immediate roadmap.
Not right now. We hope to build an API for all TheoryTab data in the future (and provide more related support), but right now this is not available and we are 100% focused on other products.
If you have a question about Hooktheory's API, please post it in the forum.