NBA

Fuzzy search NBA players by name

Trigram-similarity (pg_trgm) ranking over full_name. Returns up to limit players whose name has similarity > 0.2 to q, ordered by similarity DESC. Designed for autocomplete / type-ahead UIs where a substring or close-spelling match should outrank exact matches that come alphabetically later.

get/api/v1/nba/players/search

Request

  • Base URL: https://api.stat-api.com
  • URL: https://api.stat-api.com/api/v1/nba/players/search
  • Auth: HTTP bearer

Query parameters

qstring required

Search query — matches against full_name (case-insensitive).

limitinteger

Max results to return. Default 10; max 50.

Response

Fuzzy search NBA players by name

birth_citystring nullable

City of birth.

birth_countrystring nullable

Country of birth (ISO English name).

birth_datestring date nullable

Birth date in YYYY-MM-DD form.

birth_statestring nullable

State / province of birth (US/Canadian players).

display_fi_laststring nullable

Display name in "F. Last" form.

display_last_comma_firststring nullable

Display name in "Last, First" form. Useful for sorted lists.

dleague_flagstring nullable

Two-character bit-string from the league: "00" no G-League history, "01" G-League experience, "11" currently G-League-affiliated (two-way / assignment).

draft_numberstring nullable

Overall pick number within the draft (string). Empty for undrafted.

draft_roundstring nullable

Draft round (string). Empty for undrafted players.

draft_yearstring nullable

Year the player was drafted (string form). Empty for undrafted players.

experienceinteger nullable

Years of NBA experience as of the most recent season. Rookies = 0.

first_namestring required

Player's legal first name as registered with the league.

from_yearstring nullable

Player's NBA debut year as a string (as the league records it).

full_namestring required

Convenience concatenation of first_name + last_name. Use this for display.

full_position_liststring nullable

Hyphenated full-word position list (e.g., "Guard-Forward", "Center-Forward").

games_played_flagstring nullable

String "Y"/"N" indicating whether the player has played at least one regular-season game.

heightinteger nullable

Height in inches.

idinteger required

Primary Key

injury_body_partstring nullable

Affected body part for the most recent injury (e.g., "Knee", "Ankle"). Null when injury_status is null.

injury_detailstring nullable

Free-text injury description from the source feed.

injury_sincestring date-time nullable

Timestamp of the injury status snapshot. Updated when player_news produces a new injury entry.

injury_statusstring nullable

Current injury status snapshot derived from player_news. Values: "OUT", "QUESTIONABLE"; null = no active injury designation (healthy).

jerseystring nullable

Current jersey number as a string (some leagues allow leading zeros, e.g., "00").

last_affiliationstring nullable

Most recent pre-NBA affiliation (school, league, or team).

last_namestring required

Player's legal last name.

league_player_idinteger required

Official NBA player ID (issued by the league). Stable across seasons; use it to join other data that carries the league id.

league_slugstring nullable

NBA-issued URL slug of the player (as in the league player page).

nba_flagstring nullable

String "Y"/"N" indicating NBA experience. Almost always "Y" in this table.

playercodestring nullable

NBA-issued player code (lastname_firstname format).

position_categorystring nullable

Coarse positional grouping. One of Guard, Forward, Center, Utility.

primary_positionstring required

Primary position. One of G, F, C, G-F, F-C. (True PG/SG/SF/PF splits live in team_depth_charts.position.)

roster_statusstring nullable

Canonical roster status, shared across leagues. NBA source granularity is coarse: "active" (on an NBA roster), "free_agent" (no team), "inactive" (not currently rostered); injured_reserve/retired appear where derivable. The "on a team now" set is {active, injured_reserve}.

schoolstring nullable

Last school attended before the NBA (college, prep, or international club).

team_abbreviationstring nullable

Current team's tri-letter code.

team_citystring nullable

Current team's city name.

team_codestring nullable

Current team's lowercase URL slug.

team_idinteger nullable

FK to nba.teams. Null for free agents and retired players.

team_namestring nullable

Current team's mascot name (denormalized from teams.name for read convenience).

to_yearstring nullable

Player's most recent NBA season year. Equal to from_year for rookies.

weightinteger nullable

Listed weight in pounds.

Example response

[
  {
    "birth_city": "Sombor",
    "birth_country": "Serbia",
    "birth_date": "1995-02-19",
    "display_fi_last": "N. Jokić",
    "display_last_comma_first": "Jokić, Nikola",
    "dleague_flag": "00",
    "draft_number": "41",
    "draft_round": "2",
    "draft_year": "2014",
    "experience": 10,
    "first_name": "Nikola",
    "from_year": "2015",
    "full_name": "Nikola Jokić",
    "full_position_list": "Guard-Forward",
    "games_played_flag": "Y",
    "height": 83,
    "injury_since": "2026-04-12T18:30:00Z",
    "injury_status": "OUT",
    "jersey": "15",
    "last_affiliation": "Mega Basket / Serbia",
    "last_name": "Jokić",
    "league_player_id": 203999,
    "league_slug": "nikola-jokic",
    "nba_flag": "Y",
    "playercode": "jokic_nikola",
    "position_category": "Center",
    "primary_position": "C",
    "roster_status": "active",
    "school": "Mega Basket",
    "team_abbreviation": "DEN",
    "team_city": "Denver",
    "team_code": "nuggets",
    "team_id": 12,
    "team_name": "Nuggets",
    "to_year": "2025",
    "weight": 284
  }
]

Changes

No recorded changes to this operation across all 4 revisions of this API.