🎧 Discogs Marketplace API NodeJS

 !GitHub Repo stars  

A modern TypeScript/Node.js client for scraping and retrieving Discogs Marketplace listings — flexible, type safe, and easy to use. 💿
> 💪 No Discogs API token required — this client scrapes public Marketplace data.

🚀 Installation

``sh
npm install discogs-marketplace-api-nodejs

Because we use Playwright to scrape the data, you may also need to run:

npx playwright install --with-deps chromium

`

⚡ Quick Start

`ts
import { DiscogsMarketplace } from 'discogs-marketplace-api-nodejs'

const result = await DiscogsMarketplace.search({
api: 'v2',
artistIds: [244819],
genres: ['Rock'],
sort: 'price,asc',
limit: 50,
page: 1,
})

console.log(result.items)
`

📚 Usage Examples

This library offers two API modes to access Discogs Marketplace data. The required api parameter determines which endpoint to use:

- api: 'v2' (Modern JSON API) - Recommended for most use cases, offers advanced filtering
- api: 'legacy' (HTML scraping) - Required for certain search types and general queries

Each API has different capabilities and available parameters. See the API Reference section for complete details.

$3

`ts
// https://www.discogs.com/sell/list?sort=listed,desc&limit=250&artist_id=244819&page=2&genre=Rock
const result = await DiscogsMarketplace.search({
api: 'legacy',
artistId: 244819,
genre: 'Rock',
sort: 'listed,desc',
limit: 250,
page: 2,
})
// OR
const result = await DiscogsMarketplace.search({
api: 'v2',
artistIds: [244819],
genres: ['Rock'],
sort: 'listed,desc',
limit: 250,
page: 2,
})
`

$3

`ts
// https://www.discogs.com/shop/mywants
const result = await DiscogsMarketplace.search({
api: 'v2',
limit: 50,
sort: 'price,asc',
wantlist: 'Kirian_',
})
`

$3

`ts
// https://www.discogs.com/sell/list?release_id=767931&sort=seller,asc&limit=25
// https://www.discogs.com/sell/release/767931?sort=seller,asc&limit=25
const result = await DiscogsMarketplace.search({
api: 'legacy',
releaseId: 767931,
sort: 'seller,asc',
})
// OR
const result = await DiscogsMarketplace.search({
api: 'v2',
releaseIds: [767931],
sort: 'seller,asc',
})
`

$3

`ts
// https://www.discogs.com/sell/list?sort=listed,desc&limit=100&q=in+flames&page=1
const result = await DiscogsMarketplace.search({
api: 'legacy',
query: 'in flames',
sort: 'listed,desc',
limit: 100,
})
`

$3

`ts
// https://www.discogs.com/sell/list?sort=listed,desc&seller=Kirian_
// https://www.discogs.com/seller/Kirian_/profile?sort=listed,desc
const result = await DiscogsMarketplace.search({
api: 'legacy',
sort: 'listed,desc',
seller: 'Kirian_',
})
// OR
const result = await DiscogsMarketplace.search({
api: 'v2',
sort: 'listed,desc',
sellerIds: [6562907],
})
`

$3

`ts
// https://www.discogs.com/seller/Kirian_/mywants?sort=listed,desc&user=Kirian_
const result = await DiscogsMarketplace.search({
api: 'legacy',
sort: 'listed,desc',
seller: 'Kirian_',
user: 'Kirian_',
})
// OR
const result = await DiscogsMarketplace.search({
api: 'v2',
sort: 'listed,desc',
wantlist: 'Kirian_',
sellerIds: [6562907],
})
`

$3

`ts
// https://www.discogs.com/sell/list?master_id=28291&q=red
const result = await DiscogsMarketplace.search({
api: 'legacy',
sort: 'listed,desc',
masterId: 2167270,
query: 'red',
})
`

🧩 API Reference

This library provides two different ways to search the Discogs Marketplace:

- Modern API (api: 'v2') → JSON API, used by the Discogs "My Wants" page.
- Legacy API (api: 'legacy') → HTML scraping, required for some cases.

Both share common search filters and extend them with API-specific options via the SearchParams interface.

$3

| Field | Type | Description | Example | Default |
|-------------------------|---------------------|------------------------------------|-------------------------|---------|
| api | 'v2' | Selects the modern API. | 'v2' | – |
| currencies | Currency[] | Filter by multiple currencies. | ['USD', 'EUR'] | – |
| conditions | Condition[] | List of media/sleeve conditions. | ['Mint (M)'] | – |
| genres | Genre[] | Filter by multiple genres. | ['Rock', 'Jazz'] | – |
| from | From[] | Filter by seller’s countries. | ['FR', 'DE'] | – |
| sort | Sort | Sort and sort order. | 'listed,desc' | 'listed,desc' |
| limit | number | Number of results per page. | 100 | 25 |
| artistIds | number[] | Filter by artist IDs. | [123, 456] | – |
| sellerIds | number[] | Filter by seller IDs. | [789, 1011] | – |
| priceRange.min/max | number | Filter by price range. | { min: 10, max: 100 } | – |
| sellerRatingMin | number (0–100) | Minimum seller rating. | 90 | 0 |
| hideGenericSleeves | boolean | Hide generic sleeves. | – | false |
| hideSleevelessMedia | boolean | Hide sleeveless media. | – | false |
| showUnavailable | boolean | Show unavailable items. | – | true |
| sellerRatingCountMin | number | Minimum number of seller ratings. | 50 | 0 |
| wantlist* | string | Search by wantlist username. | "username" | – |
| releaseIds* | number[] | Search by release IDs. | [12345, 67890] | – |

\* Only one of wantlist or releaseIds can be used.

$3

| Field | Type | Description | Example | Default |
|--------------|-----------------|------------------------------------|--------------------------------|---------|
| api | 'legacy' | Selects the legacy API. | 'legacy' | – |
| query | string | Search string. | "something" | – |
| currency | Currency | Currency code for price filtering. | 'USD' | – |
| condition | Condition | Media/sleeve conditions. | 'Mint (M)' | – |
| genre | Genre | Filter by genre. | 'Rock' | – |
| styles | Style[] | Filter by style. | ['Death Metal', 'Heavy Metal'] | – |
| from | From | Filter by seller’s country. | 'FR' | – |
| sort | Sort | Sort order for results. | 'listed,desc' | 'listed,desc' |
| limit | 25 \| 50 \| 100 \| 250 | Number of results per page. | 100 | 25 |
| seller | string | Filter by seller username. | "seller_name" | – |
| user | string | Filter by user. | "my_username" | – |
| lang | Lang | Discogs interface language. | 'en' | 'en' |
| masterId* | number | Search by master release ID. | 12345 | – |
| labelId* | number | Search by label ID. | 67890 | – |
| releaseId* | number | Search by release ID. | 11111 | – |
| artistId* | number | Search by artist ID. | 22222 | – |

\* Only one of masterId, labelId, releaseId, or artistId can be used.

$3

| Field | Type | Description | Example | Default |
|-----------------------|------------------------------|------------------------------------------------|----------------------------------------|---------|
| formats | Format[] | List of formats. | ['Vinyl', 'CD'] | – |
| formatDescriptions | FormatDescription[] | List of format descriptions. | ['Limited Edition', 'Numbered'] | – |
| years.min / max | number | Year range. | { min: 1980, max: 1990 } | – |
| isMakeAnOfferOnly | boolean | Only return listings that accept offers. | – | false |
| page | number | Page number (must be < 401 to avoid 404). | 2 | 1 |

On success, a SearchResult interface is returned:

`ts
interface SearchResult {
items: Array<{
id: number
title: string
artists: Array<{
id: number | null
name: string
url: string | null
}>
release: {
id: number
name: string
url: string
}
formats: Array
labels: Array<{
id: number
name: string
url: string
}>
url: string
listedAt: Date | null
catnos: Array
imageUrl: string | null
description: string | null
isAcceptingOffer: boolean
isAvailable: boolean
condition: {
media: {
full: string
short: string
}
sleeve: {
full: string | null
short: string | null
}
}
seller: {
name: string
url: string
score: string | null
notes: number | null
}
price: {
/* @example '12.34 USD' /
base: ${number} ${CurrencyValues}
/* @example '5.67 USD' /
shipping: ${number} ${CurrencyValues} | null
}
country: {
name: string
/* @example 'US' /
code: CountryValues
}
community: {
have: number
want: number
}
}>
page: {
current: number
total: number
}
result: {
total: number
perPage: number
}
urlGenerated: string
}
`

🛠️ Development & Contribution

- Clone the repo and use the included devcontainer/VSCode setup.
- Run: npm install
- Add your contribution.
- Use npm test` to run unit tests.
- Open a pull request with your new additions! 🎉

👉 Known Issues

- Requests hitting page >400 will result in a 404 on the legacy API.
- Some search parameters might not be compatible with every type of queries.
- For other edge cases, feel free to open an issue on GitHub.

📃 License

Licensed under MIT.