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

userid

integer

required

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

Query Parameters

force

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)

status

string

Status of the response: “cached”

data

object

Collection data object

data.success

boolean

Whether the scraping was successful

data.entries

array

Array of kit entries in the collection

data.total_entries

integer

Total number of kits in the collection

data.pages_scraped

integer

Number of pages scraped from FootballKitArchive

pagination

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)

status

string

Status of the response: “processing”

task_id

string

Celery task ID for tracking the scraping job

message

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

userid

integer

required

User ID from FootballKitArchive

Query Parameters

page

integer

default:"1"

Page number for pagination (minimum: 1)

page_size

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)

status

string

Status of the response: “ready”

data

object

Collection data object

data.success

boolean

Whether the scraping was successful

data.entries

array

Array of kit entries for the current page

data.entries[].kit_id

integer

Kit ID

data.entries[].kit_name

string

Full name of the kit

data.entries[].kit_slug

string

URL-friendly slug for the kit

data.entries[].team_name

string

Club/team name

data.entries[].season_year

string

Season year

data.entries[].main_img_url

string

URL to the kit image

data.total_entries

integer

Total number of kits in the collection

data.pages_scraped

integer

Number of pages scraped from FootballKitArchive

data.user

object

User information (if available from scraping)

data.user.name

string

User’s display name

data.user.image

string

URL to user’s profile image

data.user.twitter

string

Twitter handle

data.user.instagram

string

Instagram handle

data.user.description

string

User’s profile description

data.user.points

integer

User’s points on FootballKitArchive

pagination

object

Pagination information

pagination.current_page

integer

Current page number

pagination.total_pages

integer

Total number of pages

pagination.total_count

integer

Total number of kits

pagination.page_size

integer

Number of items per page

pagination.has_next

boolean

Whether there is a next page

pagination.has_previous

boolean

Whether there is a previous page

pagination.next_page

integer

Next page number (null if no next page)

pagination.previous_page

integer

Previous page number (null if no previous page)

cached_until

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)

status

string

Status of the response: “not_found”

message

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']}")

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

Endpoints

Advanced

​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