SDKs

Use the official SDKs when you want a client layer, not raw HTTP glue.

NFLMeta now has official SDKs for TypeScript/JavaScript and Python. This page covers package names, when to use each client, what they wrap, and where the low-level escape hatches still matter.

Docs Overview Search Docs OpenAPI FAQ

SDK Overview

Two official clients, one API contract

The SDK layer exists to shorten integration time, not to invent a second product model. Use the SDK when you want stable auth wiring, typed errors, parsed rate-limit headers, and resource methods that track the public API shape closely.

Official SDK

TypeScript / JavaScript

The first SDK is the TypeScript client for the Node and JavaScript audience. It uses fetch, exposes typed resource clients, and is intended for the @nfldb/sdk package name.

Official SDK

Python

The Python client mirrors the same resource families with a thin synchronous urllib transport and is intended for the nfldb package name.

Current Status

Source of truth lives in-repo today

The current SDK implementations live in the main codebase under sdk/typescript and sdk/python. Registry publishing can follow without changing the documented package names or client model.

Design Rule

The SDK does not replace the API contract

Both clients keep the same data/meta envelope, the same auth header, and a raw get escape hatch so new routes never wait on wrapper helpers.

Package Names

Use the official names consistently

These are the package names to document and integrate against as the SDK surface stabilizes.

TypeScript / JavaScript

@nfldb/sdk

Python

nfldb

If you are working from the source tree before registry publication, the current implementations live in the main repo under sdk/typescript and sdk/python.

When To Use Them

Choose by runtime, not by feature set

Choose the TypeScript client for Next.js apps, Node services, scripts, and modern JavaScript tooling.
Choose the Python client for notebooks, ETL scripts, internal tooling, and research workflows.
Stay on raw HTTP only when you are in another language or intentionally avoiding a client dependency.
Use the same API key model either way: X-NFLMeta-Key on every protected request.

@nfldb/sdk

TypeScript / JavaScript client

Use the TypeScript SDK when your app already runs in Node or modern JavaScript and you want typed resource clients instead of hand-built fetch calls.

Example

import { NFLDBClient, NFLDBNotFoundError } from "@nfldb/sdk";

const client = new NFLDBClient({
  apiKey: process.env.NFLDB_API_KEY,
  timeoutMs: 10_000,
});

try {
  const team = await client.teams.get("PIT", { season: 2025 });
  const usage = await client.usage.get();

  console.log(team.data.displayName);
  console.log(usage.rateLimit.remaining);
} catch (error) {
  if (error instanceof NFLDBNotFoundError) {
    console.error(error.message);
  }
}

nfldb

Python client

Use the Python SDK for scripts, notebooks, internal tools, and research workflows that want a thin synchronous client with the same resource model.

Example

from nfldb import NFLDBClient, NFLDBNotFoundError

client = NFLDBClient(
    api_key="YOUR_KEY",
    timeout=10.0,
)

try:
    team = client.teams.get("PIT", season=2025)
    usage = client.usage.get()

    print(team.data["displayName"])
    print(usage.rate_limit.remaining)
except NFLDBNotFoundError as error:
    print(error)

Both SDKs

Raw escape hatch

Keep using the SDK even when a new route ships before a dedicated wrapper method. The low-level get method preserves auth, rate-limit parsing, and the standard response envelope.

Example

// TypeScript
const raw = await client.get("/api/v1/reference/team-colors", {
  query: { limit: 10 },
});

# Python
raw = client.get("/api/v1/reference/team-colors", query={"limit": 10})

What They Handle

Common client plumbing is already built in

Automatic X-NFLMeta-Key header support
Typed 400, 401, 404, 429, and timeout errors
Parsed X-RateLimit-* headers on responses
Configurable base URL, timeout, and default headers
Transport injection for tests or custom HTTP infrastructure

Coverage

Use the SDK for the common public resource families

The wrappers already cover the main public surfaces developers are likely to reach for first. For exact route-level coverage, filters, and identifier rules, keep Core Endpoints, Reference Data, and Finding Identifiers as the source of truth.

Important Constraint

The SDK still follows the API docs

Wrapper methods help with path construction and error handling, but the source of truth for identifiers, filters, and route behavior is still the API contract. Use Finding Identifiers, Core Endpoints, and Reference Data when you need to reason about coverage.

Need Another Language?

SDK coverage can expand without changing the API path

If you need another official client, the API contract stays the same. Start from the current docs and post the language request on the request board.