{"id":47793246,"url":"https://github.com/zcaceres/naics-api","last_synced_at":"2026-04-03T15:56:20.587Z","repository":{"id":338159776,"uuid":"1156732500","full_name":"zcaceres/naics-api","owner":"zcaceres","description":"Free API for NAICS codes (2022, 2017, 2012) with full-text search, hierarchy traversal, and cross-references","archived":false,"fork":false,"pushed_at":"2026-03-07T20:35:45.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-08T00:54:36.128Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zcaceres.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T01:39:23.000Z","updated_at":"2026-03-07T20:35:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zcaceres/naics-api","commit_stats":null,"previous_names":["zcaceres/naics-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zcaceres/naics-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Fnaics-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Fnaics-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Fnaics-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Fnaics-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zcaceres","download_url":"https://codeload.github.com/zcaceres/naics-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Fnaics-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31362036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T15:19:21.178Z","status":"ssl_error","status_checked_at":"2026-04-03T15:19:20.670Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T15:56:20.053Z","updated_at":"2026-04-03T15:56:20.569Z","avatar_url":"https://github.com/zcaceres.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAICS Code API\n\nFree, self-hosted REST API for NAICS (North American Industry Classification System) codes. Supports **2022**, **2017**, and **2012** revisions. Built with [Bun](https://bun.sh) and SQLite.\n\nData sourced from the [U.S. Census Bureau](https://www.census.gov/naics/).\n\n## Prerequisites\n\n- [Bun](https://bun.sh) v1.0+\n\n## Quick Start\n\n```bash\nbun install\nbun run build-db    # downloads Census XLSX files and builds SQLite databases (all years)\nbun run dev         # starts server with hot reload on http://localhost:3456\n```\n\nTo build a single year:\n\n```bash\nbun run build-db:2022   # only 2022\nbun run build-db:2017   # only 2017\nbun run build-db:2012   # only 2012\n```\n\n## Scripts\n\n| Script | Command | Description |\n|--------|---------|-------------|\n| `bun run dev` | `bun --hot src/index.ts` | Start dev server with hot reload |\n| `bun run start` | `bun src/index.ts` | Start production server |\n| `bun run build-db` | `bun scripts/build-db.ts` | Download Census data and build all year DBs |\n| `bun run build-db:2022` | `bun scripts/build-db.ts 2022` | Build 2022 database only |\n| `bun run build-db:2017` | `bun scripts/build-db.ts 2017` | Build 2017 database only |\n| `bun run build-db:2012` | `bun scripts/build-db.ts 2012` | Build 2012 database only |\n| `bun test` | | Run all tests |\n\n## Database Setup\n\nThe databases are not checked into the repo. Run `bun run build-db` to create them. This will, for each year:\n\n1. Download 4 XLSX files from Census.gov into `data/xlsx/{year}/`\n2. Parse codes, descriptions, index entries, and cross-references\n3. Build `data/naics-{year}.db` with FTS5 full-text search index\n\nThe download is cached — re-running skips files already in `data/xlsx/`.\n\n## Multi-Year Support\n\nAll endpoints accept an optional year prefix: `/api/{year}/...`. Unprefixed routes default to **2022**.\n\nSupported years: `2022`, `2017`, `2012`\n\n```bash\n# Default (2022)\ncurl http://localhost:3456/api/naics/722511\n\n# Explicit 2022\ncurl http://localhost:3456/api/2022/naics/722511\n\n# 2017 revision\ncurl http://localhost:3456/api/2017/naics/722511\n\n# 2012 revision\ncurl http://localhost:3456/api/2012/sectors\n```\n\n## API Endpoints\n\nAll endpoints below are shown without year prefix. Prepend `/api/{year}` for a specific revision (e.g. `/api/2017/sectors`).\n\n### Codes\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/sectors` | List all 20 top-level NAICS sectors |\n| `GET /api/naics/:code` | Look up a specific NAICS code |\n| `GET /api/naics?codes=:code1,:code2,...` | Batch lookup (max 50, returns in request order) |\n\n### Hierarchy\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/naics/:code/children` | Direct children of a code |\n| `GET /api/naics/:code/ancestors` | Full ancestor chain up to sector |\n| `GET /api/naics/:code/descendants?limit=100\u0026offset=0` | All codes below (paginated, max 500, integer params only) |\n\n### Search\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/search?q=:query\u0026limit=20\u0026offset=0\u0026level=:level` | Full-text search with BM25 ranking (max 100, integer pagination params, optional level filter 2-6) |\n\n### Related Data\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/naics/:code/cross-references` | Cross-references for a code |\n| `GET /api/naics/:code/index-entries` | Index entry keywords for a code |\n\n### Other\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/openapi.json` | OpenAPI 3.0 specification (same spec at all year prefixes — API shape is identical across years) |\n| `GET /` | API overview with all endpoints and examples |\n\n## Response Format\n\n**Success** responses return `{ data, meta? }`:\n\n```json\n{\n  \"data\": {\n    \"code\": \"722511\",\n    \"title\": \"Full-Service Restaurants\",\n    \"description\": \"...\",\n    \"level\": 6,\n    \"parent_code\": \"72251\"\n  }\n}\n```\n\nPaginated endpoints include `meta`:\n\n```json\n{\n  \"data\": [...],\n  \"meta\": { \"total\": 245, \"limit\": 20, \"offset\": 0 }\n}\n```\n\n**Error** responses return `{ error }` with appropriate HTTP status:\n\n```json\n{ \"error\": \"Code not found\" }\n```\n\n| Status | Meaning |\n|--------|---------|\n| 200 | Success |\n| 400 | Invalid input (bad code format, missing params, invalid search syntax) |\n| 404 | Code not found or unknown route |\n| 500 | Server error |\n\n## Search Syntax\n\nThe search endpoint uses SQLite FTS5 with Porter stemming. Queries support:\n\n- **Simple terms**: `restaurant` — matches stemmed variants (e.g. \"restaurants\")\n- **Phrases**: `\"full service\"` — matches exact phrase\n- **AND** (default): `restaurant bar` — both terms must appear\n- **OR**: `restaurant OR bar` — either term\n- **NOT**: `restaurant NOT bar` — exclude term\n- **Prefix**: `rest*` — prefix matching\n\n## Caching and CORS\n\n- **CORS** is enabled on all routes.\n- **Cache-Control** headers are set on all 200 responses: `public, max-age=86400, s-maxage=604800` (1 day browser, 7 days CDN). Error responses are not cached.\n\n## Examples\n\nSee [EXAMPLES.md](EXAMPLES.md) for detailed request/response examples with real data.\n\n```bash\n# Look up Full-Service Restaurants (default: 2022)\ncurl http://localhost:3456/api/naics/722511\n\n# Look up in 2017 revision\ncurl http://localhost:3456/api/2017/naics/722511\n\n# Get children of Accommodation and Food Services\ncurl http://localhost:3456/api/naics/72/children\n\n# Search for \"restaurant\"\ncurl \"http://localhost:3456/api/search?q=restaurant\"\n\n# Search 2012 data\ncurl \"http://localhost:3456/api/2012/search?q=restaurant\"\n\n# Search for 6-digit codes only\ncurl \"http://localhost:3456/api/search?q=restaurant\u0026level=6\"\n\n# Batch lookup\ncurl \"http://localhost:3456/api/naics?codes=722511,111110,541511\"\n\n# Range code descendants (Manufacturing)\ncurl \"http://localhost:3456/api/naics/31-33/descendants?limit=10\"\n```\n\n## Code Format\n\nNAICS codes are 2-6 digits representing hierarchy levels:\n\n| Digits | Level | Example |\n|--------|-------|---------|\n| 2 | Sector | `72` (Accommodation and Food Services) |\n| 3 | Subsector | `722` (Food Services and Drinking Places) |\n| 4 | Industry Group | `7225` (Restaurants and Other Eating Places) |\n| 5 | Industry | `72251` (Restaurants and Other Eating Places) |\n| 6 | National Industry | `722511` (Full-Service Restaurants) |\n\nSome sectors use range codes: `31-33` (Manufacturing), `44-45` (Retail Trade), `48-49` (Transportation and Warehousing).\n\n## Project Structure\n\n```\nsrc/\n  index.ts              Server entry point\n  db.ts                 Database factory (per-year connections)\n  types.ts              Shared types and year constants\n  params.ts             Request parsing and validation (pure)\n  transforms.ts         Data transformations (pure)\n  openapi.json          OpenAPI 3.0 spec\n  routes/\n    codes.ts            Code lookup and hierarchy routes\n    search.ts           Full-text search route\n    helpers.ts          Shared route utilities\nscripts/\n  build-db.ts           Census data downloader and DB builder (multi-year)\ntests/\n  params.test.ts        Param parsing tests\n  transforms.test.ts    Data transformation tests\n  routes.test.ts        Integration tests (default routes)\n  multi-year.test.ts    Multi-year route tests\ndata/\n  naics-2022.db         SQLite database for 2022 (generated)\n  naics-2017.db         SQLite database for 2017 (generated)\n  naics-2012.db         SQLite database for 2012 (generated)\n  xlsx/                 Census source files (downloaded, not in git)\n```\n\n## Backward Compatibility\n\nIf you previously used a single `data/naics.db` file (pre-multi-year), the server will automatically use it as the 2022 database when `data/naics-2022.db` doesn't exist. No migration needed.\n\n## License\n\nMIT. See [LICENSE](LICENSE). NAICS data is public domain, published by the U.S. Census Bureau.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzcaceres%2Fnaics-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzcaceres%2Fnaics-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzcaceres%2Fnaics-api/lists"}