Discogs APIdiscogs.com ↗
Fetch paginated Discogs Marketplace vinyl listings with filters for format, style, and shipping origin. Get full listing details including price, condition, and seller info.
What is the Discogs API?
This API provides two endpoints for querying the Discogs Marketplace: fetch_vinyl_listings returns paginated listing summaries with over a dozen fields per item including pricing, condition grades, and seller data, while get_listing_detail returns a full record for a single listing including release metadata, community stats, and shipping policy. Together they cover searching, filtering, and deep-diving into individual marketplace records.
curl -X GET 'https://api.parse.bot/scraper/55cf9bdd-42b4-44ac-a5a5-64cc5bda5596/fetch_vinyl_listings?page_url=https%3A%2F%2Fwww.discogs.com%2Fsell%2Flist%3Fstyle%3DScore%26format%3DVinyl%26ships_from%3DNetherlands' \ -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 discogs-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.
"""Discogs Marketplace: browse vinyl listings and drill into detail."""
from parse_apis.discogs_marketplace_api import Discogs, ListingNotFound
client = Discogs()
# Browse Score/Soundtrack vinyl listings from Netherlands (default filter)
for listing in client.listingsummaries.list(limit=3):
print(listing.title, listing.price, listing.ships_from)
# Drill into the first listing's full detail
summary = client.listingsummaries.list(limit=1).first()
if summary:
detail = summary.details()
print(detail.condition, detail.seller.username, detail.release.title)
print(detail.original_price.formatted, detail.price.currency)
# Direct fetch by listing_id with typed error handling
try:
full = client.listings.get(listing_id="9999999999")
except ListingNotFound as exc:
print(f"Listing not found: {exc.listing_id}")
print("exercised: listingsummaries.list / summary.details / listings.get / ListingNotFound")
Fetch a paginated list of Discogs Marketplace listings. Supports filtering by format, style/genre, shipping origin, sort order, and page size via a full Discogs Marketplace URL. Returns matching items with pricing, condition, seller info, and community data, plus a next-page URL for pagination. If no page_url is provided, returns the first page of Score-style vinyl listings shipping from the Netherlands.
| Param | Type | Description |
|---|---|---|
| page_url | string | Full Discogs Marketplace URL for a specific results page. Supports query parameters such as style, format, format_desc, ships_from, page, limit (25|50|100|250), and sort. If omitted, fetches the first page of results for Score-style vinyl listings shipping from the Netherlands. |
{
"type": "object",
"fields": {
"items": "array of listing summary objects with release_id, title, listing_id, listing_url, label, catalog_number, media_condition, sleeve_condition, price, price_currency, price_value, converted_price, seller, seller_rating, seller_num_ratings, ships_from, community_have, community_want, community_rating, thumbnail, release_url, seller_comments",
"page_range": "string or null - e.g. '1 – 25 of 8,541'",
"items_count": "integer - number of items on this page",
"request_url": "string - the URL that was fetched",
"total_items": "integer or null - total matching items across all pages",
"next_page_url": "string or null - URL for the next page of results",
"prev_page_url": "string or null - URL for the previous page of results"
}
}About the Discogs API
Browsing and Filtering Marketplace Listings
fetch_vinyl_listings accepts a full Discogs Marketplace URL via the page_url parameter, which means any filter combination the Marketplace supports — format, style, ships_from, sort order, and page size — can be passed directly. The response includes an items array where each object carries release_id, listing_id, listing_url, title, label, catalog_number, media_condition, sleeve_condition, and pricing fields. Pagination is handled through next_page_url and prev_page_url, and the page_range string (e.g. 1 – 25 of 8,541) lets you calculate total pages without extra requests. total_items gives the integer count directly when the Marketplace exposes it.
Listing Detail Endpoint
get_listing_detail takes a numeric listing_id — obtained from the listing_id field in fetch_vinyl_listings results — and returns a complete record. The price object contains a numeric value in USD and the original currency. The seller object includes username, rating, total_ratings, min_order_total, accepted payment methods, and the seller's full shipping_policy text. The release sub-object adds artist, format, year, label, catalog_number, a thumbnail URL, and community have/want counts that reflect collector demand.
Conditions, Comments, and Provenance
Both endpoints surface condition data: fetch_vinyl_listings gives media_condition and sleeve_condition in each summary object, while get_listing_detail returns a condition field plus a free-text comments string where sellers describe pressings, defects, or history. The ships_from field on the detail endpoint identifies the dispatch country, complementing the ships_from filter available on the listing search. The posted field is an ISO datetime indicating when the listing went live.
The Discogs API is a managed, monitored endpoint for discogs.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when discogs.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 discogs.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?+
- Track price trends for a specific pressing by collecting
price.valueacross paginated results filtered byrelease_id. - Build a deal-finder that filters listings by
ships_fromto surface items shipping from a target region at low cost. - Monitor community demand by comparing
community_wantvscommunity_havefromget_listing_detailrelease objects. - Aggregate seller reputation data using
seller.ratingandseller.total_ratingsacross multiple listings. - Alert on new listings for a given style or label by polling
fetch_vinyl_listingsand comparinglisting_idsets. - Compile a catalog of available pressings for a specific label using
labelandcatalog_numberfields from listing summaries. - Audit seller shipping policies by extracting
seller.shipping_policyandseller.min_order_totalfrom detail responses.
| 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 Discogs have an official developer API?+
What does `fetch_vinyl_listings` return beyond the item list?+
items array, the response includes page_range (a human-readable range string like '1 – 25 of 8,541'), total_items as an integer, items_count for the current page, request_url, and both next_page_url and prev_page_url for cursor-style pagination.Does the API return seller shipping costs or just shipping policy text?+
get_listing_detail endpoint returns seller.shipping_policy as a free-text string and seller.min_order_total, but does not return a computed shipping cost to a specific destination. Calculated shipping rates are not currently exposed. You can fork the API on Parse and revise it to add an endpoint targeting destination-specific shipping cost data if the source exposes it for a given listing.Can I filter listings by specific release ID or artist name through `fetch_vinyl_listings`?+
page_url parameter accepts any valid Discogs Marketplace URL, so filters supported by the Marketplace search (format, style, ships_from, sort) can be included. Direct filtering by release_id or artist name in the endpoint parameter is not currently an option beyond what the Marketplace URL query string allows. You can fork the API on Parse and revise it to add a dedicated release-level search endpoint.Is sleeve condition always present in listing summaries?+
items array from fetch_vinyl_listings, but sellers occasionally list records without a sleeve or omit that grade, so the value may be null or absent for some records. Media condition is more consistently populated.