Uberchord API guide

Table of Contents

What is Uberchord API?

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

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:

Attribute name Description
chordName Every guitar chord has a name which is a string with up to 4 components separated by , character.
See the "chordName pattern" section below for the details.
strings Fret numbers to be fingered down for each of the string starting from the bottom.
See the "strings pattern" section below for the details.
fingering Finger numbers for each string starting from the bottom.
See the "fingering pattern" section below for the details.

chordName pattern

The chord name consists of the following pattern:

root,quality,tension,bass

Example: E7#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: Fmaj7#11613(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:

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

Example: C7

C7 chord

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:

F tone

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 Amaj79(add11) in the examples list below.

Example: C

C tone

fingering value for the above chord is:

X 1 2 X 3 X

Example: Amaj79(add11)

Abmaj79(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:

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 Fmaj7 chord

To get exactly the Fmaj7 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:

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 Fmaj79 or Fmmaj7 are listed in the results even that the first Fmaj7 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:

Example: getting Fmaj7 and Em75 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:

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 Fmaj7 and E6 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:

Attribute name Description
id An unique identifier of the specific Song. The identifier is generated automatically by API and it is read only.
url An unique URL where the song can be viewed. It is read only.
title Title of the song that will appear on the top of the shared song page.
description Description of the song that will appear under the song title.
thumbnailData Every song can have specific picture associated with it. The picture should be in JPEG format and sent as raw JPEG file content encoded in base64. If there's no picture to be assigned with a song, empty string can be passed and shared song page will output a default thumbnail with Uberchord logo.
voicings This is the main component of each song. It is an array that contains guitar chords. For further details about chords, please refer to the "Guitar chords" section.

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:

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:

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:

Attribute Description Exemplary value
data-search-by There are three ways to find multiple chords to be displayed: names, nameLike and voicing. Each of them is described in the next table. names
data-search-query When search mode by data-search-by is specified, there has to be defined a value which will be used for search in the used search mode. F,Bb,F_maj7

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

Value Description data-search-query example value
names In this search mode chords are searched by their exact names. Please refer to the Search multiple chords by name section and it examples for the details about the query value construction for that search mode. F,Bb,F_maj7
nameLike If you want to search chords that names are similar to the one provided use this mode. Please refer to the Searching multiple chords by exact names section and it examples for the details about the query value construction for that search mode. Fmaj7
voicing To search chords by specific voicing pattern(s) use this search mode. Please refer to the Searching multiple chords by voicing pattern section and it examples for the details about the query value construction for that search mode. 1-X-2-2-1-0,0-X-2-4-2-4

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:

Attribute Description Exemplary value
data-autosize 0 - Iframe custom dimensions mode. 1 - Iframe auto-size mode. 1
data-diagram-scale Scale of the diagrams size. Provide the value in percents relative to the original size (100 is an original size). Works only with Iframe auto-size mode. 90
data-width Width in pixels of the iframe when using Iframe custom dimensions mode. 500
data-height Height in pixels of the iframe when using Iframe custom dimensions mode. 500
data-no-icon The icon on the bottom banner that encourages user to open the song in the Uberchord iOS App, can be hided through that attribute by setting it to 1. 1

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:

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

Chord search specific options:

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: