GitHub - FOOR29/IconicFootball-API: IconicFootball API is a public REST API that provides data about legendary football players in their prime, including FIFA-style stats (PAC, SHO, PAS, DRI, DEF, PHY), country, club, images, and more.

📋 Table of Contents

About
Tech Stack
Rate Limiting
API Endpoints
Response Structure
Player Attributes
Cache System
Database Relations

🎯 About

IconicFootball-API is a RESTful API built with Laravel 12 that provides detailed information about iconic football players, including their stats, clubs, and national teams. The API features intelligent caching, rate limiting by user roles, and optimized queries for high performance.

🛠️ Tech Stack

Framework: Laravel 12
Database: PostgreSQL (Neon)
Cache: Redis
Image Storage: Cloudinary
API Type: RESTful

⚡ Rate Limiting

The API implements rate limiting based on user categories to ensure fair usage and optimal performance:

Category	Requests per Minute	Identifier
🌍 Public	200	IP Address
👤 Authenticated User	250	User ID / IP
👑 Admin	500	User ID / IP

Note: When rate limit is exceeded, you'll receive a 429 Too Many Requests response.

📡 API Endpoints

Base URL

https://iconicfootball-api.fly.dev/api/players

Get All Players

Retrieve a paginated list of all players in the database.

Endpoint

GET /players

Default Response (20 players per page)

