Java SDK

Install

git clone https://github.com/stat-api/stat-api

A published package is coming; for now install from source or JitPack.

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 com.statapi.cookbook;

import com.statapi.StatApi;
import com.statapi.nba.*;
import java.util.*;

public final class NbaHelloStatApi {
    public static void main(String[] args) {
        StatApi api = new StatApi(); // reads STAT_API_KEY from the environment

        // List a few teams
        List<NBATeam> teams = api.nba().teams().list(new NBATeamsListParams().limit(3L)).rows();

        // Print what came back
        System.out.println(teams);

    }
}

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 StatApi 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, iterate(), 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 Java call, and the examples walk through longer recipes.