nhl-api

name: nhl-api description: Use when answering questions about the NHL (National Hockey League) that need current or live data — player or goalie stats, team standings, today's scores, schedules, rosters, playoffs, or filtering/ranking players by nationality, team, position, or season. Covers the free no-auth public NHL APIs (api-web.nhle.com and api.nhle.com/stats/rest).

NHL API

Overview

The NHL exposes two free, no-auth, JSON public APIs (the same backend powering NHL.com). No API key, no User-Agent required (they return 200 to a plain client).

• Web API — https://api-web.nhle.com/v1/... — ready-to-read nested objects: scores, schedule, standings, player profiles (with last-5-games), rosters. /now paths 307-redirect to a dated URL → follow redirects (curl -L).
• Stats API — https://api.nhle.com/stats/rest/en/... — queryable stat tables (skater/goalie/team summary, season list) with a cayenneExp filter + sort. This is how you filter, rank, and aggregate (by nationality, team, season, position). Returns {"total":N,"data":[...]}.

Always pull live — do NOT answer NHL stat questions from training memory (it's stale). For deeper endpoint/field catalogs and more examples, read reference.md in this skill directory.

Quick reference

{TEAM} = 3-letter abbrev (TBL, BOS…). {id} = numeric player ID (from the search endpoint).

cayenneExp — the filter language

Stats endpoints take cayenneExp (SQL-like WHERE) + optional sort (JSON) + start/limit. Let curl encode it:

# All Latvian skaters, 2025-26 regular season, ranked by points
curl -sG https://api.nhle.com/stats/rest/en/skater/summary \
  --data-urlencode 'sort=[{"property":"points","direction":"DESC"}]' \
  --data-urlencode 'cayenneExp=seasonId=20252026 and gameTypeId=2 and nationalityCode="LVA"'

• seasonId — e.g. 20252026 (auto-detect via the season endpoint above).
• gameTypeId — 2 = regular season, 3 = playoffs.
• Filterable fields: nationalityCode, birthCountryCode, teamId, positionCode, seasonId, plus any numeric stat (points>=50).
• String values need double quotes inside the expression: nationalityCode="LVA".

Key gotchas

• savePct (stats API) ≠ savePctg (web API /landing). Same for GAA: goalsAgainstAverage (stats) vs goalsAgainstAvg (landing). Sorting/filtering on the wrong name → {"message":"Invalid report property"}.
• nationalityCode vs birthCountryCode — nationality = national-team eligibility; birthCountry = where born. Usually identical; differ for players born abroad. Choose deliberately ("Latvian players" → nationalityCode="LVA").
• /now endpoints 307-redirect to a dated path — always follow redirects.
• summary excludes 0-GP players — a rostered player who hasn't dressed won't appear; use the roster endpoint for full rosters.
• Off-season: score/now returns games:[]; the season endpoint can flip to the next (not-yet-started) season so summary returns total:0 until games begin — fall back to the previous seasonId if you need last season's numbers.
• gameState: FUT/PRE = upcoming, LIVE/CRIT = in progress, OFF/FINAL = final. Times are UTC (startTimeUTC).

Worked example

"How many points does Zemgus Girgensons have, and which Latvian goalie has the best save %?"

1. skater/summary?cayenneExp=seasonId=20252026 and gameTypeId=2 and nationalityCode="LVA" sorted by points → Girgensons 20 P (9G 11A, 74 GP).
2. goalie/summary?...nationalityCode="LVA" → sort by savePct (not savePctg) → Šilovs .888, ahead of Merzļikins .883.

Two filtered calls, no per-player lookups, no dead-ends.