f1

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 2, 2026 License: MIT Imports: 9 Imported by: 0

README

jolpica-go

A Go client library for the Jolpica F1 API — the open-source successor to the Ergast Formula 1 API.

Tests

Installation

go get github.com/kostplu/jolpica-go

Requires Go 1.25 or later.

Quick start

package main

import (
    "fmt"
    f1 "github.com/kostplu/jolpica-go"
)

func main() {
    client := f1.NewClient()

    drivers, err := client.GetDrivers(f1.WithSeason(2024))
    if err != nil {
        panic(err)
    }

    for _, d := range drivers.Drivers {
        fmt.Printf("%s %s (%s)\n", d.GivenName, d.FamilyName, d.Code)
    }
}

Usage

Creating a client
// default client
client := f1.NewClient()

// with caching — strongly recommended
// historical data never changes, caching avoids hammering Jolpica's servers
client := f1.NewClient(
    f1.WithCache("~/.cache/jolpica-go/cache.db", 24*time.Hour),
)

// with a custom timeout
client := f1.NewClient(
    f1.WithTimeout(15 * time.Second),
)
Filtering

All methods accept functional options to filter results:

// by season
client.GetDrivers(f1.WithSeason(2024))

// by season and constructor
client.GetDrivers(f1.WithSeason(2024), f1.WithConstructor("ferrari"))

// by season, round, and driver
client.GetResults(
    f1.WithSeason(2024),
    f1.WithRound(1),
    f1.WithDriver("hamilton"),
)
Pagination

Each method returns a page with pagination metadata:

page, err := client.GetDrivers(
    f1.WithSeason(2024),
    f1.WithLimit(10),
)

fmt.Println(page.PageInfo.Total)      // total results available
fmt.Println(page.PageInfo.HasMore())  // true if more pages exist

// fetch next page
next, err := client.GetDrivers(
    f1.WithSeason(2024),
    f1.WithLimit(10),
    f1.WithOffset(page.PageInfo.NextOffset()),
)

To fetch all pages automatically:

drivers, err := client.GetAllDrivers(f1.WithSeason(2024))
Endpoints
Method Description
GetDrivers(opts...) Drivers
GetConstructors(opts...) Constructors
GetRaces(opts...) Race schedule
GetResults(opts...) Race results
GetQualifying(opts...) Qualifying results
GetDriverStandings(opts...) Driver standings
GetConstructorStandings(opts...) Constructors standings
GetCircuits(opts...) Circuit information
GetLaps(opts...) Lap times
GetPitStops(opts...) Pit stop data
GetSprintResults(opts...) Sprint race results
GetStatus(opts...) Status codes

Each method has a corresponding GetAll variant that handles pagination automatically.

Typed values

All values are returned as proper Go types — no manual parsing needed:

results, _ := client.GetResults(f1.WithSeason(2024), f1.WithRound(1))
race := results.Races[0]

// positions and points are ints and floats, not strings
winner := race.Results[0]
fmt.Println(int(winner.Position))        // 1
fmt.Println(float64(winner.Points))      // 25.0

// lap times are time.Duration
fmt.Println(winner.FastestLap.Time.Duration.Seconds()) // 83.456

// dates are time.Time
driver := winner.Driver
fmt.Println(driver.DateOfBirth.Year())   // 1985
Examples

Driver standings after a specific round:

standings, err := client.GetStandings(
    f1.WithSeason(2024),
    f1.WithRound(10),
)
for _, s := range standings.Standings[0].DriverStandings {
    fmt.Printf("P%d %s — %s pts\n",
        int(s.Position),
        s.Driver.Code,
        s.Points,
    )
}

Qualifying results for a specific race:

page, err := client.GetQualifying(
    f1.WithSeason(2024),
    f1.WithRound(1),
)
race := page.Races[0]
for _, q := range race.QualifyingResults {
    fmt.Printf("P%d %s — Q1: %s\n",
        int(q.Position),
        q.Driver.Code,
        q.Q1.Duration,
    )
}

All races Hamilton won:

results, err := client.GetAllResults(f1.WithDriver("hamilton"))
var wins []Race
for _, race := range results {
    if len(race.Results) > 0 && int(race.Results[0].Position) == 1 {
        wins = append(wins, race)
    }
}
fmt.Printf("Hamilton wins: %d\n", len(wins))

