Skip to main content
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:
1

Scrape collection

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

Wait for completion

Waits for scraping to complete or uses cached data
3

Fetch paginated data

Retrieves collection entries in batches
4

Create database objects

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

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

​
userid
integer
required
User ID from Football Kit Archive to import
​
--target-username
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
​
--wait-timeout
integer
default:"120"
Maximum time to wait for scraping in seconds.Example:
python manage.py populate_user_collection 12345 --wait-timeout 180
​
--page-size
integer
default:"20"
Page size for paginated requests.Example:
python manage.py populate_user_collection 12345 --page-size 50
​
--dry-run
boolean
Preview mode - don’t create any database objects.Example:
python manage.py populate_user_collection 12345 --dry-run
​
--json-file
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

If scraping times out, increase --wait-timeout:
python manage.py populate_user_collection 12345 --wait-timeout 300
Verify FKAPI is running and environment variables are set:
echo $FKA_API_IP
echo $API_KEY
curl http://$FKA_API_IP/health
The command checks for existing items to avoid duplicates. If you get duplicate errors, ensure your database constraints are properly set up.
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