Ultimate Guitar APIultimate-guitar.com ↗
Search Ultimate Guitar tabs by song or artist and fetch chord charts with inline chord names. 2 endpoints covering tab metadata, ratings, tuning, and capo.
What is the Ultimate Guitar API?
The Ultimate Guitar API gives developers programmatic access to the world's largest tab repository through 2 endpoints. Use search_songs to query tabs by title, artist, or both and receive paginated results with rating, version, and type metadata. Use get_chord_chart to retrieve a specific tab's full chord chart, returned as lyrics with inline chord names in square brackets alongside tuning, capo, tonality, and vote count.
curl -X GET 'https://api.parse.bot/scraper/12ac6f45-949a-4b24-ba4b-c6da49dbd41a/search_songs?query=wonderwall+oasis&tab_type=chords' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace ultimate-guitar-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: search Ultimate Guitar for chord charts and fetch full tab details."""
from parse_apis.ultimate_guitar_com_api import UltimateGuitar, TabType, TabNotFound
client = UltimateGuitar()
# Search for chord tabs matching a query, capped at 5 results.
for tab in client.tabs.search(query="wonderwall oasis", tab_type=TabType.CHORDS, limit=5):
print(tab.song_name, "-", tab.artist_name, f"(v{tab.version}, rating {tab.rating})")
# Drill into the first result to get the full chord chart.
hit = client.tabs.search(query="hey joe hendrix", limit=1).first()
if hit is not None:
# Fetch complete tab details using the URL from the search result.
try:
detail = client.tabs.get(tab_url=hit.url)
except TabNotFound:
print("Tab no longer available:", hit.url)
else:
print(detail.song_name, "by", detail.artist_name)
print("Chords used:", ", ".join(detail.chords_used or []))
print("Difficulty:", detail.difficulty)
if detail.capo is not None:
print("Capo fret:", detail.capo)
# Show the first few lines of the chord chart.
for line in (detail.chord_chart or "").split("\n")[:6]:
print(line)
print("exercised: tabs.search / tabs.get")
Searches Ultimate Guitar tabs by free text (song title, artist name, or both, e.g. 'wonderwall oasis'). Returns one page of matching user-submitted tabs (Chords, Tab, Ukulele Chords, Bass Tab, etc.), ordered by the site's relevance. Promotional/official 'Pro' entries without a public page are omitted. The page size is fixed by the site (up to about 50 rows); use `page` to walk pages while `has_more` is true; `page` defaults to 1. `total_results` is the site's reported match count across all pages. Each row's `url` is the tab page address to pass to get_chord_chart. `tonality` and `difficulty` are null when the site does not list them. A query with no matches returns an empty `results` array with `total_results` 0.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page number. |
| queryrequired | string | Free-text search: song title, artist name, or both, in any order. |
| tab_type | string | Restrict results to one tab type. Omitted = all types. |
{
"type": "object",
"fields": {
"page": "current page number (integer)",
"query": "the search text as echoed by the site",
"results": "array of tab summaries: tab_id (string), song_name, artist_name, type (e.g. Chords, Tab, Ukulele Chords), version (integer), rating (0-5 float), votes (integer), tonality (key or null), difficulty (or null), url (tab page, input for get_chord_chart)",
"has_more": "true when a later page exists",
"tab_type": "the tab_type filter applied, or null when none",
"total_pages": "number of result pages the site reports for this query (integer)",
"total_results": "site-reported total number of matching tabs across all pages (integer)"
},
"sample": {
"data": {
"page": 1,
"query": "wonderwall oasis",
"results": [
{
"url": "https://tabs.ultimate-guitar.com/tab/oasis/wonderwall-chords-6125",
"type": "Chords",
"votes": 2497,
"rating": 4.59615,
"tab_id": "6125",
"version": 1,
"tonality": "F#m",
"song_name": "Wonderwall",
"difficulty": "intermediate",
"artist_name": "Oasis"
},
{
"url": "https://tabs.ultimate-guitar.com/tab/oasis/wonderwall-chords-1064463",
"type": "Chords",
"votes": 403,
"rating": 4.86554,
"tab_id": "1064463",
"version": 1,
"tonality": null,
"song_name": "Wonderwall",
"difficulty": null,
"artist_name": "Oasis"
}
],
"has_more": false,
"tab_type": "chords",
"total_pages": 1,
"total_results": 24
},
"status": "success"
}
}About the Ultimate Guitar API
Searching for Tabs
The search_songs endpoint accepts a free-text query parameter (song title, artist name, or a combination like 'wonderwall oasis') and returns an array of tab summaries. Each result includes tab_id, song_name, artist_name, type (Chords, Tab, Ukulele Chords, Bass Tab, etc.), version, rating, and a url suitable for passing directly to get_chord_chart. You can narrow results using the optional tab_type filter and paginate with the page parameter. The response also surfaces total_results and total_pages so you can build pagination controls or estimate corpus size for a given query.
Fetching a Chord Chart
Passing a tab URL from search_songs results to get_chord_chart returns the full chart for that tab. The chord_chart field renders the chart as lyric lines with chord names inserted inline in square brackets at the position where they fall — for example, 'Today is g[A]onna be the day'. The response also includes raw_chart containing the original site markup with [ch]..[/ch] chord tags and [tab]..[/tab] blocks, which is useful if you need to reformat or parse the structure yourself. Additional fields cover tuning (e.g. 'E A D G B E'), capo fret, tonality (song key), rating, votes, and version.
Data Coverage and Limitations
Results come from user-submitted tabs and are ordered by the site's own relevance ranking. Paid 'Pro' tab entries that lack a publicly visible chart are excluded from search_songs results. The rating field is a 0–5 float based on user votes, and version distinguishes multiple community submissions for the same song. Tabs without tuning or capo data return null for those fields.
The Ultimate Guitar API is a managed, monitored endpoint for ultimate-guitar.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ultimate-guitar.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ultimate-guitar.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a chord lookup tool that queries tabs by song and artist name and displays inline chord positions
- Generate a transposition aid using the
tuningandcapofields returned byget_chord_chart - Aggregate tab quality data by collecting
ratingandvotesacross versions of the same song - Filter search results to a specific instrument using the
tab_typeparameter (e.g. Ukulele Chords) - Create a songbook app that stores
raw_chartmarkup and reformats it per user preference - Identify the most popular community tab for a song by comparing
versionnumbers andratingvalues acrosssearch_songsresults - Build a key/tonality browser that groups songs by the
tonalityfield returned from fetched charts
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Ultimate Guitar have an official developer API?+
What does `search_songs` return, and how do I filter by tab type?+
results array includes tab_id, song_name, artist_name, type, version, rating, and url. Pass the optional tab_type parameter (e.g. 'Chords' or 'Bass Tab') to restrict results to one format. Omitting it returns all tab types. The response includes total_results and total_pages for pagination, and has_more as a boolean shortcut.What is the difference between `chord_chart` and `raw_chart` in `get_chord_chart`?+
chord_chart is a processed, human-readable format where chord names are inserted inline into lyric lines at the correct character positions (e.g. '[G]Today is gonna be the day'). raw_chart preserves the original site markup including [ch]..[/ch] and [tab]..[/tab] tags, which is useful if you need to parse chord positions yourself or apply custom rendering logic.Are artist pages, discographies, or user profiles available through the API?+
search_songs and individual tab chord charts via get_chord_chart. Artist pages, full discography listings, and user profile data are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting those resources.Does the API return guitar pro or PDF files attached to tabs?+
chord_chart, raw_chart, tuning, capo, tonality, rating, and votes. If you need to surface downloadable file availability as a metadata flag, you can fork the API on Parse and revise it to add that field.