Discogs Collection Importer

A Python CLI tool to import your Discogs record collection from a CSV export file using the Discogs API.

Features

• Import CSV collection data to Discogs via API
• Intelligent rate limiting based on API response headers
• Automatic folder creation for missing collection folders
• Skip duplicate folder creation by checking existing folders first
• Comprehensive error handling and progress tracking

Prerequisites

• Python 3.6 or higher
• A Discogs account
• A Discogs API token (Personal Access Token)
• Your collection exported as CSV from Discogs

Installation

1. Clone or download this repository
2. Install required dependencies:

   pip install requests

Getting Your Discogs API Token

1. Go to Discogs Developer Settings
2. Click "Generate new token"
3. Give it a name (e.g., "Collection Importer")
4. Copy the generated token

CSV File Format

The script expects a CSV file with the following columns:

• CollectionFolder: The folder name where the release should be placed
• release_id: The Discogs release ID

Example CSV structure:

Catalog#,Artist,Title,Label,Format,Rating,Released,release_id,CollectionFolder,Date Added
T-583,Stephanie Mills,What Cha Gonna Do With My Lovin',20th Century Fox Records,"LP, Album, Ind",,1979,527552,LPs,2024-02-27 18:25:27

Usage

Basic Usage

python import_discogs_collection.py -u YOUR_USERNAME -t YOUR_API_TOKEN

With Custom CSV File

python import_discogs_collection.py -u YOUR_USERNAME -t YOUR_API_TOKEN -c path/to/your/collection.csv

Command Line Options

Option	Short	Required	Description
--username	-u	Yes	Your Discogs username
--token	-t	Yes	Your Discogs API token
--csv	-c	No	Path to CSV file (default: discogs-collection.csv)

Help

python import_discogs_collection.py --help

How It Works

The script performs the following steps:

1. Load CSV Data: Reads the CSV file and extracts unique folder names
2. Get Existing Folders: Retrieves your current collection folders from Discogs API
3. Create Missing Folders: Creates only the folders that don't already exist
4. Refresh Folder List: Updates the folder lookup table with newly created folders
5. Import Releases: Adds each release to its designated folder

Rate Limiting

The script includes intelligent rate limiting that:

• Respects Discogs API limits (60 requests/minute for authenticated users)
• Dynamically adjusts wait times based on API response headers
• Shows real-time rate limit status
• Includes safety buffers to prevent hitting limits

Error Handling

The script handles various error conditions:

• Missing CSV file or invalid format
• Invalid API credentials
• Network connectivity issues
• API rate limit exceeded
• Missing release IDs or folder names

Example Output

Step 1: Loading unique folder names from CSV...
Found 5 unique folders: ['Jazz', 'LPs', 'New arrivals', 'Rock', 'Singles']

Step 2: Getting existing folder lookup table...
Found 3 existing folders

Step 3: Creating missing folders via API...
Need to create 2 new folders: ['Jazz', 'New arrivals']
Created folder: Jazz
Created folder: New arrivals

Step 4: Refreshing folder lookup table...
Updated folder lookup with 5 total folders

Step 5: Processing releases and adding to folders...
Processed 10/50 releases (10 successful, 0 errors)
Rate limit: 15/60 used, 45 remaining
...
Import complete: 50 successful, 0 errors

Troubleshooting

Common Issues

403 Forbidden Error

• Verify your API token is correct and hasn't expired
• Ensure your username is correct
• Check that your token has collection write permissions

Rate Limited (429 Error)

• The script handles rate limiting automatically
• If you see persistent rate limit errors, wait a few minutes and try again

CSV Format Errors

• Ensure your CSV has the required columns: CollectionFolder and release_id
• Check that the CSV is properly formatted and not corrupted

Network Errors

• Check your internet connection
• Verify that Discogs API is accessible (not blocked by firewall/proxy)

Getting Help

If you encounter issues:

1. Check the error message for specific details
2. Verify all prerequisites are met
3. Test with a smaller CSV file first
4. Check the Discogs API status page

API Documentation

This tool uses the Discogs API v2.0. For more information:

• Discogs API Documentation
• Collection Endpoints

License

This script is provided as-is for personal use with the Discogs API.