---
title: "Fuzzy search NBA players by name"
method: GET
path: "/api/v1/nba/players/search"
tags: ["NBA"]
---

# Fuzzy search NBA players by name

`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

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.

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

Fuzzy search NBA players by name

- NBAPlayers[]
  - `birth_city` string, nullable: City of birth.
  - `birth_country` string, nullable: Country of birth (ISO English name).
  - `birth_date` string, date, nullable: Birth date in YYYY-MM-DD form.
  - `birth_state` string, nullable: State / province of birth (US/Canadian players).
  - `display_fi_last` string, nullable: Display name in "F. Last" form.
  - `display_last_comma_first` string, nullable: Display name in "Last, First" form. Useful for sorted lists.
  - `dleague_flag` string, 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_number` string, nullable: Overall pick number within the draft (string). Empty for undrafted.
  - `draft_round` string, nullable: Draft round (string). Empty for undrafted players.
  - `draft_year` string, nullable: Year the player was drafted (string form). Empty for undrafted players.
  - `experience` integer, nullable: Years of NBA experience as of the most recent season. Rookies = 0.
  - `first_name` string, required: Player's legal first name as registered with the league.
  - `from_year` string, nullable: Player's NBA debut year as a string (as the league records it).
  - `full_name` string, required: Convenience concatenation of first_name + last_name. Use this for display.
  - `full_position_list` string, nullable: Hyphenated full-word position list (e.g., "Guard-Forward", "Center-Forward").
  - `games_played_flag` string, nullable: String "Y"/"N" indicating whether the player has played at least one regular-season game.
  - `height` integer, nullable: Height in inches.
  - `id` integer, required: Primary Key
  - `injury_body_part` string, nullable: Affected body part for the most recent injury (e.g., "Knee", "Ankle"). Null when injury_status is null.
  - `injury_detail` string, nullable: Free-text injury description from the source feed.
  - `injury_since` string, date-time, nullable: Timestamp of the injury status snapshot. Updated when player_news produces a new injury entry.
  - `injury_status` string, nullable: Current injury status snapshot derived from player_news. Values: "OUT", "QUESTIONABLE"; null = no active injury designation (healthy).
  - `jersey` string, nullable: Current jersey number as a string (some leagues allow leading zeros, e.g., "00").
  - `last_affiliation` string, nullable: Most recent pre-NBA affiliation (school, league, or team).
  - `last_name` string, required: Player's legal last name.
  - `league_player_id` integer, required: Official NBA player ID (issued by the league). Stable across seasons; use it to join other data that carries the league id.
  - `league_slug` string, nullable: NBA-issued URL slug of the player (as in the league player page).
  - `nba_flag` string, nullable: String "Y"/"N" indicating NBA experience. Almost always "Y" in this table.
  - `playercode` string, nullable: NBA-issued player code (lastname_firstname format).
  - `position_category` string, nullable: Coarse positional grouping. One of Guard, Forward, Center, Utility.
  - `primary_position` string, 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_status` string, 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}.
  - `school` string, nullable: Last school attended before the NBA (college, prep, or international club).
  - `team_abbreviation` string, nullable: Current team's tri-letter code.
  - `team_city` string, nullable: Current team's city name.
  - `team_code` string, nullable: Current team's lowercase URL slug.
  - `team_id` integer, nullable: FK to nba.teams. Null for free agents and retired players.
  - `team_name` string, nullable: Current team's mascot name (denormalized from teams.name for read convenience).
  - `to_year` string, nullable: Player's most recent NBA season year. Equal to from_year for rookies.
  - `weight` integer, nullable: Listed weight in pounds.

## Other responses

- `400`: q is empty or exceeds 100 chars
- `503`: pg_trgm extension unavailable on the DB

---

[API](https://skmtc.dev/stat-api/apis/sports-db-public-api.md) · [All operations](https://skmtc.dev/stat-api/apis/sports-db-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stat-api/apis/sports-db-public-api/revisions/601ff9eaca3f?raw)