Developer data
The chord library,
as open JSON.
Three read-only JSON endpoints power the tools on this site and are free for anyone else to use: every chord shape, every scale chart and the full fretboard explorer table. No key, no account, no tracking — fetch, cache and cite.
- 3
- JSON endpoints
- 172
- chord shapes
- 60
- scale charts
- 144
- explorer entries
Endpoints
All three are static files on this domain, served with Access-Control-Allow-Origin: * and a one-day cache lifetime. The JSON is generated from the same source as the HTML pages, so the two never disagree.
Chord database
172 entriesEvery chord shape with its fingering, notes, difficulty, canonical page URL and name in each published language.
/data/chords.json→Scale database
60 entriesFive scale types in all twelve keys with spelled notes, degrees, intervals, step formulas and the diatonic chords of the key.
/data/scales.json→Fretboard explorer state
144 entriesThe interactive explorer fetches this once instead of carrying 144 chord entries inside every page: every root and quality, including all voicings up the neck.
/data/fretboard-explorer.json→
Fields
Arrays of six values follow the strings from low E to high E. Fret 0 is an open string and "x" means the string is not played.
chords[ ]
symbol- Chord symbol as the site spells it, such as C, F#m7 or Bbadd9.
name- Full, human-readable chord name (C major).
root- Root note the entry is built on.
quality- Quality id such as major, minor, 7 or sus4.
slug- URL slug of the page for this entry.
hasOwnPage- True when the chord has a dedicated page; otherwise the shape is documented inside its family page.
href- Site-relative path of the chord page; url is the absolute address.
names- The chord name keyed by site language (en, zh, zh-Hant).
notes- The pitches the shape sounds, spelled by letter rather than by a global sharp or flat table.
frets- Fret to press on each string, low E to high E.
fingers- Finger per string: 1 index, 2 middle, 3 ring, 4 pinky, 0 none.
barres- Fret numbers barred by one finger; an empty array means no barre.
baseFret- First fret in the diagram window; 1 means the window starts at the nut.
difficulty- 1 to 5: 1 is an open beginner shape, 5 a stretch few players use.
scales[ ]
root- Root note the entry is built on.
scale- Scale type id such as major, natural-minor or blues.
slug- URL slug of the page for this entry.
url- Absolute URL of the HTML page for that entry.
notes- The scale spelled in order from its root, with the correct letter for each degree (C natural minor is C D Eb F G Ab Bb).
notePitchClasses- The same notes as pitch classes 0–11, for code that should not parse note names.
degrees- Scale degree of each note: 1, 2, ♭3, 4, 5, ♭6, ♭7.
intervals- Semitone offsets from the root, the same numbers the scale is generated from.
steps- Step formula, where W is a whole step, H a half step and m3 a minor third.
diagram- Absolute URL of the fretboard diagram image for that scale.
pitchClassNames- Pitch class to note name map, for labelling a fretboard without parsing spelling.
diatonicChords- The seven chords built on the scale, as numeral, symbol and notes.
chords["C|major"]
version- Response format version; currently 1. It changes only if the response shape has to.
chords["…"]- Object key formed as root plus quality id, for example C|major or F#|minor. Each value uses the chord fields above plus voicings.
voicings- Every position the site knows for that root and quality, each with its own frets, fingers and barres.
Quick start
Read it from the command line or fetch it in the browser. Nothing needs a key, a header or an account.
curl -s https://openguitarchords.com/data/chords.json | jq '.chords[] | select(.symbol == "C")'const res = await fetch('https://openguitarchords.com/data/chords.json');
const { chords } = await res.json();
const cMajor = chords.find((c) => c.symbol === 'C');One chord entry
{
"symbol": "C",
"name": "C major",
"root": "C",
"quality": "major",
"slug": "c",
"hasOwnPage": true,
"href": "/chords/c",
"url": "https://openguitarchords.com/chords/c",
"names": {
"en": "C major",
"zh": "C 大三和弦",
"zh-Hant": "C 大三和弦"
},
"notes": [
"C",
"E",
"G"
],
"frets": [
"x",
3,
2,
0,
1,
0
],
"fingers": [
0,
3,
2,
0,
1,
0
],
"barres": [],
"baseFret": 1,
"difficulty": 1
}One scale entry
{
"root": "C",
"scale": "major",
"scaleLabel": "Major (Ionian)",
"slug": "c-major",
"url": "https://openguitarchords.com/scales/c-major",
"notes": [
"C",
"D",
"E",
"F",
"G",
"A",
"B"
],
"notePitchClasses": [
0,
2,
4,
5,
7,
9,
11
],
"degrees": [
"1",
"2",
"3",
"4",
"5",
"6",
"7"
],
"intervals": [
0,
2,
4,
5,
7,
9,
11
],
"steps": "W-W-H-W-W-W-H"
}One explorer entry
{
"slug": "c",
"symbol": "C",
"baseFret": 1,
"frets": [
"x",
3,
2,
0,
1,
0
],
"fingers": [
0,
3,
2,
0,
1,
0
],
"barres": [],
"difficulty": 1,
"notes": [
"C",
"E",
"G"
],
"voicings": [
{
"baseFret": 1,
"frets": [
"x",
3,
2,
0,
1,
0
],
"fingers": [
0,
3,
2,
0,
1,
0
],
"barres": []
},
{
"baseFret": 3,
"frets": [
"x",
3,
5,
5,
5,
3
],
"fingers": [
0,
1,
3,
3,
3,
1
],
"barres": [
{
"fret": 3,
"from": 1,
"to": 5
},
{
"fret": 5,
"from": 2,
"to": 4
}
]
}
]
}Entries trimmed to the fields most consumers use; the real response contains every field listed above.
Use and attribution
The data is free to use, including commercially. No license requires attribution, but a link back to Open Guitar Chords is appreciated and helps the project keep going.
The files contain chord and scale facts only: no lyrics, no tablature and no audio. The diagrams, page text and recordings that present this data are the site's own work.
Stability and changes
Field names are stable and changes are additive: new fields may appear, existing fields keep their meaning. The explorer endpoint carries a version number and will only change if the shape of the response has to.
The files are edge-cached for a day, so a correction can take up to 24 hours to reach you. The HTML pages and the JSON come from the same generated data.
Found a wrong fingering or need a field that is missing? The contact page lists every channel that reaches us. contact page