NAICS Search

Status: stable Category: lookup Added: 2026-04-27 Last reviewed: 2026-10-14

Summary

Type-ahead search across BLS industry safety benchmarks. Pass a short fragment of either the industry name or a numeric NAICS prefix and get back the matching codes ranked closest first. Designed to power UI autocomplete; safe to call on every keystroke once q is at least two characters.

The dataset is the BLS Survey of Occupational Injuries and Illnesses, reseeded annually. Lookups always read the latest published year for each (code, ownership) pair. Like every lookup resource, each hit carries code and label, so one picker component works against every lookup endpoint.

Endpoint

Field	Value
Method	`GET`
Path	`/api/lookup/naics/search`
Full URL	`https://engine.tripod-health.com/api/lookup/naics/search`
Authentication	API key (required)
Request body	none
Response body	`application/json`
Idempotent	Yes
Rate-limited	Yes

Authentication

Send a valid API key in the apikey header. See authentication.md.

Request

Headers

Header	Required	Description
`apikey`	Yes	Consumer API key.

Path parameters

None.

Query parameters

Parameter	Type	Required	Default	Description
`q`	`string`	Yes	—	Search fragment. Minimum two characters. An all-digit value matches as a NAICS code prefix; anything else matches as a case-insensitive substring of the industry name.
`ownership`	`string`	No	`private`	One of `private`, `state_government`, `local_government`. Picks the BLS ownership cohort.
`limit`	`int`	No	`10`	Maximum results to return. Range `1`–`50`.

Body

None.

Response

Success — `200 OK`

The response to GET /api/lookup/naics/search?q=construction&limit=5:

{
  "results": [
    {
      "code": "23",
      "label": "Construction",
      "ownership": "private",
      "total_recordable_rate": 2.2
    },
    {
      "code": "236",
      "label": "Construction of buildings",
      "ownership": "private",
      "total_recordable_rate": 2.2
    },
    {
      "code": "237",
      "label": "Heavy and civil engineering construction",
      "ownership": "private",
      "total_recordable_rate": 1.8
    },
    {
      "code": "2361",
      "label": "Residential building construction",
      "ownership": "private",
      "total_recordable_rate": 2.5
    },
    {
      "code": "2362",
      "label": "Nonresidential building construction",
      "ownership": "private",
      "total_recordable_rate": 1.9
    }
  ],
  "request_id": "f1b3fca4-4613-47cc-8357-394982cb9d74",
  "timestamp": "2026-10-14T00:16:15.127Z"
}

results is always present. An empty array is a normal response (the query matched nothing in the requested ownership cohort), not an error.

Response fields

Field	Type	Always present	Description
`results`	`array`	Yes	Zero or more match objects, ordered by code length (shortest first), then by code.
`results[].code`	`string`	Yes	NAICS code, 2–6 digits. Treat as opaque text rather than parsing as a number. Pass it to `/api/lookup/naics/get` `?code=` for the full benchmark row.
`results[].label`	`string`	Yes	Industry name as published by BLS.
`results[].ownership`	`string`	Yes	Echoes the `?ownership=` value.
`results[].total_recordable_rate`	`number \| null`	Yes	Total recordable case rate per 100 FTE. `null` when BLS suppressed the cell for sample-size reasons.
`request_id`	`string`	Yes	Correlation ID. Quote in support tickets.
`timestamp`	`string` (ISO 8601 UTC)	Yes	Server time when the response was emitted.

Status codes

Code	Meaning	When
`200`	OK	Search ran. `results` may be empty.
`400`	`ValidationError`	`q` missing or shorter than two characters, `ownership` not in the allowed set, or `limit` out of range. `field` names the offending parameter.
`401`	`Unauthenticated`	Missing or invalid API key.
`429`	`RateLimited`	Per-consumer rate limit exceeded.
`500`	`InternalError`	Unexpected failure. Quote `request_id` in the ticket.

Examples

curl

curl -sS "https://engine.tripod-health.com/api/lookup/naics/search?q=construction&limit=5" \
  -H "apikey: $ENGINE_API_KEY"

Returns the 200 body shown in Success above.

Numeric prefix

curl -sS "https://engine.tripod-health.com/api/lookup/naics/search?q=236" \
  -H "apikey: $ENGINE_API_KEY"

Python (`requests`)

# Uses the call() helper from quickstart.md.
result = call("GET", "/api/lookup/naics/search?q=hospital&limit=5")
for row in result["results"]:
    print(f"{row['code']:6}  {row['label']:60}  TRR={row['total_recordable_rate']}")

