Uberchord API guide

Table of Contents

• What is Uberchord API?
• Getting started
• Guitar chords
  • chordName pattern
    • Example: E^7#5#9
    • Example: B♭
    • Example: A/C#
    • Example: F_maj^{7#11♭6♭13(omit 3)}
  • strings pattern
    • Example: C⁷
  • fingering pattern
    • Example: C
    • Example: A♭_maj^79(add11)
• Chords searching
  • Get an exact chord
    • Example: get the F_maj⁷ chord
    • Example: get the B♭ chord
  • Searching multiple chords by name
    • Example: searching for chords like Fmaj7
  • Searching multiple chords by exact names
    • Example: getting F_maj⁷ and E_m^7♭5 chords
  • Searching multiple chords by voicing pattern
    • Example: getting chords that match 1 X 2 2 1 0 and 0 X 2 4 2 4 patterns
• Songs
  • Song resource
  • Sharing a song
    • Example: sharing a song without a thumbnail
    • Example: sharing a song with a thumbnail
  • Retrieving a shared song
    • Example: retrieving song available under https://song.uberchord.com/QLrnvJcIOu url
• Embeddable content
  • Iframe custom dimensions
  • Iframe auto-size mode
  • Customize Chord Search title and description
  • Uberchord Embed SDK
    • Embedded Song
    • Embedded Chord
    • Embedded Chords (multiple)
    • Common attributes in Uberchord Embed SDK
  • Embedded code snippet generator
    • Extra options
    • Example: https://song.uberchord.com/QLrnvJcIOu song
    • Example: chords with names like Em7
    • Example: chords with name like F - custom iframe dimensions
    • Example: chords with name like Fmaj - custom song title and description

What is Uberchord API?

Uberchord API is a RESTful API that provides the following features:

• Searching for guitar chords

• Sharing and retrieving songs

• Embedding the chords on your website

Getting started

The current version of the Uberchord API is located under the following URL:

https://api.uberchord.com/v1

To see what endpoints are available and more detailed information about them, please visit Uberchord API Reference.

This guide will describe the basic concepts of the API and examples of API usage.

Guitar chords

One of the key structure which appears across the Uberchord API is object that contains information about the chord. The data from this object is information that is sufficient to render a specific chord's diagram. The Chord objects consist of the following properties:

chordName pattern

The chord name consists of the following pattern:

root,quality,tension,bass

Example: E^7#5#9

Not all components of the pattern are required, for instance:

E,,7#5#9

Components are interpreted as follows:

  root    = E
  quality = empty
  tension = 7#5#9
  bass    = empty

Example: B♭

For "bemolle" music character use lower case "b" letter:

Bb

Components are interpreted as follows:

  root    = Bb
  quality = empty
  tension = empty
  bass    = empty

Example: A/C#

A,,,C#

Components are interpreted as follows:

  root    = A
  quality = empty
  tension = empty
  bass    = C#

Example: F_maj^{7#11♭6♭13(omit 3)}

F,maj,7#11b6b13(omit 3)

Components are interpreted as follows:

  root    = F
  quality = maj
  tension = 7#11b6b13(omit 3)
  bass    = empty

strings pattern

strings pattern generally consists of numbers of frets that has to be fingered down by a guitarist for each specific string. Although, because often not all strings are fingered, there are two additional special symbols reserved:

• 0 (zero) - used when string stays opened
• X - used when string is not played

The pattern elements (fret numbers) are ordered from the highest to the lowest string and each element is separated by space character.

Example: C⁷

strings value for the above chord (represented on the diagram) is:

X 3 2 3 1 0

We start from the bottom (the highest string). Special character X means that string is not played. Next 4 numbers (3, 2, 3, 1) are correct fret numbers, hence they correspond to the black dots on the diagram. The last element which is left is 0 character, so it is represented as an open string in the chord diagram.

fingering pattern

fingering pattern looks similarly to the strings pattern. The element values of which it consists of also correspond to the strings in order from the highest string to the lowest string as it is in strings pattern. However, the values inside this pattern are finger numbers to be denoted on finger down dots presented on chord diagrams.

As it was highlighted in the strings pattern, often not all strings are fingered down by the guitarist. Hence, analogously to the strings pattern, there is special symbol X used for strings that are not fingered down (namely opened or not played strings).

Sometimes it is more handy for the guitarist to finger down more than one string by using same finger:

To describe such case in the fingering, finger number should appear more than once. The finger numbers for this case should appear for the highest and the lowest string which should be covered by fingering down. See also A♭_maj^79(add11) in the examples list below.

Example: C

fingering value for the above chord is:

X 1 2 X 3 X

Example: A♭_maj^79(add11)

fingering value for the above chord is:

2 1 3 1 4 X

Chords searching

Uberchord API contains a big database of guitar chords that can be queried.

Get an exact chord

You can get the one specific chord by it's unique name through: https://api.uberchord.com/v1/chords/{chordName} endpoint (GET method) where:

• {chordName} - is a chord name which conists of the 3 following components:
  • root
  • quality & tension
  • bass

The {chordName} pattern is similar to the pattern described in "chordName pattern" section, except that quality and tension components are merged into one. That is due to the fact that diagram renderer has to render the quality and tension chord name parts separately, so separated quality & tension components are more comfortable for rendering. However, for quering the database, these parts doesn't have to be separated.

As a response to this request the JSON object with the specific chord data is returned with the same properties that are described in "Guitar chords" section.

Example: get the F_maj⁷ chord

To get exactly the F_maj⁷ chord, the following URL can be used:

https://api.uberchord.com/v1/chords/F_maj7

Note that _ is used as a separator for the chord in the API call.

The response:

{
  "strings": "1 X 2 2 1 0",
  "fingering": "1 X 3 4 2 X",
  "chordName": "F,maj,7,"
  }

Example: get the B♭ chord

For chords that contain "bemolle" character in their names, just replace that character with b character:

https://api.uberchord.com/v1/chords/Bb

The response:

{
  "strings": "X 1 3 3 3 1",
  "fingering": "X 1 2 3 4 1",
  "chordName": "Bb,,,"
  }

Searching multiple chords by name

The chords with names that does not have to match exactly to the provided name, can be search through: https://api.uberchord.com/v1/chords?nameLike={chordName} endpoint (GET method) where:

• {chordName} is a chord name that doesn't have to be exact.

Example: searching for chords like Fmaj7

Requesting the https://api.uberchord.com/v1/chords?nameLike=F_maj7 URL will produce the following result as a response:

[
  {
  "strings": "1 X 2 2 1 0",
  "fingering": "1 X 3 4 2 X",
  "chordName": "F,maj,7,"
  },
  {
  "strings": "1 0 2 0 X X",
  "fingering": "1 X 3 X X X",
  "chordName": "F,maj,79,"
  },
  {
  "strings": "1 X 2 2 3 X",
  "fingering": "1 X 2 3 4 X",
  "chordName": "F,maj,713,"
  },
  {
  "strings": "1 X 2 2 2 0",
  "fingering": "1 X 2 3 4 X",
  "chordName": "F,maj,7#5,"
  },
  {
  "strings": "1 3 2 1 1 4",
  "fingering": "1 3 2 1 1 4",
  "chordName": "F,m,maj7,"
  },
  {
  "strings": "1 X 2 1 1 3",
  "fingering": "1 X 2 1 1 4",
  "chordName": "F,m,maj79,"
  },
  ...
  ]

The ellipsis has been placed in the response code above to cut the original response that is a bit longer.

As you can see, chords like F_maj⁷⁹ or F_m^maj7 are listed in the results even that the first F_maj⁷ is the perfect match.

Searching multiple chords by exact names

To get multiple chords that have exact names use: https://api.uberchord.com/v1/chords?names={chordNames} endpoint (GET method) where:

• {chordNames} consists of the list of the chord names separated by , (comma) character.

Example: getting F_maj⁷ and E_m^7♭5 chords

To get the chords from the example's title GET request has to be sent to the following URL:

https://api.uberchord.com/v1/chords?names=F_maj7,E_m7b5

As a response the following JSON array will be returned:

[
  {
  "strings": "1 X 2 2 1 0",
  "fingering": "1 X 3 4 2 X",
  "chordName": "F,maj,7,"
  },
  {
  "strings": "0 X 0 3 3 3",
  "fingering": "X X X 2 3 4",
  "chordName": "E,m,7b5,"
  }
  ]

Searching multiple chords by voicing pattern

You can search for chords where fingers are down on specific frets. In other words, you can search by strings attribute. To to that, send GET request to the https://api.uberchord.com/v1/chords?voicing={voicings} endpoint where:

• {voicings} contains string patterns like strings chord attibute values except that spaces are replaced with - (hyphen) character. Specific patterns are separated by , character.

Example: getting chords that match 1 X 2 2 1 0 and 0 X 2 4 2 4 patterns

For instance the URL:

https://api.uberchord.com/v1/chords?voicing=1-X-2-2-1-0,0-X-2-4-2-4

will result with the F_maj⁷ and E⁶ chords as they match the provided patterns:

[
  {
  "strings": "1 X 2 2 1 0",
  "fingering": "1 X 3 4 2 X",
  "chordName": "F,maj,7,"
  },
  {
  "strings": "0 X 2 4 2 4",
  "fingering": "X X 1 3 1 4",
  "chordName": "E,,6,"
  }
  ]

Songs

Song resource

Uberchord API enables you to share songs. Songs are resources which consists of the following attributes:

Sharing a song

You can store the song through the API and it will be instantly available under a unique URL which can be shared with friends. To do so, you should send a POST request to the https://api.uberchord.com/v1/song endpoint with Content-Type: application/json header and JSON object in the request body which consists of parameters described in "Song resource" section, excluding read-only parameters (id and url).

Example: sharing a song without a thumbnail

Request URL: https://api.uberchord.com/v1/song
Method: POST
Header: Content-Type: application/json
Body:

{
  "title": "I've played it yesterday",
  "type": "song",
  "description": "My first own chord progression, inspired by the Beatles.",
  "thumbnail_data": "",
  "voicings": [
  {
  "strings": "X 0 2 0 2 0",
  "fingering": "X X 1 X 2 X",
  "chord_name": "A,,7"
  },
  {
  "strings": "X X 0 2 3 1",
  "fingering": "X X X 1 2 3",
  "chord_name": "D,m"
  },
  {
  "strings": "X X 3 3 3 1",
  "fingering": "X X 1 2 3 4",
  "chord_name": "Bb"
  },
  {
  "strings": "X 3 2 3 1 0",
  "fingering": "X 1 2 3 4 X",
  "chord_name": "C,,7"
  },
  {
  "strings": "X 3 2 0 1 0",
  "fingering": "X 1 2 X 3 X",
  "chord_name": "C"
  },
  {
  "strings": "X X 0 2 3 1",
  "fingering": "X X X 1 2 3",
  "chord_name": "D,m"
  },
  {
  "strings": "3 2 0 0 0 1",
  "fingering": "1 2 X X X 3",
  "chord_name": "G,,7"
  },
  {
  "strings": "X X 3 2 1 1",
  "fingering": "X X 1 2 3 3",
  "chord_name": "F"
  },
  {
  "strings": "0 2 2 0 3 0",
  "fingering": "X 1 2 0 3 0",
  "chord_name": "E,m,7"
  },
  {
  "strings": "X X 3 2 1 1",
  "fingering": "X X 1 2 3 3",
  "chord_name": "F"
  }
  ]
  }

Example: sharing a song with a thumbnail

Request URL: https://api.uberchord.com/v1/song
Method: POST
Header: Content-Type: application/json
Body:
Body content has been separated to another file which is available here: song_with_thumbnail.json

Retrieving a shared song

To retrive a specific song, you must know it's unique id identifier. You can request a song by using the https://api.uberchord.com/v1/song/{songId} endpoint (GET method) where {songId} is an unique id identifier of a song.

As a response, JSON with the song data will be returned which is compliant with the table in "Song resource" section.

Example: retrieving song available under https://song.uberchord.com/QLrnvJcIOu url

If we have a link to the shared song, we can easily extract the song's id identifier. Basically, the id always comes after the last slash character in the song.uberchord.com/... URL. So in our case, id is equal to QLrnvJcIOu and we can get the song's JSON through the following URL:

https://api.uberchord.com/v1/song/QLrnvJcIOu

Embeddable content

Uberchord API enables you to embed songs and collections of chord diagrams which are available in the search API. Song and chord search API endpoints can be prefixed with "/embed" path node for instance:

https://api.uberchord.com/v1/chords?nameLike=F

can be replaced to:

https://api.uberchord.com/v1/embed/chords?nameLike=F

The /embed/* endpoints behave analogously to the original ones. The difference is that the API will respond with HTML content which can be embedded on third party website in contrast to the original JSON response. The HTML response includes everything that is required to render the chord diagrams inside the webbrowser.

Iframe custom dimensions

By default, the generated content tries to fit all of the chords in the available area nicely. This means that you can experiment with different sizes of an iframe and the 'fit-in' algoritm will try to adjust the chord diagram sizes to fit every single chord diagram in the available space, but with maintaining the readability chord sizes at the same time. This of course has some limits. For instance, when the available space is small and chord diagram count is too big, the algorithm will be not able to scale all of the chords to fit in the available space and embedded content may seem like it's cut. That's due to the fact that there are minimal and maximal chord diagram size boundaries (to ensure readability).

Iframe auto-size mode

Because specific fixed dimensions of an iframe have some drawbacks, there is another approach to scale the iframe content. Iframe width can be stretched to the 100% of the available width and the height of it can be adjusted automatically to fit in all of the content.

Technically, this approach uses window.postMessage method to communicate with the parent of the iframe. By this way, an iframe asks the page which hosts it to change it's height.

To enable iframe to send the messages to the host about the desired height #autosize postfix in the iframe's src URL has to be passed, for instance:

https://api.uberchord.com/v1/embed/chords?nameLike=F#autosize

Because height resizing action has to be performed on the host page, additional JavaScript code has to be embedded next to the iframe snippet. The whole embed iframe code snippet can be easily generated through a snippet generator which is described in the next section. Please also refer to the Uberchord Embed SDK section.

Customize Chord Search title and description

When embedding the Chord Search diagrams on third party website, a couple of icons related to the sharing are available near to the diagram(s). One of these icons which is a download emblem redirects the user to the page which looks like the page of shared song. Like a song it has a title, description, chords collection, and enables user to import all of these information into Uberchord iOS App. By default the "song" title is generated automatically basing on the result chord names, and description is empty.

Although, you can override this behavior by customizing the title and description. To perform that, just append two extra query parameters like in the following example:

https://api.uberchord.com/v1/embed/chords?nameLike=F&title=Custom%20title&description=Custom%20Description#autosize

where extra parameters are as follows:

• title - custom title to override the generated one
• description - custom description which is empty by default

Uberchord Embed SDK

The songs and chord progressions can be easily embedded on your custom website through the iframe as it was described in the sections before. Nevertheless, we strongly recommend you to use special Uberchord Embed SDK script which takes care of generation of the iframes and adds additional logic to your page which hosts an iframe. The features include:

• Automatic sizing of the iframe when auto-size mode has been selected
• Proper handling of button which opens the Uberchord iOS App and imports the song (this can't be done properly directly from the iframe itself due to it's context)

Also, please keep in mind that SDK code will be always up to date in case we introduce some new features and bug fixes.

To enable our SDK please embed the following code on your website:

<script>(function(d, s, id) {
  var js, ucjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return;
  js = d.createElement(s); js.id = id;
  js.src = "//static.uberchord.com/uberchord-embed-sdk.js";
  ucjs.parentNode.insertBefore(js, ucjs);
  }(document, 'script', 'uberchord-jssdk'));</script>

After embedding the SDK it's possible to embed two types of content described in the next subsections.

Embedded Song

If you have shared some song already (this feature is available in Uberchord iOS App), you should be able to provide a URL which links to that song, for instance:

https://song.uberchord.com/QLrnvJcIOu

In the above example, the last part of the URL namely QLrnvJcIOu is a Song ID. The exemplary song can be embedded through the following code:

<div class="uberchord-song" data-song-id="QLrnvJcIOu"></div>

The HTML elements with class "uberchord-song" will be recognized by the Uberchord Embed SDK as the elements that has to be decoracted with iframes that contain the embedded songs. As you can see, data-song-id attribute is required to specify the Song to be embedded ID.

Embedded Chord

Like in the Embedded Song case, to embed the Chord use the HTML <div> element with a specific class and attributes for instance:

<div class="uberchord-chord" data-chord-name="F,maj7,"></div>

So as you can see, it's pretty analogous to the Embedded Song, although the class has to be set to the uberchord-chord value and you specify the chord name through data-chord-name attribute. For the guidelines in terms of valid chord name construction please refer to the Get an exact chord section.

Embedded Chords (multiple)

To embed multiple chord diagrams please use the uberchord-chords class on the HTML element like in the following example:

<div class="uberchord-chords" data-search-by="names" data-search-query="F,Bb,F_maj7"></div>

As you can see, there are two additional attributes which defines which chords should be displayed:

The data-search-by attribute can be set to the following values:

Common attributes in Uberchord Embed SDK

Beside the specific attributes for tags that are handled by Uberchord Embed SDK, there are a couple of attributes that are available to both of the embed SDK contents (embedded song and embedded chord/chords) in terms of embedded content appearance configuration:

Embedded code snippet generator

To make life easier, we share a iframe code snippet generator. The generator enables you to generate and preview the snippet code to embed an iframe after filling in a couple of inputs. All you have to do is:

• select one of the content sources:
  • Song - select this option if you have ID or URL of the shared song and you want to generate an embeddable iframe with this song. You can paste in shared song urls like https://song.uberchord.com/QLrnvJcIOu or just song IDs like QLrnvJcIOu.
  • Chord search - select this option if you want to generate iframe which contains specific or multiple chord diagrams. This option requires filling in some more inputs to build a query to API that will enable it to display specific chord diagrams.
  • Manual URL - if you know our API well, you can built the URL by your own through this option.
• select size mode between auto-size and specific
  • in case of specific mode selection, width and height dimensions has to be defined

After that, clicking "Generate code and preview" button should generate a code snippet and it's preview on the right ("Output:") side of the generator page.

Extra options

• Hide "Practice this in Uberchord" icon - this checkbox enables you to hide the iOS App icon in the banner that encourages the user that views the embedded song or chords to import them to the Uberchord iOS App.

Chord search specific options:

• Customize song header - embedded chords by default doesn't have the header like embedded songs do. But when user clicks the import button the song page will appear with the previously embedded chords. By default there is title generated which bases on the chord names or search query. To alter that title and optionally provide also the custom description of the import song, you can use this option and fill in the inputs that will appear after checking that option.
• Embed as song (shorter URL) - you can transform the chords search result to the song. This will result a shorter sharing and import link and in fact the snippet code which is used for songs will be generated as an output instead. You can customize the song title and description by using the Customize song header option also.

Example: https://song.uberchord.com/QLrnvJcIOu song

Content source: Song
Song ID / URL: QLrnvJcIOu
Iframe size: Auto-size

Code snippet:

<script>!function(e,r,d){var t,c=e.getElementsByTagName(r)[0];e.getElementById(d)||(t=e.createElement(r),t.id=d,t.src="//static.uberchord.com/uberchord-embed-sdk.js",c.parentNode.insertBefore(t,c))}(document,"script","uberchord-jssdk");</script>
  <div data-autosize="1" data-diagram-scale="100" class="uberchord-song" data-song-id="QLrnvJcIOu"></div>

Preview:

Example: chords with names like Em7

Content source: Chord search
Filter chords by: Chords with name like
Input value: Em7
Iframe size: Auto-size

Code snippet:

<script>!function(e,r,d){var t,c=e.getElementsByTagName(r)[0];e.getElementById(d)||(t=e.createElement(r),t.id=d,t.src="//static.uberchord.com/uberchord-embed-sdk.js",c.parentNode.insertBefore(t,c))}(document,"script","uberchord-jssdk");</script>
  <div data-autosize="1" data-diagram-scale="100" class="uberchord-chords" data-search-by="nameLike" data-search-query="Em7"></div>

Preview:

Example: chords with name like F - custom iframe dimensions

Content source: Chord search
Filter chords by: Chords with name like
Input value: F
Iframe size: Specific
Width: 440
Height: 425

Code snippet:

<script>!function(e,r,d){var t,c=e.getElementsByTagName(r)[0];e.getElementById(d)||(t=e.createElement(r),t.id=d,t.src="//static.uberchord.com/uberchord-embed-sdk.js",c.parentNode.insertBefore(t,c))}(document,"script","uberchord-jssdk");</script>
  <div data-width="440" data-height="425" data-diagram-scale="100" class="uberchord-chords" data-search-by="nameLike" data-search-query="F"></div>

Preview:

Example: chords with name like Fmaj - custom song title and description

Content source: Chord search
Filter chords by: Chords with name like
Input value: Fmaj
Iframe size: Auto-size
Customize song header: checked
Song title: Fmaj chords
Song description A collection of chords like "Fmaj"

Code snippet:

<script>!function(e,r,d){var t,c=e.getElementsByTagName(r)[0];e.getElementById(d)||(t=e.createElement(r),t.id=d,t.src="//static.uberchord.com/uberchord-embed-sdk.js",c.parentNode.insertBefore(t,c))}(document,"script","uberchord-jssdk");</script>
  <div data-autosize="1" data-diagram-scale="100" data-title="Fmaj chords" data-description="A collection of chords like &quot;Fmaj&quot;" class="uberchord-chords" data-search-by="nameLike" data-search-query="Fmaj"></div>

Preview: