User Collections

Overview

The User Collections endpoints allow you to scrape and retrieve a user’s kit collection from FootballKitArchive. Collections are cached for 1 week after scraping.

User collections can contain large amounts of data. The API supports pagination to efficiently retrieve collection data.

Scrape User Collection

curl -X POST "https://your-domain.com/api/user-collection/148184/scrape" \
  -H "X-API-Key: your-api-key-here"

Start asynchronous scraping of a user’s collection from FootballKitArchive. If the collection is already cached, returns data immediately.

Path Parameters

integer

required

User ID from FootballKitArchive (found in the user’s profile URL)

Query Parameters

boolean

default:"false"

Force a fresh scrape by invalidating existing cache. Useful for getting updated collection data.

Response Codes

200 OK - Collection found in cache, data returned immediately
202 Accepted - Scraping started, use task_id to check status

Response (200 OK - Cached)

string

Status of the response: “cached”

object

Collection data object

boolean

Whether the scraping was successful

array

Array of kit entries in the collection

integer

Total number of kits in the collection

integer

Number of pages scraped from FootballKitArchive

object

Pagination information

{
  "status": "cached",
  "data": {
    "success": true,
    "entries": [
      {
        "kit_id": 12345,
        "kit_name": "Manchester United 2024-25 Home Kit",
        "kit_slug": "manchester-united-2024-25-home-kit",
        "team_name": "Manchester United",
        "season_year": "2024-25",
        "main_img_url": "https://www.footballkitarchive.com/images/kits/..."
      }
    ],
    "total_entries": 150,
    "pages_scraped": 8
  },
  "pagination": {
    "total_count": 150,
    "note": "Use GET /api/user-collection/148184?page=1&page_size=20 for paginated results"
  }
}

Response (202 Accepted - Processing)

string

Status of the response: “processing”

string

Celery task ID for tracking the scraping job

string

Instructions for checking status

{
  "status": "processing",
  "task_id": "abc123-def456-ghi789",
  "message": "Scraping started. Check status in 60 seconds by calling GET /api/user-collection/148184"
}

Usage Flow

POST /api/user-collection/{userid}/scrape to start scraping
If you receive 202 Accepted, wait approximately 60 seconds (scraping time depends on collection size)
GET /api/user-collection/{userid} to retrieve paginated data

For large collections (500+ kits), scraping may take 2-3 minutes. The API respects rate limits to avoid overloading FootballKitArchive servers.

Get User Collection

curl -X GET "https://your-domain.com/api/user-collection/148184?page=1&page_size=20" \
  -H "X-API-Key: your-api-key-here"

Get a user’s collection from cache with pagination. Collection must be scraped first using the POST endpoint.

Path Parameters

integer

required

User ID from FootballKitArchive

Query Parameters

integer

default:"1"

Page number for pagination (minimum: 1)

integer

default:"20"

Number of items per page (minimum: 1, maximum: 100)

Response Codes

200 OK - Collection found in cache, returns paginated data
404 Not Found - Collection not found, suggest starting scraping first

Response (200 OK)

string

Status of the response: “ready”

object

Collection data object

boolean

Whether the scraping was successful

array

Array of kit entries for the current page

integer

Kit ID

string

Full name of the kit

string

URL-friendly slug for the kit

string

Club/team name

string

Season year

string

URL to the kit image

integer

Total number of kits in the collection

integer

Number of pages scraped from FootballKitArchive

object

User information (if available from scraping)

string

User’s display name

string

URL to user’s profile image

string

Twitter handle

string

Instagram handle

string

User’s profile description

integer

User’s points on FootballKitArchive

object

Pagination information

integer

Current page number

integer

Total number of pages

integer

Total number of kits

integer

Number of items per page

boolean

Whether there is a next page

boolean

Whether there is a previous page

integer

Next page number (null if no next page)

integer

Previous page number (null if no previous page)

string

ISO 8601 timestamp indicating when the cache expires

{
  "status": "ready",
  "data": {
    "success": true,
    "entries": [
      {
        "kit_id": 12345,
        "kit_name": "Manchester United 2024-25 Home Kit",
        "kit_slug": "manchester-united-2024-25-home-kit",
        "team_name": "Manchester United",
        "season_year": "2024-25",
        "main_img_url": "https://www.footballkitarchive.com/images/kits/manchester-united-2024-25-home.jpg"
      },
      {
        "kit_id": 12346,
        "kit_name": "Liverpool 2024-25 Away Kit",
        "kit_slug": "liverpool-2024-25-away-kit",
        "team_name": "Liverpool",
        "season_year": "2024-25",
        "main_img_url": "https://www.footballkitarchive.com/images/kits/liverpool-2024-25-away.jpg"
      }
    ],
    "total_entries": 150,
    "pages_scraped": 8,
    "user": {
      "name": "John Doe",
      "image": "https://www.footballkitarchive.com/images/users/12345.jpg",
      "twitter": "johndoe",
      "instagram": "johndoe",
      "description": "Kit collector since 2010",
      "points": 1250
    }
  },
  "pagination": {
    "current_page": 1,
    "total_pages": 8,
    "total_count": 150,
    "page_size": 20,
    "has_next": true,
    "has_previous": false,
    "next_page": 2,
    "previous_page": null
  },
  "cached_until": "2026-03-10T12:00:00"
}

Response (404 Not Found)

string

Status of the response: “not_found”

string

Error message with instructions