Node.js (native `fetch`)

// Uses the call() helper from quickstart.md.
const result = await call("GET", "/api/lookup/naics/search?q=hospital&limit=5");
for (const row of result.results) {
  console.log(`${row.code.padEnd(6)}  ${row.label}  TRR=${row.total_recordable_rate}`);
}

TypeScript

interface NaicsSearchResult {
  code: string;
  label: string;
  ownership: "private" | "state_government" | "local_government";
  total_recordable_rate: number | null;
}

interface NaicsSearchResponse {
  results: NaicsSearchResult[];
  request_id: string;
  timestamp: string;
}

const result = await call<NaicsSearchResponse>(
  "GET",
  "/api/lookup/naics/search?q=construction",
);

Error scenarios

`q` too short

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/naics/search?q=h" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (400):

{
  "timestamp": "2026-10-14T00:16:15.411Z",
  "error": "ValidationError",
  "message": "Query parameter 'q' must be at least 2 characters",
  "field": "q",
  "request_id": "d943a85a-de9d-4dcb-8153-0d9e7520fbe7"
}

Invalid ownership

Send:

curl -sS "https://engine.tripod-health.com/api/lookup/naics/search?q=hospital&ownership=federal" \
  -H "apikey: $ENGINE_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Receive (400):

{
  "timestamp": "2026-10-14T00:16:15.718Z",
  "error": "ValidationError",
  "message": "Query parameter 'ownership' must be one of private, state_government, local_government",
  "field": "ownership",
  "request_id": "34c37b2f-af69-4306-bea2-4354d19a6ee2"
}

Intended use

Autocomplete UIs that let an employer find their industry by typing a few letters or digits.
Onboarding flows where the user has a NAICS code from another system and wants to confirm it lines up with the published industry name before submitting a calculation.
Building lookup tables when you need to display the industry name alongside a NAICS code your application stores.
One picker for every lookup resource. Each hit carries code and label, the same pair the ICD-10-CM, CPT, regulations, and fee schedule searches return.

Mistaken use

Do not call search to fetch a single known code. Use /api/lookup/naics/get — one record, full benchmark fields, no ranking layer.
Do not interpret an empty results array as a failure. It means the query matched nothing in the requested ownership cohort. Try a shorter fragment or a different ?ownership=.
Do not pass a NAICS code to q and expect it to behave like get. Search returns multiple rows — for example q=23 matches every code beginning with 23. To resolve a single record, call /api/lookup/naics/get?code=23.

Debugging

Capture request_id from the response body (or, if the response has no body from the engine, the X-Request-ID response header).
Empty results for a search you expected to match. Double-check ?ownership= — most BLS data ships only under private, and a request for state_government or local_government will be empty for industries the BLS does not publish under that cohort.
400 ValidationError with field: "q". The fragment was shorter than two characters. UI clients should not send the request until the user has typed at least two characters.
null rate values in results. BLS suppresses cells when the survey sample is too small to publish a stable estimate. This is expected, especially on narrow 5- and 6-digit codes.

Rate limits

See rate-limits.md for the current per-consumer limits.

lookup-naics-get.md — single-record lookup once the user has chosen a code.
lookup-naics-calculate.md — compute employer rates and compare against the benchmark.
lookup-regulations-search.md, lookup-icd10cm-search.md, lookup-cpt-search.md, lookup-fee_schedule-search.md — the other lookup searches, which share the same q, limit, code, and label rules.
authentication.md, errors.md, rate-limits.md, conventions.md — cross-cutting contract rules.

Change history

Date	Change
2026-04-27	Initial publication.
2026-10-14	Moved from `/api/naics/search` to `/api/lookup/naics/search`. Result fields `naics_code` and `industry_name` renamed to `code` and `label`. Examples recaptured.
2026-10-14	The `X-Request-ID` response header is the gateway's trace ID for the request and does not match `request_id`; quote `request_id` to support.

Summary​

Endpoint​

Authentication​

Request​

Headers​

Path parameters​

Query parameters​

Body​

Response​

Success — 200 OK​

Response fields​

Status codes​

Examples​

curl​

Numeric prefix​

Python (requests)​

Node.js (native fetch)​

TypeScript​

Error scenarios​

q too short​

Invalid ownership​

Intended use​

Mistaken use​

Debugging​

Rate limits​

Related​

Change history​