Albumoftheyear APIalbumoftheyear.org ↗
Access album metadata, critic and user scores, genres, labels, and ranked lists from albumoftheyear.org via 5 structured endpoints.
What is the Albumoftheyear API?
The Album of the Year API provides access to structured music data across 5 endpoints, covering album search, full metadata, ranked best-of lists, new releases, and a complete genre index. The get_album_details endpoint returns critic scores, user scores, release dates, labels, genres, and production details for any album. Results from search_albums, get_best_albums, and get_new_releases all include a path field that feeds directly into detail lookups.
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 3 results.
for album in client.album_summaries.search(query="Radiohead", limit=3):
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})")
# List available genres.
for genre in client.genres.list(limit=3):
print(genre.name, genre.numeric_id, genre.url)
# 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 / genres.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
Search and Discovery
The search_albums endpoint accepts a query string matching artist names or album titles and returns paginated results. Each result includes artist, album_title, year, type, and a path field. That path is the key input for get_album_details, which returns the full record: critic_score, user_score, release_date, genres (array), labels (array), and an extra_details object that can carry variable keys like Format, Producer, Writer, and Tags.
Rankings and New Releases
get_best_albums lets you pull ranked album lists filtered by year (a four-digit string like '2024' or the string 'all' for all-time) and sorted by list_type. Each ranked result includes rank, critic_score, user_score, genres, and a path. get_new_releases returns albums in reverse chronological order with critic_reviews and user_reviews counts alongside scores — useful for tracking how much critical coverage a new release has accumulated.
Genre Index
get_genres returns the complete genre list in a single call — no pagination. Each entry includes a name, a numeric_id (matching how genres appear in albumoftheyear.org URLs and filters), and a direct url. This makes it straightforward to map genre names to identifiers when building filters or category-based browsing on top of the API.
Score Coverage
Both critic_score and user_score are returned as strings and can be null when a score hasn't been published or has too few reviews. The extra_details object uses variable keys, so not every album will carry every field — check for key presence before reading Producer, Writer, or Tags.
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 by polling
get_new_releasesand filtering bycritic_scorethreshold - Populate an album database with release metadata using
get_album_detailsfields likelabels,genres, andrelease_date - Generate year-end ranked lists by querying
get_best_albumswith a specificyearparameter - Map a user's genre preferences to numeric IDs via
get_genresfor category-based browsing - Compare critic and user reception gaps by reading
critic_scoreanduser_scorefrom detail or ranking endpoints - Track new release review velocity by monitoring
critic_reviewsanduser_reviewscounts inget_new_releasesover time - Auto-tag albums with production credits by extracting
ProducerandWriterfrom theextra_detailsobject inget_album_details
| 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 albumoftheyear.org have an official developer API?+
What does `get_album_details` return beyond scores?+
genres (array of strings), labels (array of strings), release_date, and an extra_details object with variable keys including Format, Producer, Writer, and Tags. Score fields (critic_score, user_score) are strings and may be null when no score is available.Can I filter `get_best_albums` or `get_new_releases` by genre?+
get_best_albums supports filtering by year and list_type, and get_new_releases supports only page. Genre-based filtering is not a parameter on either endpoint. You can fork this API on Parse and revise it to add genre filter support using the numeric IDs returned by get_genres.Does the API expose individual critic reviews or review text?+
get_album_details returns aggregate critic_score and user_score values, and get_new_releases includes critic_reviews and user_reviews counts. Individual review text, reviewer names, and publication sources are not included. You can fork this API on Parse and revise it to add an endpoint that returns per-review data for a given album.How does pagination work across endpoints?+
search_albums, get_best_albums, and get_new_releases all accept an optional page integer parameter and return the current page number in the response. get_genres does not paginate — it returns the full genre list in one response. There is no total_pages field, so you advance pages until results are empty.