API FAQ

NFLMeta is built for hobbyists, independent developers, researchers, newsletter writers, small media projects, and small businesses that want clean historical NFL data without enterprise contracts.

• Fan sites, stat explorers, and football research tools
• Developer projects, side projects, and internal dashboards
• Newsletters, podcasts, and small content businesses
• Apps that need structured historical games, seasons, standings, playoffs, and metadata

NFLMeta is not positioned as an enterprise live-data vendor for sportsbooks or major broadcast partners. The focus is historical depth, clean structure, and practical developer access.

1. Create an account at /register.
2. Verify your sign-in and open Customer Portal to get your free API key.
3. Review onboarding and auth details at /api-docs, then call endpoints under /api/v1.

1. Copy your API key from Customer Portal.
2. Open /api-docs and use the beginner quick-start and copy-paste examples.
3. Start with one object endpoint such as /api/v1/teams/NE or /api/v1/coaches/mike-vrabel.
4. If you only need one value, switch to a field drilldown such as /api/v1/season/2024/champion_team_abbr.
5. Move to raw /reference endpoints only when you intentionally want database-shaped rows.

1. Use a list or search endpoint first, such as /api/v1/teams?q=ravens, /api/v1/games?season=2024&team=PIT, /api/v1/players?q=lamar, /api/v1/coaches?q=tomlin, /api/v1/staff?search=cignetti, /api/v1/contributors?search=nunn, /api/v1/executives?search=kraft, /api/v1/reference/officials?q=blakeman, or /api/v1/reference/venues?q=arrowhead.
2. Find the matching row in the response.
3. Copy the returned canonical identifier such as abbr, id, player_key, coach_key, staff_key, contributor_key, executive_key, official_key, venue_key, or year.
4. Use that identifier with the single-record route and any related subroutes. Season routes and Hall of Fame election routes use the year directly, and playoff routes use the playoff game id returned by postseason summary endpoints.