{
    "data": [
        {
            "id": 1,
            "known_as": "Kahn",
            "full_name": "Oliver Rolf Kahn",
            "img": "https://res.cloudinary.com/.../oliver_nfalr0.png",
            "prime_season": "2001-2002",
            "prime_position": "GK",
            "preferred_foot": "right",
            "spd": 82,
            "sho": 25,
            "pas": 59,
            "dri": 44,
            "def": 95,
            "phy": 92,
            "prime_rating": 93,
            "club_id": 1,
            "country_id": 1
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}

Get Player by ID

Retrieve detailed information about a specific player.

Endpoint

GET /players/{id}

Example

GET https://iconicfootball-api.fly.dev/api/players/1

Response

{
    "player": {
        "id": 1,
        "known_as": "Kahn",
        "full_name": "Oliver Rolf Kahn",
        "img": "https://res.cloudinary.com/.../oliver_nfalr0.png",
        "prime_season": "2001-2002",
        "prime_position": "GK",
        "preferred_foot": "right",
        "spd": 82,
        "sho": 25,
        "pas": 59,
        "dri": 44,
        "def": 95,
        "phy": 92,
        "prime_rating": 93,
        "club_id": 1,
        "country_id": 1
    },
    "status": 200
}

Include Relations

You can include related data (club and/or country) in your requests using the include parameter.

Include Club and Country

Endpoint

GET https://iconicfootball-api.fly.dev/api/players/1?include=club,country

Response

{
    "data": [
        {
            "id": 1,
            "known_as": "Kahn",
            "full_name": "Oliver Rolf Kahn",
            "img": "https://res.cloudinary.com/.../oliver_nfalr0.png",
            "prime_season": "2001-2002",
            "prime_position": "GK",
            "preferred_foot": "right",
            "spd": 82,
            "sho": 25,
            "pas": 59,
            "dri": 44,
            "def": 95,
            "phy": 92,
            "prime_rating": 93,
            "club_id": 1,
            "country_id": 1,
            "club": {
                "id": 1,
                "name": "FC Bayern Múnich",
                "logo": "https://res.cloudinary.com/.../bayern-munich.png"
            },
            "country": {
                "id": 1,
                "name": "Alemania",
                "logo": "https://res.cloudinary.com/.../de_apncmu.png"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}

Include Only Club

Endpoint

GET /players?include=club

Response

{
    "data": [
        {
            "id": 1,
            "known_as": "Kahn",
            "full_name": "Oliver Rolf Kahn",
            "img": "https://res.cloudinary.com/.../oliver_nfalr0.png",
            "prime_season": "2001-2002",
            "prime_position": "GK",
            "preferred_foot": "right",
            "spd": 82,
            "sho": 25,
            "pas": 59,
            "dri": 44,
            "def": 95,
            "phy": 92,
            "prime_rating": 93,
            "club_id": 1,
            "country_id": 1,
            "club": {
                "id": 1,
                "name": "FC Bayern Múnich",
                "logo": "https://res.cloudinary.com/.../bayern-munich.png"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}

Include Only Country

Endpoint

GET /players?include=country

Single Player with Relations

Endpoint

GET /players/{id}?include=club,country

Example

GET /players/1?include=club,country

Response

{
    "player": {
        "id": 1,
        "known_as": "Kahn",
        "full_name": "Oliver Rolf Kahn",
        "img": "https://res.cloudinary.com/.../oliver_nfalr0.png",
        "prime_season": "2001-2002",
        "prime_position": "GK",
        "preferred_foot": "right",
        "spd": 82,
        "sho": 25,
        "pas": 59,
        "dri": 44,
        "def": 95,
        "phy": 92,
        "prime_rating": 93,
        "club_id": 1,
        "country_id": 1,
        "club": {
            "id": 1,
            "name": "FC Bayern Múnich",
            "logo": "https://res.cloudinary.com/.../bayern-munich.png"
        },
        "country": {
            "id": 1,
            "name": "Alemania",
            "logo": "https://res.cloudinary.com/.../de_apncmu.png"
        }
    },
    "status": 200
}

Pagination

Control the number of results per page and navigate through pages.

Custom Items per Page

Endpoint

GET /players?per_page={number}

Example (Get 11 players)

GET https://iconicfootball-api.fly.dev/api/players?per_page=11

Note: Default pagination is 20 items per page. Maximum recommended: 20.

Navigate Pages

Endpoint

GET /players?page={number}

Example

GET https://iconicfootball-api.fly.dev/api/players?page=2

Combined Parameters

You can combine multiple parameters for precise queries:

Example (11 players with club and country data)

GET /players?include=club,country&per_page=11

Example (Page 2 with club data)

GET /players?page=2&include=club

📊 Response Structure

Successful List Response

{
    "data": [
        /* Array of players */
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 100,
        "last_page": 5
    }
}

Successful Single Player Response

{
    "player": {
        /* Player object */
    },
    "status": 200
}

Not Found Response

{
    "message": "Player not found",
    "status": 404
}

Empty Result

{
    "message": "Players not found",
    "status": 200
}

👤 Player Attributes

Attribute	Type	Description
`id`	Integer	Unique player identifier
`known_as`	String	Player's popular name
`full_name`	String	Complete legal name
`img`	String (URL)	Player's image (Cloudinary)
`prime_season`	String	Peak performance season
`prime_position`	String	Primary position during prime
`preferred_foot`	String	Preferred foot (left/right)
`spd`	Integer	Speed stat (0-99)
`sho`	Integer	Shooting stat (0-99)
`pas`	Integer	Passing stat (0-99)
`dri`	Integer	Dribbling stat (0-99)
`def`	Integer	Defense stat (0-99)
`phy`	Integer	Physical stat (0-99)
`prime_rating`	Integer	Overall rating (0-99)
`club_id`	Integer	Foreign key to club
`country_id`	Integer	Foreign key to country

🚀 Cache System

The API implements Redis caching for optimal performance:

Cache Duration: 60 seconds
Cache Strategy: Query-based caching
Cache Keys: Generated from request parameters (page, per_page, include)
Benefits: Reduced database load, faster response times

Cached Endpoints:

✅ GET /players (all combinations)
✅ GET /players/{id} (all combinations)

🔗 Database Relations

Player Model Relationships

Player
├── belongsTo → Club
└── belongsTo → Country

Club
└── hasMany → Players

Country
└── hasMany → Players

Available Relations:

club: Club information with logo
country: Country information with flag

💡 Usage Examples

Basic Request (JavaScript)

fetch("http://your-domain.com/api/players")
    .then((response) => response.json())
    .then((data) => console.log(data));

With Parameters (JavaScript)

const url =
    "http://your-domain.com/api/players?include=club,country&per_page=11";
fetch(url)
    .then((response) => response.json())
    .then((data) => console.log(data));

cURL Example

curl -X GET "http://your-domain.com/api/players?include=club,country&per_page=11"

📝 Notes

All responses are in JSON format
All timestamps use UTC timezone
Images are hosted on Cloudinary CDN
API responses include proper HTTP status codes
Pagination metadata is included in list responses

📄 License

Open Source

By: Forlán ordoñez

🇪🇸 Ver documentación en Español

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/assets/logo		.github/assets/logo
app		app
bootstrap		bootstrap
config		config
database		database
docker		docker
public		public
resources		resources
routes		routes
storage		storage
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README-ES.md		README-ES.md
README.md		README.md
artisan		artisan
composer.json		composer.json
composer.lock		composer.lock
docker-compose.yml		docker-compose.yml
fly.toml		fly.toml
package-lock.json		package-lock.json
package.json		package.json
phpunit.xml		phpunit.xml
start.sh		start.sh
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

📋 Table of Contents

🎯 About

🛠️ Tech Stack

⚡ Rate Limiting

📡 API Endpoints

Base URL

Get All Players

Get Player by ID

Include Relations

Include Club and Country

Include Only Club

Include Only Country

Single Player with Relations

Pagination

Custom Items per Page

Navigate Pages

Combined Parameters

📊 Response Structure

Successful List Response

Successful Single Player Response

Not Found Response

Empty Result

👤 Player Attributes

🚀 Cache System

🔗 Database Relations

Player Model Relationships

💡 Usage Examples

Basic Request (JavaScript)

With Parameters (JavaScript)

cURL Example

📝 Notes

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages