go-fantasy-pl

A feature-rich, high-performance Go SDK for the official Fantasy Premier League API.

go-fantasy-pl provides a typed, idiomatic interface for interacting with FPL data. It includes built-in caching, automatic rate limiting, and asynchronous helpers for high-throughput workloads.

Key Features

• Performance-first async helpers for fetching players, teams, and fixtures concurrently.
• Fully typed models for FPL API responses.
• Redis-first caching with automatic in-memory fallback for local development.
• Configurable timeouts, rate limits, and base URLs.
• Modular service-based architecture for testing and extension.

Installation

go get github.com/AbdoAnss/go-fantasy-pl

Requires Go 1.23 or higher.

Quick Start

package main

import (
	"fmt"
	"log"

	"github.com/AbdoAnss/go-fantasy-pl/client"
)

func main() {
	c, err := client.NewClient()
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}

	teams, err := c.Teams.GetAllTeams()
	if err != nil {
		log.Fatalf("failed to fetch teams: %v", err)
	}

	players, err := c.Players.GetAllPlayers()
	if err != nil {
		log.Fatalf("failed to fetch players: %v", err)
	}

	fmt.Printf("Successfully loaded %d teams and %d players.\n", len(teams), len(players))
}

Caching

client.NewClient() now prefers Redis by default.

• If Redis is reachable, the SDK uses it automatically.
• If Redis is not reachable, the SDK falls back to the in-memory cache.
• If you want Redis to be mandatory, set FPL_CACHE_BACKEND=redis.
• If you want to force in-memory caching, use client.WithMemoryCache() or set FPL_CACHE_BACKEND=memory.

Environment Variables

export REDIS_ADDR=localhost:6379
export REDIS_PASSWORD=
export REDIS_DB=0
export REDIS_KEY_PREFIX=go-fantasy-pl
export FPL_CACHE_BACKEND=auto

Supported FPL_CACHE_BACKEND values:

• auto: try Redis first, then fall back to memory.
• redis: require Redis and fail client creation if it is unavailable.
• memory: skip Redis and use the in-memory cache.

Explicit Redis Configuration

c, err := client.NewClient(
	client.WithRedisCache(client.RedisOptions{
		Addr:      "localhost:6379",
		Password:  "",
		DB:        0,
		KeyPrefix: "go-fantasy-pl",
	}),
)

Advanced Usage

Asynchronous Data Retrieval

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/AbdoAnss/go-fantasy-pl/client"
)

func main() {
	c, err := client.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()

	playersCh := c.Players.GetAllPlayersAsync(ctx)
	teamsCh := c.Teams.GetAllTeamsAsync(ctx)
	fixturesCh := c.Fixtures.GetAllFixturesAsync(ctx)

	playersRes := <-playersCh
	teamsRes := <-teamsCh
	fixturesRes := <-fixturesCh

	if playersRes.Err != nil || teamsRes.Err != nil || fixturesRes.Err != nil {
		log.Fatal("one or more requests failed")
	}

	fmt.Printf(
		"Fetched %d players, %d teams, and %d fixtures concurrently!\n",
		len(playersRes.Value),
		len(teamsRes.Value),
		len(fixturesRes.Value),
	)
}

Configuration Options

c, err := client.NewClient(
	client.WithTimeout(30*time.Second),
	client.WithRateLimit(100, time.Minute),
	client.WithBaseURL("https://custom-proxy.example/api"),
)

CI/CD

The GitHub Actions pipeline now covers:

• formatting, module tidy checks, vet, tests, and builds on pull requests and pushes
• Docker image publishing to GHCR on main and version tags
• optional deployment webhook triggering on main

Optional repository secrets:

• CODECOV_TOKEN
• DEPLOY_WEBHOOK_URL
• DEPLOY_WEBHOOK_TOKEN

Project Structure

• client/: main entry point and configuration
• endpoints/: domain-specific service implementations
• models/: data structures mapping to FPL API responses
• internal/cache/: cache implementations
• examples/: example programs

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.