benchgecko

README

BenchGecko Go SDK

Official Go client for the BenchGecko API. Query AI model data, benchmark scores, and run side-by-side comparisons from Go applications.

BenchGecko tracks every major AI model, benchmark, and provider. This module wraps the public REST API with idiomatic Go types, proper error handling, and zero external dependencies beyond the standard library.

Installation

go get github.com/BenchGecko/benchgecko-go

Requires Go 1.21 or later.

Quick Start

package main

import (
    "fmt"
    "log"

    benchgecko "github.com/BenchGecko/benchgecko-go"
)

func main() {
    client := benchgecko.NewClient(nil)

    // List all tracked AI models
    models, err := client.Models()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Tracking %d models\n", len(models))

    // List all benchmarks
    benchmarks, err := client.Benchmarks()
    if err != nil {
        log.Fatal(err)
    }
    for _, b := range benchmarks[:5] {
        fmt.Println(b.Name)
    }

    // Compare two models head-to-head
    result, err := client.Compare([]string{"gpt-4o", "claude-opus-4"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Compared %d models\n", len(result.Models))
}

API Reference

NewClient(opts *ClientOptions) *Client

Create a new BenchGecko API client. Pass nil for default options (production URL, 30s timeout).

// Custom configuration
client := benchgecko.NewClient(&benchgecko.ClientOptions{
    BaseURL: "http://localhost:3000",
    Timeout: 10 * time.Second,
})

client.Models() ([]Model, error)

Fetch all AI models tracked by BenchGecko. Returns a slice of Model structs with name, provider, slug, and additional metadata.

client.Benchmarks() ([]Benchmark, error)

Fetch all benchmarks tracked by BenchGecko. Returns a slice of Benchmark structs with name, category, and slug.

client.Compare(models []string) (*ComparisonResult, error)

Compare two or more AI models. Pass a slice of model slugs (minimum 2). Returns a ComparisonResult with per-model data.

Error Handling

API errors are returned as *benchgecko.Error with status code and message:

models, err := client.Models()
if err != nil {
    if apiErr, ok := err.(*benchgecko.Error); ok {
        fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
    }
}

Data Attribution

Data provided by BenchGecko. Model benchmark scores are sourced from official evaluation suites. Pricing data is updated daily from provider APIs.

Links

• BenchGecko - AI model benchmarks, pricing, and rankings
• API Documentation
• GitHub Repository

License

MIT

Documentation

Overview

Package benchgecko provides an official Go client for the BenchGecko API.

BenchGecko tracks every major AI model, benchmark, and provider. This package wraps the public REST API so you can query model data, benchmark scores, and run comparisons from Go applications.

Quick start:

client := benchgecko.NewClient(nil)
models, err := client.Models()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Tracking %d models\n", len(models))

Index

• Constants
• type Benchmark
• type Client
  • func NewClient(opts *ClientOptions) *Client
  • func (c *Client) Benchmarks() ([]Benchmark, error)
  • func (c *Client) Compare(models []string) (*ComparisonResult, error)
  • func (c *Client) Models() ([]Model, error)
• type ClientOptions
• type ComparisonResult
• type Error
  • func (e *Error) Error() string
• type Model

Constants

const (
	// DefaultBaseURL is the default BenchGecko API base URL.
	DefaultBaseURL = "https://benchgecko.ai"
	// Version is the SDK version.
	Version = "0.1.0"
)

Types

type Benchmark

type Benchmark struct {
	ID       string                 `json:"id,omitempty"`
	Name     string                 `json:"name,omitempty"`
	Slug     string                 `json:"slug,omitempty"`
	Category string                 `json:"category,omitempty"`
	Extra    map[string]interface{} `json:"-"`
}

Benchmark represents a benchmark tracked by BenchGecko.

type Client

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

Client is the BenchGecko API client.

func NewClient

func NewClient(opts *ClientOptions) *Client

NewClient creates a new BenchGecko API client. Pass nil for default options.

func (*Client) Benchmarks

func (c *Client) Benchmarks() ([]Benchmark, error)

Benchmarks returns all benchmarks tracked by BenchGecko.

func (*Client) Compare

func (c *Client) Compare(models []string) (*ComparisonResult, error)

Compare compares two or more AI models side by side. Pass at least 2 model slugs.

func (*Client) Models

func (c *Client) Models() ([]Model, error)

Models returns all AI models tracked by BenchGecko.

type ClientOptions

type ClientOptions struct {
	// BaseURL overrides the default API URL. Leave empty for production.
	BaseURL string
	// Timeout sets the HTTP request timeout. Defaults to 30 seconds.
	Timeout time.Duration
	// HTTPClient allows providing a custom http.Client.
	HTTPClient *http.Client
}

ClientOptions configures the BenchGecko client.

type ComparisonResult

type ComparisonResult struct {
	Models []json.RawMessage      `json:"models,omitempty"`
	Extra  map[string]interface{} `json:"-"`
}

ComparisonResult holds the result of comparing two or more models.

type Error

type Error struct {
	StatusCode int
	Message    string
}

Error represents an API error from BenchGecko.

func (*Error) Error

func (e *Error) Error() string

type Model

type Model struct {
	ID       string                 `json:"id,omitempty"`
	Name     string                 `json:"name,omitempty"`
	Slug     string                 `json:"slug,omitempty"`
	Provider string                 `json:"provider,omitempty"`
	Extra    map[string]interface{} `json:"-"`
}

Model represents an AI model tracked by BenchGecko.