Skip to main content
FootyCollect integrates with the Football Kit Archive via FKAPI (Football Kit Archive API) to provide a seamless search-and-add workflow for cataloging your collection. This integration automatically populates item metadata including club, season, competition, brand, and design information.

​
What is FKAPI?

FKAPI is a RESTful API service that provides access to the Football Kit Archive database, which contains thousands of football kits from clubs around the world. It serves as the primary data source for kit metadata when adding items to your FootyCollect collection.
FKAPI is an optional dependency. FootyCollect works without FKAPI, but you’ll need to enter all item details manually. With FKAPI running, you get automatic metadata population and search capabilities.

​
Key Features

  • Club search: Search for clubs by name
  • Season lookup: Get available seasons for each club
  • Kit catalog: Browse kits by club and season
  • Kit details: Retrieve complete kit information including colors, design, competitions, and images
  • Bulk operations: Fetch multiple kits in a single request

​
How FKAPI Integrates with FootyCollect

The integration works through a client-service architecture:

​
FKAPIClient

The FKAPIClient class handles all communication with the FKAPI service: 
class FKAPIClient:
    def __init__(self):
        self.base_url = f"http://{settings.FKA_API_IP}"
        self.api_key = settings.API_KEY
        self.cache_timeout = 3600  # 1 hour cache
        self.request_timeout = 60
        self.max_retries = 3

Circuit Breaker

Prevents cascading failures by temporarily blocking requests after repeated failures

Rate Limiting

Maximum 100 requests per minute to protect the API

Retry Logic

Automatic retry with exponential backoff for failed requests

Response Caching

1-hour cache for search results and kit details

​
Configuration

Set these environment variables to enable FKAPI integration:
.env
FKA_API_IP=localhost:8000  # FKAPI server address
API_KEY=your_api_key_here  # FKAPI authentication key

​
Search Workflow

​
1. Search for Clubs

When creating a new item, start by searching for a club: 
client = FKAPIClient()
clubs = client.search_clubs(query="Real Madrid")
# Returns: [{"id": 123, "name": "Real Madrid CF", "country": "ESP", ...}]

​
2. Get Club Seasons

Once you select a club, fetch available seasons: 
seasons = client.get_club_seasons(club_id=123)
# Returns: [{"id": 456, "year": "2023-24", ...}, {"id": 457, "year": "2022-23", ...}]

​
3. Browse Kits for Season

Select a season to see available kits: 
kits = client.get_club_kits(club_id=123, season_id=456)
# Returns: [
#   {"id": 789, "type": "Home", "brand": "Adidas", ...},
#   {"id": 790, "type": "Away", "brand": "Adidas", ...}
# ]

​
4. Get Kit Details

Retrieve complete metadata for the selected kit: 
kit_details = client.get_kit_details(kit_id=789)
# Returns complete kit data including:
# - Colors (main, secondary)
# - Design pattern
# - Competitions
# - Brand information
# - Official images
Kit details are cached for 1 hour by default. Set use_cache=False if you need fresh data:
kit_details = client.get_kit_details(kit_id=789, use_cache=False)

​
Automatic Metadata Population

When you select a kit from FKAPI, FootyCollect automatically populates:

​
Club Information

  • Club name
  • Club logo (downloaded and stored locally)
  • Country

​
Season Data

  • Season year (e.g., “2023-24”)
  • Start and end dates

​
Kit Details

  • Kit type (Home, Away, Third, Goalkeeper, etc.)
  • Brand name and logo
  • Main color and secondary colors
  • Design pattern (Stripes, Plain, Hoops, etc.)

​
Competitions

  • Associated leagues and tournaments
  • Competition logos
The FKAPIKitProcessor service handles kit data processing:
class FKAPIKitProcessor:
    def process_kit_data(self, form, kit_id: int):
        # Fetch kit details from FKAPI
        kit_data = self.fkapi_client.get_kit_details(kit_id)
        
        # Process and create/update entities
        club = self._process_club(kit_data)
        season = self._process_season(kit_data)
        brand = self._process_brand(kit_data)
        kit_type = self._process_kit_type(kit_data)
        competitions = self._process_competitions(kit_data)
        colors = self._process_colors(kit_data)
        
        # Populate form instance
        form.instance.club = club
        form.instance.season = season
        form.instance.brand = brand
        # ... and so on
