Go SDK

Install

go get github.com/stat-api/stat-api/go@latest

Quickstart

The smallest end-to-end program: construct a client, list a few rows, and print them.

// Hello, NBA
// Generated from schema/api/examples/hello-stat-api.yml — do not edit.
package main

import (
	"context"
	"encoding/json"
	"fmt"
	statapi "github.com/stat-api/stat-api/go"
	"log"
)

func main() {
	client, err := statapi.New()
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	// List a few teams
	teamsPage, err := client.NBA.Teams.List(ctx, &statapi.NBATeamsListParams{Limit: statapi.Int(3)})
	if err != nil {
		log.Fatal(err)
	}
	teams := teamsPage.Rows

	// Print what came back
	teamsJSON, err := json.MarshalIndent(teams, "", "  ")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(teamsJSON))

}

Authentication

The client reads your API key from the STAT_API_KEY environment variable — the zero-argument constructor above needs nothing else. To pass it explicitly, hand the key to the Client constructor. The base URL defaults to https://api.stat-api.com. Get a key on the pricing page — the free tier covers 50,000 records a month.

Pagination & iteration

Every list call returns one bounded page (default 50 rows, max 200) wrapped in the list envelope, plus a next_from_id keyset cursor. Pass it back as from_id to fetch the next page, or let the built-in auto-paging iterator, All(), stream every row across pages for you — available on every table.

Errors

Failed requests raise a typed error rather than returning a status code: AuthenticationError (401), PlanRequiredError (402), QuotaExceededError (429), NotFoundError (404), and ValidationError (400, e.g. a missing required filter) — all subclasses of StatApiError. GET requests are retried automatically on transient network errors and 5xx responses; quota exhaustion (429) is never retried.

Quota

Every response reports your monthly usage through X-Quota-* headers, surfaced on each page (and on QuotaExceededError) as a Quota value with limit, used, and remaining record counts — the same metering as the REST API.

More

Every endpoint in the API reference carries a copy-pasteable Go call, and the examples walk through longer recipes.