> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fkapi.sunr4y.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Football Kit Archive API

> A comprehensive Django REST API for managing and retrieving football kit data from around the world

<img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/sunr4y-fkapi-12-12/images/hero-light.svg" alt="Hero Light" />

<img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/sunr4y-fkapi-12-12/images/hero-dark.svg" alt="Hero Dark" />

## Welcome to FKApi

FKApi is a powerful Django REST API that provides comprehensive access to football kit information from clubs worldwide. Built with Django 5.0.4 and Django Ninja, it offers advanced search capabilities, caching, and ethical web scraping integration.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Get started with your first API call in minutes
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Complete installation and setup guide
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Explore available endpoints and schemas
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/sunr4y/fkapi">
    View source code and contribute
  </Card>
</CardGroup>

## Overview

FKApi provides a comprehensive database of football kits with rich metadata including:

* **300,000+ Kits** from clubs worldwide
* **5,000+ Clubs** with logos and country data
* **Seasons** from historical to current (e.g., "2025-26", "1996-97")
* **Brands** including Nike, Adidas, Puma, and more
* **Competitions** with league and tournament information
* **Color Analysis** with primary and secondary color extraction
* **Kit Types** categorized from match kits to training wear

## Key Features

### Advanced Search

Trigram-based fuzzy search with accent-insensitive matching:

* Find "Málaga" by searching "Malaga"
* Search clubs, kits, brands, and competitions
* Priority-based season ordering for relevant results
* Secondary team filtering (prioritizes first teams over B/Youth teams)

### Performance & Caching

* **Redis Caching**: Configurable cache layers for optimal performance
* **Bulk Endpoints**: Retrieve multiple kits/clubs in a single request
* **Pagination**: Efficient handling of large datasets (default: 20 items/page, max: 100)
* **Rate Limiting**: 100 requests/hour per IP (configurable with whitelist support)

### Data Management

* **Ethical Scraping**: Built-in respect for robots.txt and rate limits (2-5 second delays)
* **Celery Integration**: Optional background task processing for scalability
* **Data Quality**: Management commands for validation and cleanup
* **Real-time Updates**: Daily automated scraping for latest kit releases

### API Capabilities

* **RESTful Design**: Clean, predictable endpoint structure
* **JSON Responses**: Standardized schemas with comprehensive metadata
* **Optional Authentication**: API key support via `X-API-Key` header
* **Health Monitoring**: Built-in health checks and metrics endpoints
* **OpenAPI/Swagger**: Auto-generated interactive API documentation

## Technology Stack

<CardGroup cols={3}>
  <Card title="Django 5.0.4" icon="python">
    Modern web framework with ORM
  </Card>

  <Card title="Django Ninja" icon="ninja">
    Fast, type-hinted REST framework
  </Card>

  <Card title="PostgreSQL 15+" icon="database">
    Robust relational database
  </Card>

  <Card title="Redis 6+" icon="fire">
    Caching and task queuing
  </Card>

  <Card title="Celery" icon="clock">
    Optional async task processing
  </Card>

  <Card title="BeautifulSoup4" icon="code">
    Web scraping capabilities
  </Card>
</CardGroup>

## Current Version

**Version 1.0.2** (Released: February 4, 2026)

Recent updates include:

* Bulk kits endpoint accepting 2-30 kits per request
* User collection API with pagination and caching
* IP whitelist support for rate limiting
* Enhanced security with HTML sanitization
* Improved Type\_K categorization system
* Season search with priority-based ordering

<Note>
  FKApi starts with an empty database. You'll need to populate it through ethical web scraping following the guidelines in the Getting Started documentation.
</Note>

## Use Cases

* **Mobile Apps**: Build football kit collection and browsing apps
* **Analytics**: Analyze kit design trends across seasons and brands
* **E-commerce**: Integrate kit data into merchandise platforms
* **Research**: Study branding patterns and color psychology in sports
* **Fan Sites**: Create comprehensive kit archives for clubs

## Next Steps

<Steps>
  <Step title="Quick Start">
    Follow the [Quickstart Guide](/quickstart) to make your first API call in under 5 minutes
  </Step>

  <Step title="Full Installation">
    Set up a complete development environment with the [Installation Guide](/installation)
  </Step>

  <Step title="Explore the API">
    Browse endpoints and test queries in the interactive API documentation at `/api/docs`
  </Step>

  <Step title="Populate Data">
    Learn ethical scraping practices to populate your database responsibly
  </Step>
</Steps>

## Community & Support

* **Maintainer**: sunr4y
* **License**: MIT
* **Last Updated**: March 3, 2026

<Warning>
  Always scrape responsibly: Check robots.txt, use proper User-Agent headers, respect rate limits (minimum 2 seconds between requests), and ensure you have permission to scrape target websites.
</Warning>