🎧 Discogs Marketplace API NodeJS

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

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

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.

1. Get 250 latest listings by a specific artist in the Rock genre, page 2

// 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,
})

2. Get listings of a user's wantlist, sorted by price, limit 50

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

3. Get listings on a release, sorted by seller name

// 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',
})

4. Get listings by a general search query (e.g., "in flames"), sorted by newest listings, limit 100

// 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,
})

5. Get newest listings on a seller inventory

// 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],
})

6. Get newest listings of a user's wantlist, on a seller inventory

// 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],
})

7. Get listings by a general search query (e.g., "red"), sorted by newest listings, on a master release

// 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.

Modern API (api: "v2"), recommended for most use cases

| 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.

Legacy API (api: "legacy")

| 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.

Common Parameters (all searches)

| 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:

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<string>
        labels: Array<{
            id: number
            name: string
            url: string
        }>
        url: string
        listedAt: Date | null
        catnos: Array<string>
        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.