{
  "openapi": "3.1.0",
  "info": {
    "title": "USA Business Search static data API",
    "version": "1.0.0",
    "description": "Read-only JSON files describing businesses listed on USA Business Search (usabusinesssearch.com) in California, Texas, Florida, New York, Colorado, Arizona, Nebraska, Georgia, Illinois, New Jersey and Missouri. Static files, no key needed. For people-facing pages use the HTML URLs built from each response. Independent directory, not affiliated with any government agency.",
    "contact": { "name": "USA Business Search", "url": "https://usabusinesssearch.com/contact/" }
  },
  "servers": [{ "url": "https://usabusinesssearch.com" }],
  "paths": {
    "/api/business.json": {
      "get": {
        "operationId": "getDirectorySummary",
        "summary": "Directory summary: states covered with business counts, URL patterns, guides and upgrade pricing.",
        "responses": { "200": { "description": "Summary object", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/data/cats.json": {
      "get": {
        "operationId": "listCategories",
        "summary": "All 111 categories with slug (s), name (n), group (g), national count (c) and search keywords (k).",
        "responses": { "200": { "description": "Array of categories", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } }
      }
    },
    "/data/cities.json": {
      "get": {
        "operationId": "listCities",
        "summary": "States and cities as arrays [path, name, stateCode, businessCount, hasCategoryPages]. State rows use stateCode '_state'. path is 'state' or 'state/city'.",
        "responses": { "200": { "description": "Array of city rows", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "array" } } } } } }
      }
    },
    "/data/k/{state}.json": {
      "get": {
        "operationId": "getCityCategoryIndex",
        "summary": "For one state: object keyed by city slug; value is a comma list 'category:pages'. pages = number of /{state}/{city}/{category}/ pages; 0 means the category is listed inline on the city page at #c-{category}. Small towns are not in this file; all their businesses are on /{state}/{city}/.",
        "parameters": [{ "name": "state", "in": "path", "required": true, "schema": { "type": "string", "example": "georgia" } }],
        "responses": { "200": { "description": "City -> category pages", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }
      }
    },
    "/data/n/_split.json": {
      "get": {
        "operationId": "getNameIndexSplits",
        "summary": "Which name-index prefixes are split into longer prefixes. Object keyed by prefix length (2..8) listing prefixes that continue to the next length. Start with the first 2 characters of the first significant word of a business name; while that prefix appears in the list for its length, add one more character.",
        "responses": { "200": { "description": "Split table", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/data/n/{prefix}.json": {
      "get": {
        "operationId": "findBusinessesByName",
        "summary": "Name index shard. Rows are [name, cityPath, categorySlug, id, page, flags, where?]. Listing URL: page 0 -> https://usabusinesssearch.com/{cityPath}/#b-{id}; page >= 1 -> https://usabusinesssearch.com/{cityPath}/{categorySlug}/ (+ page/{page}/ when page > 1) #b-{id}; cityPath 'recently-added' -> https://usabusinesssearch.com/recently-added/#b-{id}. flags: bit 1 = has phone, bit 2 = has website. Words skipped when choosing the prefix: the, a, an, and, of, co, llc, inc, near, me, in, best, top, for, my.",
        "parameters": [{ "name": "prefix", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9_]{2,8}$" } }],
        "responses": { "200": { "description": "Array of rows", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "array" } } } } }, "404": { "description": "No businesses with that prefix" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Category": { "type": "object", "properties": { "s": { "type": "string" }, "n": { "type": "string" }, "g": { "type": "string" }, "c": { "type": "integer" }, "k": { "type": "array", "items": { "type": "string" } } } }
    }
  },
  "x-actions": {
    "addBusiness": "https://usabusinesssearch.com/add-your-business/",
    "claimOrFix": "https://usabusinesssearch.com/claim/?b={id}",
    "upgrade": "https://usabusinesssearch.com/upgrade/",
    "contact": "https://usabusinesssearch.com/contact/"
  }
}