{
  "status": "not_found",
  "message": "Collection not found for userid 148184. Call POST /api/user-collection/148184/scrape first to start scraping."
}

Complete Example Workflow

import requests
import time

BASE_URL = "https://your-domain.com/api"
API_KEY = "your-api-key-here"
headers = {"X-API-Key": API_KEY}

# Step 1: Start scraping
userid = 148184
response = requests.post(
    f"{BASE_URL}/user-collection/{userid}/scrape",
    headers=headers
)
result = response.json()
print(f"Scrape status: {result['status']}")

# Step 2: Wait if processing
if result.get('status') == 'processing':
    print(f"Task ID: {result['task_id']}")
    print("Waiting 60 seconds for scraping to complete...")
    time.sleep(60)

# Step 3: Get paginated collection
response = requests.get(
    f"{BASE_URL}/user-collection/{userid}",
    params={"page": 1, "page_size": 20},
    headers=headers
)
collection = response.json()

print(f"Total kits: {collection['data']['total_entries']}")
print(f"Page {collection['pagination']['current_page']} of {collection['pagination']['total_pages']}")

for kit in collection['data']['entries']:
    print(f"- {kit['kit_name']}")

const BASE_URL = 'https://your-domain.com/api';
const API_KEY = 'your-api-key-here';
const headers = { 'X-API-Key': API_KEY };

const userid = 148184;

// Step 1: Start scraping
const scrapeResponse = await fetch(
  `${BASE_URL}/user-collection/${userid}/scrape`,
  { method: 'POST', headers }
);
const scrapeResult = await scrapeResponse.json();
console.log(`Scrape status: ${scrapeResult.status}`);

// Step 2: Wait if processing
if (scrapeResult.status === 'processing') {
  console.log(`Task ID: ${scrapeResult.task_id}`);
  console.log('Waiting 60 seconds...');
  await new Promise(resolve => setTimeout(resolve, 60000));
}

// Step 3: Get paginated collection
const collectionResponse = await fetch(
  `${BASE_URL}/user-collection/${userid}?page=1&page_size=20`,
  { headers }
);
const collection = await collectionResponse.json();

console.log(`Total kits: ${collection.data.total_entries}`);
console.log(`Page ${collection.pagination.current_page} of ${collection.pagination.total_pages}`);

collection.data.entries.forEach(kit => {
  console.log(`- ${kit.kit_name}`);
});

# Step 1: Start scraping
curl -X POST "https://your-domain.com/api/user-collection/148184/scrape" \
  -H "X-API-Key: your-api-key-here"

# If response is 202 Accepted, wait ~60 seconds

# Step 2: Get first page of collection
curl -X GET "https://your-domain.com/api/user-collection/148184?page=1&page_size=20" \
  -H "X-API-Key: your-api-key-here"

# Step 3: Get next page
curl -X GET "https://your-domain.com/api/user-collection/148184?page=2&page_size=20" \
  -H "X-API-Key: your-api-key-here"

Force Re-scrape

curl -X POST "https://your-domain.com/api/user-collection/148184/scrape?force=true" \
  -H "X-API-Key: your-api-key-here"

To get updated collection data with the latest kits and user information, use the force=true parameter. This invalidates the existing cache and performs a fresh scrape.

Force re-scraping should be used sparingly to avoid unnecessary load on FootballKitArchive servers. Collections are cached for 1 week.

Cache Duration

User collections are cached for 1 week (604,800 seconds) after scraping. After this period, a fresh scrape will be required.

Finding User IDs

To find a user’s ID on FootballKitArchive:

Visit the user’s profile on FootballKitArchive
Look at the URL: https://www.footballkitarchive.com/user/{userid}/
The number in the URL is the user ID

Example: https://www.footballkitarchive.com/user/148184/ → User ID is 148184

Rate Limiting

The scraping process respects rate limits (minimum 2 seconds between requests) to avoid overloading FootballKitArchive servers. Large collections may take several minutes to scrape.

Ethical Considerations

This endpoint is designed for personal use and respects FootballKitArchive’s robots.txt and rate limits. Do not abuse this endpoint or scrape excessively.

Overview

Endpoints

Advanced

User Collections

Overview

Scrape User Collection

Path Parameters

Query Parameters

Response Codes

Response (200 OK - Cached)

Response (202 Accepted - Processing)

Usage Flow

Get User Collection

Path Parameters

Query Parameters

Response Codes

Response (200 OK)

Response (404 Not Found)

Complete Example Workflow

Force Re-scrape

Cache Duration

Finding User IDs

Rate Limiting

Ethical Considerations

​Overview

​Scrape User Collection

​Path Parameters

​Query Parameters

​Response Codes

​Response (200 OK - Cached)

​Response (202 Accepted - Processing)

​Usage Flow

​Get User Collection

​Path Parameters

​Query Parameters

​Response Codes

​Response (200 OK)

​Response (404 Not Found)

​Complete Example Workflow

​Force Re-scrape

​Cache Duration

​Finding User IDs

​Rate Limiting

​Ethical Considerations

Overview

Scrape User Collection

Path Parameters

Query Parameters

Response Codes

Response (200 OK - Cached)

Response (202 Accepted - Processing)

Usage Flow

Get User Collection

Path Parameters

Query Parameters

Response Codes

Response (200 OK)

Response (404 Not Found)

Complete Example Workflow

Force Re-scrape

Cache Duration

Finding User IDs

Rate Limiting

Ethical Considerations