This ensures all related entities (clubs, brands, competitions) are created in your local database if they don’t already exist.

​
Advanced Features

​
Bulk Kit Fetching

Fetch multiple kits in a single API call: 
slugs = ["real-madrid-home-2023-24", "barcelona-home-2023-24"]
kits = client.get_kits_bulk(slugs)
# Returns reduced response format for 2-30 kits
Bulk endpoint supports 2-30 slugs per request. Requests with fewer than 2 or more than 30 slugs will be rejected or truncated.

​
User Collection Scraping

Import your entire collection from Football Kit Archive: 
# Queue scraping task
client.scrape_user_collection(userid=12345)
# Returns: {"status": "queued"}

# Check progress
collection = client.get_user_collection(
    userid=12345,
    page=1,
    page_size=20
)
This asynchronous operation:
  1. Scrapes your Football Kit Archive collection
  2. Processes each kit through FKAPI
  3. Creates corresponding items in FootyCollect
  4. Downloads and optimizes kit images

​
Alternative Search Methods

If FKAPI is unavailable, the client falls back to alternative methods: 
# Direct brand search
brands = client.search_brands(query="Nike")

# If FKAPI unavailable, searches kits and extracts brands
if result is None:
    kits = self.search_kits(query)
    brands = {}
    for kit in kits:
        brand = kit.get("brand")
        if brand:
            brands[brand["name"]] = brand
    return list(brands.values())

​
Error Handling & Resilience

​
Circuit Breaker Pattern

Prevents overwhelming a failing FKAPI service: 
class CircuitBreaker:
    def __init__(self, failure_threshold: int = 5, timeout: int = 60):
        self.failure_threshold = failure_threshold
        self.timeout = timeout
        self.state = "closed"  # closed, open, half_open
    
    def record_failure(self):
        self.failure_count += 1
        if self.failure_count >= self.failure_threshold:
            self.state = "open"
            # Block requests for 60 seconds
States:
  • Closed: Normal operation, all requests allowed
  • Open: Service failing, requests blocked for timeout period
  • Half-Open: Testing if service recovered

​
Retry with Exponential Backoff

for attempt in range(self.max_retries):
    if attempt > 0:
        wait_time = 2 ** attempt  # 2s, 4s, 8s
        time.sleep(wait_time)
    
    response = requests.get(url, timeout=60)
    if response.status_code == 200:
        return response.json()

​
Stale Cache Fallback

If FKAPI is unavailable, FootyCollect serves stale cached data: 
if not self.circuit_breaker.allow_request():
    # Serve stale cache if available
    return cache.get(cache_key)
When FKAPI is completely unavailable and cache is empty, you’ll need to enter item details manually. The system gracefully degrades to manual entry mode.

​
Benefits of FKAPI Integration

Time Savings

Automatically populate 10+ fields with a single kit selection

Data Accuracy

Official data from Football Kit Archive ensures correct details

Consistency

Standardized club names, brands, and competitions across all items

Rich Metadata

Access to competitions, design patterns, and color information

Logo Downloads

Automatic download of club and brand logos

Bulk Import

Import entire collections from Football Kit Archive

​
API Endpoints

EndpointMethodDescription
/api/clubs/searchGETSearch clubs by keyword
/api/seasonsGETGet seasons for a club
/api/clubs/{id}/kitsGETGet kits for club/season
/api/kits/{id}GETGet kit details
/api/kits/searchGETSearch kits by keyword
/api/kits/bulkGETGet multiple kits by slugs
/api/brands/searchGETSearch brands
/api/competitions/searchGETSearch competitions
/api/user-collection/{id}GETGet user collection
/api/user-collection/{id}/scrapePOSTStart collection import

​
Running FKAPI Locally

To enable FKAPI integration in development:
  1. Clone the FKAPI repository: 
    git clone https://github.com/sunr4y/fkapi.git
cd fkapi
  2. Follow FKAPI setup instructions to start the service
  3. Configure FootyCollect environment: 
    FKA_API_IP=localhost:8000
API_KEY=your_dev_api_key
  4. Restart FootyCollect to enable integration
For production deployments, run FKAPI as a separate service and configure the FKA_API_IP to point to your FKAPI server.