Albumoftheyear APIalbumoftheyear.org ↗
Access album search, critic and user scores, genres, labels, release dates, and ranked album lists from albumoftheyear.org via 4 structured endpoints.
What is the Albumoftheyear API?
The Album of the Year API exposes 4 endpoints that cover album search, full metadata retrieval, ranked best-album lists, and new releases from albumoftheyear.org. The get_album_details endpoint returns critic scores, user scores, genres, labels, release dates, and production credits for any album identified by its path. The get_best_albums endpoint lets you pull ranked lists filtered by year or sorted by critic score, user score, or review count.
curl -X GET 'https://api.parse.bot/scraper/d9c42eb6-5bec-496f-a97d-2e8b9cc8521d/search_albums?page=1&query=Radiohead' \ -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 albumoftheyear-org-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: Album of The Year SDK — search, rank, discover, drill down."""
from parse_apis.Album_of_The_Year_API import AlbumOfTheYear, ListType, AlbumNotFound
client = AlbumOfTheYear()
# Search for albums by artist name, capped at 5 results.
for album in client.album_summaries.search(query="Radiohead", limit=5):
print(album.artist, album.album_title, album.year)
# Drill into the first search result for full metadata.
hit = client.album_summaries.search(query="Kendrick Lamar", limit=1).first()
if hit:
detail = hit.details()
print(detail.artist, detail.album_title, detail.release_date)
print("Genres:", detail.genres)
print("Labels:", detail.labels)
# Browse all-time highest-rated albums using the ListType enum.
for ranked in client.ranked_albums.list(list_type=ListType.HIGHEST_RATED, year="all", limit=3):
print(f"#{ranked.rank} {ranked.artist} - {ranked.album_title} (critic: {ranked.critic_score})")
# Check latest releases with scores and review counts.
newest = client.releases.list(limit=1).first()
if newest:
print(newest.artist, newest.album_title, newest.info)
print(f" Critic: {newest.critic_score} ({newest.critic_reviews} reviews)")
print(f" User: {newest.user_score} ({newest.user_reviews} reviews)")
# Typed error handling when an album path is invalid.
try:
bad = client.albumsummary(path="/album/0-nonexistent.php").details()
except AlbumNotFound as exc:
print(f"Album not found: {exc.album_path}")
print("Exercised: album_summaries.search / details / ranked_albums.list / releases.list / AlbumNotFound")
Full-text search over albums. query matches artist names and album titles. Returns paginated results ordered by relevance. Each result carries a path suitable for get_album_details.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| queryrequired | string | Search query for album or artist name. |
{
"type": "object",
"fields": {
"page": "current page number",
"query": "the search query string echoed back",
"results": "array of album summary objects with artist, album_title, year, type, path, and full_url"
},
"sample": {
"data": {
"page": 1,
"query": "Kendrick Lamar",
"results": [
{
"path": "/album/29250-kendrick-lamar-to-pimp-a-butterfly.php",
"type": "LP",
"year": "2015",
"artist": "Kendrick Lamar",
"full_url": "https://www.albumoftheyear.org/album/29250-kendrick-lamar-to-pimp-a-butterfly.php",
"album_title": "To Pimp a Butterfly"
}
]
},
"status": "success"
}
}About the Albumoftheyear API
What the API Returns
The API covers four main operations against the Album of the Year catalog. search_albums accepts a query string and returns paginated results with artist name, album title, release year, album type, and a path value used by other endpoints. get_album_details takes that path and returns the full record: critic_score, user_score, genres (array), labels (array), release_date, and an extra_details object that can include Format, Producer, Writer, and Tags fields depending on what the source lists.
Ranked Lists and New Releases
get_best_albums returns paginated ranked album objects filtered by a year parameter (e.g. '2024' or 'all') and a list_type parameter. Each object in the response includes rank, artist, album_title, critic_score, user_score, release_date, genres, and path. get_new_releases returns recent additions in reverse chronological order, with each entry carrying artist, album title, release info (date and format), and a path for detail lookup.
Pagination and Path Chaining
All four endpoints support a page integer parameter. The path field returned by search_albums, get_best_albums, and get_new_releases is the canonical input to get_album_details, making it straightforward to chain calls: retrieve a list, then fetch full metadata only for the albums that match your criteria. Scores are returned as strings and may be null when not yet available for an album.
The Albumoftheyear API is a managed, monitored endpoint for albumoftheyear.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when albumoftheyear.org 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 albumoftheyear.org 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 music discovery feed that surfaces albums with the highest critic scores for a given year using
get_best_albums. - Populate a database with album genres and record labels by chaining
search_albumswithget_album_details. - Track new release dates and formats automatically with
get_new_releasesand store results for notification workflows. - Compare critic scores versus user scores for any album using the
critic_scoreanduser_scorefields fromget_album_details. - Generate all-time ranked album charts filtered by list type using the
year='all'parameter inget_best_albums. - Enrich a music catalog with producer and writer credits from the
extra_detailsobject inget_album_details. - Power an album recommendation tool by searching artist names and retrieving genre tags for similarity matching.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does albumoftheyear.org have an official developer API?+
What does `get_album_details` return beyond scores?+
get_album_details returns genres (array of strings), labels (array), release_date, and an extra_details object whose keys vary by album — common keys include Format, Producer, Writer, and Tags. Both critic_score and user_score are strings and may be null if scores have not yet been recorded for that album.Can I filter `get_best_albums` by genre?+
year and list_type, and each result includes a genres array you can filter client-side. You can fork this API on Parse and revise it to add a genre filter parameter.Does the API return individual critic reviews or review text?+
get_album_details returns aggregated critic_score and user_score values, not the underlying individual reviews or review text. You can fork this API on Parse and revise it to add an endpoint that retrieves per-critic review entries.How does pagination work across endpoints?+
page integer parameter. The search_albums and get_best_albums responses echo back the current page value. There is no total-page-count field in the response, so you increment the page until the results array is empty or shorter than a full page.