populate_user_collection

The populate_user_collection command imports user collections from the Football Kit Archive (via FKAPI) into FootyCollect. This is useful for testing, data migration, or bulk importing collections.

How it works

The command performs these steps:

Scrape collection

Calls FKAPI to scrape the user’s collection from Football Kit Archive

Wait for completion

Waits for scraping to complete or uses cached data

Fetch paginated data

Retrieves collection entries in batches

Create database objects

Maps API data to Django models (User, BaseItem, Jersey, Club, Brand, Season, etc.)

Download assets

Creates Photo objects and downloads entry images

Basic usage

python manage.py populate_user_collection <userid>

Example:

python manage.py populate_user_collection 12345

Arguments and options

integer

required

User ID from Football Kit Archive to import

string

Username in your FootyCollect system to assign items to. If not provided, creates a new user.Example:

python manage.py populate_user_collection 12345 --target-username myuser

integer

default:"120"

Maximum time to wait for scraping in seconds.Example:

python manage.py populate_user_collection 12345 --wait-timeout 180

integer

default:"20"

Page size for paginated requests.Example:

python manage.py populate_user_collection 12345 --page-size 50

boolean

Preview mode - don’t create any database objects.Example:

python manage.py populate_user_collection 12345 --dry-run

string

Path to JSON file with collection data (for testing without FKAPI).Example:

python manage.py populate_user_collection --json-file test_data.json

Requirements

FKAPI must be running and configured for this command to work. See FKAPI Integration for setup instructions.

Ensure these environment variables are set:

FKA_API_IP - FKAPI server IP/hostname
API_KEY - API key for FKAPI access

Example workflows

Import to existing user

# First, create the user in Django admin or shell
python manage.py createsuperuser

# Then import the collection
python manage.py populate_user_collection 12345 --target-username admin

Test import with dry run

# Preview what would be imported
python manage.py populate_user_collection 12345 --dry-run

# If everything looks good, run for real
python manage.py populate_user_collection 12345

Import from JSON file (testing)

# Export collection data to JSON first (via FKAPI)
curl http://fkapi-server/api/user-collection/12345 > collection.json

# Import from file without FKAPI
python manage.py populate_user_collection --json-file collection.json

What gets created

The command creates and links these models:

User - New user or uses existing --target-username
Club, Brand, Season, Competition - Referenced entities
Kit - Kit metadata from FKAPI
BaseItem & Jersey - Collection items (uses Multi-Table Inheritance)
Color - Primary and secondary colors
Size - Jersey sizes
Photo - Entry images with automatic AVIF optimization

Output example

Starting collection import for user ID: 12345
Scraping collection...
Waiting for scraping to complete... (max 120s)
Scraping complete!
Fetching page 1...
Creating items...
  Created Jersey: Manchester United 1999/2000 Home
  Created Jersey: Arsenal 2003/2004 Home
  ...
Downloading photos...
Import complete!
Total items created: 42
Total photos downloaded: 58

Troubleshooting

Scraping timeout

If scraping times out, increase --wait-timeout:

python manage.py populate_user_collection 12345 --wait-timeout 300

FKAPI connection error

Verify FKAPI is running and environment variables are set:

echo $FKA_API_IP
echo $API_KEY
curl http://$FKA_API_IP/health

Duplicate items

The command checks for existing items to avoid duplicates. If you get duplicate errors, ensure your database constraints are properly set up.

Photo download failures

Photo downloads are logged. Check logs for failed downloads:

grep "Error downloading" /var/log/footycollect/django.log

FKAPI Integration

Learn about FKAPI setup and configuration

Bulk Operations

API documentation for bulk operations

​How it works

​Basic usage

​Arguments and options

​Requirements

​Example workflows

​Import to existing user

​Test import with dry run

​Import from JSON file (testing)

​What gets created

​Output example

​Troubleshooting

​Related

FKAPI Integration

Bulk Operations

How it works

Basic usage

Arguments and options

Requirements

Example workflows

Import to existing user

Test import with dry run

Import from JSON file (testing)

What gets created

Output example

Troubleshooting

Related