Caching

jolpica-go uses SQLite for caching. Historical F1 data never changes, so caching is strongly recommended both for performance and to be respectful of Jolpica's free service.

client := f1.NewClient(
    f1.WithCache("./f1-cache.db", 24*time.Hour),
)

Cache TTL guidance:

  • Historical seasons (any completed season) — 24*time.Hour or longer
  • Current season race results — 1*time.Hour
  • Current season standings — 30*time.Minute

Rate limiting

Jolpica enforces a limit of 500 requests per hour. jolpica-go's built-in caching reduces the number of requests made, and GetAll methods include a small delay between pages to avoid bursting. Please be a considerate user of Jolpica's free service.

Terms of use

By using this library you are indirectly using the Jolpica F1 API. Please review Jolpica's terms of use before building applications with this library.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AverageSpeed 

type AverageSpeed struct {
	Units string `json:"units"`
	Speed string `json:"speed"`
}

type Circuit 

type Circuit struct {
	CircuitID   string   `json:"circuitId"`
	URL         string   `json:"url"`
	CircuitName string   `json:"circuitName"`
	Location    Location `json:"Location"`
}

type CircuitsPage 

type CircuitsPage struct {
	Circuits []Circuit
	PageInfo PageInfo
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(opts ...ClientOption) *Client

func NewClientWithBaseURL 

func NewClientWithBaseURL(baseURL string, opts ...ClientOption) *Client

func (*Client) GetAllCircuits 

func (c *Client) GetAllCircuits(opts ...Option) ([]Circuit, error)

func (*Client) GetAllConstructorStandings 

func (c *Client) GetAllConstructorStandings(opts ...Option) ([]StandingsList, error)

func (*Client) GetAllConstructors 

func (c *Client) GetAllConstructors(opts ...Option) ([]Constructor, error)

func (*Client) GetAllDriverStandings 

func (c *Client) GetAllDriverStandings(opts ...Option) ([]StandingsList, error)

func (*Client) GetAllDrivers 

func (c *Client) GetAllDrivers(opts ...Option) ([]Driver, error)

func (*Client) GetAllLaps 

func (c *Client) GetAllLaps(opts ...Option) ([]Race, error)

func (*Client) GetAllPitStops 

func (c *Client) GetAllPitStops(opts ...Option) ([]Race, error)

func (*Client) GetAllQualifyingResults 

func (c *Client) GetAllQualifyingResults(opts ...Option) ([]Race, error)

func (*Client) GetAllRaces 

func (c *Client) GetAllRaces(opts ...Option) ([]Race, error)

func (*Client) GetAllResults 

func (c *Client) GetAllResults(opts ...Option) ([]Race, error)

func (*Client) GetAllSeasons 

func (c *Client) GetAllSeasons(opts ...Option) ([]Season, error)

func (*Client) GetAllSprintResults 

func (c *Client) GetAllSprintResults(opts ...Option) ([]Race, error)

func (*Client) GetAllStatus 

func (c *Client) GetAllStatus(opts ...Option) ([]Status, error)

func (*Client) GetCircuits 

func (c *Client) GetCircuits(opts ...Option) (*CircuitsPage, error)

func (*Client) GetConstructorStandings 

func (c *Client) GetConstructorStandings(opts ...Option) (*ConstructorStandingPage, error)

func (*Client) GetConstructors 

func (c *Client) GetConstructors(opts ...Option) (*ConstructorPage, error)

func (*Client) GetDriverStandings 

func (c *Client) GetDriverStandings(opts ...Option) (*DriverStandingPage, error)

func (*Client) GetDrivers 

func (c *Client) GetDrivers(opts ...Option) (*DriversPage, error)

func (*Client) GetLaps 

func (c *Client) GetLaps(opts ...Option) (*LapPage, error)

func (*Client) GetPitStops 

func (c *Client) GetPitStops(opts ...Option) (*PitStopPage, error)

func (*Client) GetQualifyingResults 

func (c *Client) GetQualifyingResults(opts ...Option) (*QualifyingResultPage, error)

func (*Client) GetRaces 

func (c *Client) GetRaces(opts ...Option) (*RacePage, error)

func (*Client) GetResults 

func (c *Client) GetResults(opts ...Option) (*RaceResultPage, error)

func (*Client) GetSeasons 

func (c *Client) GetSeasons(opts ...Option) (*SeasonPage, error)

func (*Client) GetSprintResults 

func (c *Client) GetSprintResults(opts ...Option) (*SprintResultPage, error)

func (*Client) GetStatus 

func (c *Client) GetStatus(opts ...Option) (*StatusPage, error)

type ClientOption 

type ClientOption func(*Client)

func WitTimeout 

func WitTimeout(timeout time.Duration) ClientOption

func WithCache 

func WithCache(path string, ttl time.Duration) ClientOption

type Constructor 

type Constructor struct {
	ConstructorID string `json:"constructorId"`
	URL           string `json:"url"`
	Name          string `json:"name"`
	Nationality   string `json:"nationality"`
}

type ConstructorPage 

type ConstructorPage struct {
	Constructors []Constructor
	PageInfo     PageInfo
}

type ConstructorStanding 

type ConstructorStanding struct {
	Position     IntString   `json:"position"`
	PositionText string      `json:"positionText"`
	Points       FloatString `json:"points"`
	Wins         IntString   `json:"wins"`
	Constructor  Constructor `json:"Constructor"`
}

type ConstructorStandingPage 

type ConstructorStandingPage struct {
	StandingsLists []StandingsList
	PageInfo       PageInfo
}

type Date 

type Date struct {
	time.Time
}

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(data []byte) error

type Driver 

type Driver struct {
	DriverID        string    `json:"driverId"`
	PermanentNumber IntString `json:"permanentNumber"`
	Code            string    `json:"code"`
	URL             string    `json:"url"`
	GivenName       string    `json:"givenName"`
	FamilyName      string    `json:"familyName"`
	DateOfBirth     Date      `json:"dateOfBirth"`
	Nationality     string    `json:"nationality"`
}

type DriverStanding 

type DriverStanding struct {
	Position     IntString     `json:"position"`
	PositionText string        `json:"positionText"`
	Points       FloatString   `json:"points"`
	Wins         IntString     `json:"wins"`
	Driver       Driver        `json:"Driver"`
	Constructors []Constructor `json:"Constructors"`
}

type DriverStandingPage 

type DriverStandingPage struct {
	StandingsLists []StandingsList
	PageInfo       PageInfo
}

type DriversPage 

type DriversPage struct {
	Drivers  []Driver
	PageInfo PageInfo
}

type FastestLap 

type FastestLap struct {
	Rank         IntString     `json:"rank"`
	Lap          IntString     `json:"lap"`
	Time         LapTimeObject `json:"Time"`
	AverageSpeed AverageSpeed  `json:"AverageSpeed"`
}

type FloatString 

type FloatString float64

func (*FloatString) UnmarshalJSON 

func (f *FloatString) UnmarshalJSON(data []byte) error

type IntString 

type IntString int

func (*IntString) UnmarshalJSON 

func (i *IntString) UnmarshalJSON(data []byte) error

type Lap 

type Lap struct {
	Number  IntString `json:"number"`
	Timings []Timing  `json:"Timings"`
}

type LapPage 

type LapPage struct {
	Races    []Race
	PageInfo PageInfo
}

type LapTime 

type LapTime struct {
	time.Duration
}

func (*LapTime) UnmarshalJSON 

func (l *LapTime) UnmarshalJSON(data []byte) error

type LapTimeObject 

type LapTimeObject struct {
	LapTime `json:"time"`
}

func (*LapTimeObject) UnmarshalJSON 

func (l *LapTimeObject) UnmarshalJSON(data []byte) error

type Location 

type Location struct {
	Latitude  string `json:"lat"`
	Longitude string `json:"long"`
	Locality  string `json:"locality"`
	Country   string `json:"country"`
}

type Option 

type Option func(*requestOptions)

Option is a function that modifies the request options.

func WithConstructor 

func WithConstructor(constructor string) Option

func WithDriver 

func WithDriver(driver string) Option

func WithLimit 

func WithLimit(limit int) Option

func WithOffset 

func WithOffset(offset int) Option

func WithRound 

func WithRound(round int) Option

func WithSeason 

func WithSeason(season int) Option

type PageInfo 

type PageInfo struct {
	Total  int
	Offset int
	Limit  int
}

func (PageInfo) HasNext 

func (p PageInfo) HasNext() bool

func (PageInfo) NextOffset 

func (p PageInfo) NextOffset() int

type PitStop 

type PitStop struct {
	DriverID string    `json:"driverId"`
	Lap      IntString `json:"lap"`
	Stop     string    `json:"stop"`
	Time     string    `json:"time"`
	Duration string    `json:"duration"`
}

type PitStopPage 

type PitStopPage struct {
	Races    []Race
	PageInfo PageInfo
}

type QualifyingResult 

type QualifyingResult struct {
	Number      IntString   `json:"number"`
	Position    IntString   `json:"position"`
	Driver      Driver      `json:"Driver"`
	Constructor Constructor `json:"Constructor"`
	Q1          LapTime     `json:"Q1"`
	Q2          LapTime     `json:"Q2"`
	Q3          LapTime     `json:"Q3"`
}

type QualifyingResultPage 

type QualifyingResultPage struct {
	Races    []Race
	PageInfo PageInfo
}

type Race 

type Race struct {
	Season            IntString          `json:"season"`
	Round             IntString          `json:"round"`
	URL               string             `json:"url"`
	RaceName          string             `json:"raceName"`
	Circuit           Circuit            `json:"Circuit"`
	Date              Date               `json:"date"`
	Time              string             `json:"time"`
	Results           []Result           `json:"Results,omitempty"`
	SprintResults     []Result           `json:"SprintResults,omitempty"`
	PitStops          []PitStop          `json:"PitStops,omitempty"`
	Laps              []Lap              `json:"Laps,omitempty"`
	FirstPractice     Session            `json:"FirstPractice"`
	SecondPractice    Session            `json:"SecondPractice"`
	ThirdPractice     Session            `json:"ThirdPractice"`
	Qualifying        Session            `json:"Qualifying"`
	QualifyingResults []QualifyingResult `json:"QualifyingResults,omitempty"`
}

type RacePage 

type RacePage struct {
	Races    []Race
	PageInfo PageInfo
}

type RaceResultPage 

type RaceResultPage struct {
	Races    []Race
	PageInfo PageInfo
}

type Result 

type Result struct {
	Number       IntString   `json:"number"`
	Position     IntString   `json:"position"`
	PositionText string      `json:"positionText"`
	Points       FloatString `json:"points"`
	Driver       Driver      `json:"Driver"`
	Constructor  Constructor `json:"Constructor"`
	Grid         IntString   `json:"grid"`
	Laps         IntString   `json:"laps"`
	Status       string      `json:"status"`
	Time         struct {
		Millis string `json:"millis"`
		Time   string `json:"time"`
	} `json:"Time"`
	FastestLap FastestLap `json:"FastestLap"`
}

type Season 

type Season struct {
	Season IntString `json:"season"`
	URL    string    `json:"url"`
}

type SeasonPage 

type SeasonPage struct {
	Seasons  []Season
	PageInfo PageInfo
}

type Session 

type Session struct {
	Date Date   `json:"date"`
	Time string `json:"time"`
}

type SprintResultPage 

type SprintResultPage struct {
	Races    []Race
	PageInfo PageInfo
}

type StandingsList 

type StandingsList struct {
	Season               IntString             `json:"season"`
	Round                IntString             `json:"round"`
	DriverStandings      []DriverStanding      `json:"DriverStandings,omitempty"`
	ConstructorStandings []ConstructorStanding `json:"ConstructorStandings,omitempty"`
}

type Status 

type Status struct {
	StatusID string    `json:"statusId"`
	Count    IntString `json:"count"`
	Status   string    `json:"status"`
}

type StatusPage 

type StatusPage struct {
	Statuses []Status
	PageInfo PageInfo
}

type Timing 

type Timing struct {
	DriverID string  `json:"driverId"`
	Time     LapTime `json:"time"`
	Position string  `json:"position"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.