API Documentation

Hooktheory's API exposes the chord probability data used in Hooktheory's Theorytab Trends page. The API contains two endpoints: one for "next chord probabilities" and one for "songs containing a chord progression".

Contents

  1. API endpoint
  2. Response formatting
  3. Authentication
  4. Rate limiting
  5. Next chord probabilities
  6. Songs containing a chord progression
  7. Advanced child_path documentation
  8. Showcase
  9. Q & A

API Endpoint

The Hooktheory API endpoint is:

https://api.hooktheory.com/v1/

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.

Response formatting

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.

Authentication

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:

POST users/auth

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

Rate limiting

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 period
  • X-Rate-Limit-Remaining, the number of remaining requests in the current time period
  • X-Rate-Limit-Reset, the number of seconds to wait in order to get the maximum number of allowed requests

Next chord probabilities

The entry point is

GET trends/nodes

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:

GET trends/nodes?cp=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 IVI progression, set the value of the cp parameter to "4,1"

GET trends/nodes?cp=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 IVI and it happens a remarkable 44% of the time.

Songs containing a chord progression

The entry point is

GET trends/songs

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 IVI, for example, make the following request:

GET trends/songs?cp=4,1
[  
   {  
	  "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:

GET trends/songs?cp=4,1&page=2
[  
   {  
	  "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 IVI (at least at the time of writing this).

Advanced child_path documentation

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

Showcase

Q & A

Do you have "Trends for melody" data available?

No and it is not on our immediate roadmap.

Can I get a full dump of Theorytab data for research?

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.