Use versioned endpoints under /api/v1/*. The schema contract is published at /openapi.yaml.

Coverage includes games, seasons, standings, playoffs, Super Bowls, players, coaches, current staff, contributors, executives, Hall of Fame ballot history, team history, stadium and venue history, officials, branding history, season summaries, broadcast rights, power rankings, and Pro Bowl or all-star datasets. You can browse the full surface in API Docs.

Yes. Sign in to create your account, and NFLMeta will automatically create one free API key after your first verified login.

NFLMeta account access runs through Clerk-hosted sign-in, with email and Google available from the standard sign-in page.

Pass your key in request headers: X-NFLMeta-Key: <YOUR_KEY>.

• Store API keys server-side only.
• Never ship keys in browser/mobile client bundles.
• Rotate or replace keys when team access changes.

The API returns 401 unauthorized with a structured error payload.

Yes. Plans range from Free to Team. See Pricing for tier details.

Limits work on two layers: a monthly quota that resets at the start of each UTC month, and a per-minute rate limit that prevents burst abuse. Both are plan-based.

Responses include per-minute headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Policy. Monthly quota headers are also returned: X-Monthly-Quota-Limit, X-Monthly-Quota-Remaining, X-Monthly-Quota-Reset, and X-Monthly-Quota-Policy.

• Free: 20 requests per minute
• Builder: 120 requests per minute
• Pro: 500 requests per minute
• Team: 1,500 requests per minute

The API returns 429 rate_limit_exceeded when a key exceeds either the per-minute rate limit or the monthly quota. Free keys stop at quota. Paid subscriptions are handled through Stripe, and plan changes sync back into the same NFLMeta API key automatically.

Yes. You can change plans from Customer Portal through Stripe Billing without changing how your app integrates with the API.

NFLMeta uses Stripe for paid subscriptions, renewals, cancellations, payment methods, and plan changes. Clerk is used for account authentication only. Your API key stays the same when your subscription changes.

The current first-wave checkout supports cards, Link, Apple Pay, and Google Pay when Stripe determines they are available for the customer's device, browser, and region.

Signed-in customers can open Customer Portal Billing to view plan status, billing cycle details, and launch the Stripe Billing Portal for plan changes, cancellations, and payment-method updates.

Yes. Signed-in users can delete their account from the Account page under the Delete Account tab. Deletion disables the active API key and removes the associated Clerk account.

Yes. NFLMeta now has official SDKs for TypeScript/JavaScript and Python. The documented package names are @nfldb/sdk and nfldb, and the SDK-specific docs live at /api-docs/sdk.

No. The SDKs are optional. You can always call /api/v1/* directly with raw HTTP, but the SDKs save time on auth headers, path construction, typed errors, and rate-limit parsing when you are in a supported language. Use the TypeScript SDK for Node, Next.js, and JavaScript projects, and the Python SDK for scripts, notebooks, ETL, and research workflows.

Yes. The canonical spec is available at /openapi.yaml and rendered at /api-docs.

Public data coverage is broad and now includes both curated endpoints and raw table-shaped exports across players, teams, seasons, games, playoffs, coaches, contributors, executives, Hall of Fame ballots, officials, venues, stadiums, branding history, and Pro Bowl data. Many object-style resources now also expose direct field drilldowns, while internal operational tables like auth, billing, registrations, and refresh-state tables remain private.

Yes. Contributors and executives now expose list routes plus grouped identity, bio, history, and executive career drilldowns. Hall of Fame ballot history is exposed through /api/v1/hall-of-fame and election-year routes with the same field-drilldown pattern.

Stable routes are versioned under /api/v1. New capabilities are added without breaking the existing version contract.

Yes. Primary collection endpoints support query filters and paging controls where applicable. Confirm available parameters in API Docs.

No. New integrations should use the current versioned API under /api/v1/*.

Curated endpoints return joined, app-ready payloads for common product use cases. Raw endpoints return table-shaped exports that stay closer to the underlying database. API Docs labels these explicitly so you can choose the right surface quickly.

Yes. In addition to broader composite resources, NFLMeta now exposes narrower slices such as player identity, bio, ids, roster history, honors, kicking, and punting; coach identity, bio, career, and history; contributor identity, bio, and history; executive identity, bio, career, and history; team identity, season, stats, stadium, power ranking, and Pro Bowl slices; Hall of Fame election-year ballot drilldowns; plus season and game-detail field drilldowns. This is now the preferred integration model for object-shaped reads. Most object-shaped slices also support field-level drilldowns, such as /api/v1/players/{player_key}/identity/display_name, /api/v1/players/{player_key}/bio/birth_place, /api/v1/coaches/{coach_key}/career/regular_wins, /api/v1/contributors/{contributor_key}/bio/wikipedia_summary, /api/v1/executives/{executive_key}/career/years_total, /api/v1/hall-of-fame/{election_year}/inductee_count, /api/v1/teams/{abbr}/identity/city, and /api/v1/games/{id}/stadium, /api/v1/playoff-games/{id}/round, /api/v1/season/{year}/winner, /api/v1/reference/venues/{venue_key}/venue_name, and /api/v1/teams/{abbr}/season/record. Array endpoints like roster history and game logs stay list-oriented. Player stat leaderboards are also available as stat-specific routes like /api/v1/stats/players/careers/{stat} and /api/v1/stats/players/seasons/{season_year}/{stat}.

Prefer the smallest object-shaped endpoint that satisfies the use case: start with a focused slice such as identity, bio, career, season, stadium, or profile, then use a /{field} drilldown when you only need one field. Use broader composite endpoints when you intentionally want richer joined payloads, and use /api/v1/reference/* when you want raw table-shaped exports.

Endpoints under /api/v1/reference/* are the fastest way to pull raw rows for teams, seasons, coaches, officials, venues, stadiums, branding history, season records, power rankings, and Pro Bowl data. They are best for research, exports, and internal ETL workflows, and key single-record reference routes now also support direct field drilldowns such as /api/v1/reference/officials/{official_key}/display_name and /api/v1/reference/venues/{venue_key}/city.

The player stat API now includes normalized career and season totals for core offense, defense, returns, specialist stats, snap counts, advanced passing, advanced rushing, advanced receiving, advanced defense, explosive-play buckets, and kicking split fields. The quickest way to inspect the live stat allowlist is /api/v1/stats/players/catalog, which reflects the current queryable fields exposed by /api/v1/stats/players/seasons and /api/v1/stats/players/careers.

Yes. Use /api/v1/players/{player_key}/kicking and /api/v1/players/{player_key}/punting for season rows, then switch to /api/v1/players/{player_key}/kicking/{season_year}, /api/v1/players/{player_key}/punting/{season_year}, or their /{field} drilldowns when you only need one season or one specialist stat like fgm_total or net_avg. Initial staged source coverage is 2025 regular season.

Use /api/v1/games/{id}/stats for the raw stat tables for one regular-season game and /api/v1/playoff-games/{id}/supplemental for field-complete playoff sub-tables. Use the corresponding /extras endpoints when you want lighter, joined payloads instead.

Yes. Use /api/v1/players and /api/v1/players/{player_key} for player records,/api/v1/players/{player_key}/history for player history tables like roster and honors coverage, and /api/v1/players/{player_key}/games for granular game logs such as passing yards, touchdowns, and interceptions by week. Coach history is also available through /api/v1/coaches/{coach_key}/history.

NFLMeta has a public request board at /requests where users can request new features, stats, data additions, and API endpoints. The goal is to keep the roadmap tied to real demand, not guesswork. Requests that clearly add value to the overall product are fair game for the main roadmap and will be implemented over time. Requests that receive at least 25 votes are treated as committed roadmap items, even if NFLMeta would not otherwise rank them as a high-priority addition.

If the work is too niche, too specialized, or mostly useful for one customer, it can still be built as paid custom work. Email [email protected] with the exact data, endpoint, export, or workflow you need, and NFLMeta can scope it separately without forcing that work into the shared public roadmap.

• Use server-side caching for frequently requested resources.
• Implement retry with backoff for transient failures.
• Monitor your quota headers and endpoint-level usage.

Yes. Visit Trust Center for security, reliability, and governance posture.

See Terms of Service and Privacy.

Email [email protected] or use the Contact page.