{
  "openapi": "3.1.0",
  "info": {
    "title": "Transparency Certified Directory API",
    "version": "1.0.0",
    "summary": "Public, read-only REST API for the Transparency Certified business directory.",
    "description": "US and Canadian businesses that passed an independent review-authenticity audit and hold a Transparency Certificate — and, on request, businesses that passed the audit but are not certified yet. Search and filter by name, category, city, state, or zip; fetch a single business by integer ID for the full certification rationale. By default only certified businesses are returned; `include_passed=1` adds businesses that passed the audit but are not certified yet.\n\n**Linking people to results:** this API returns JSON for programs. When showing results to a person, link to the `url` of each business and to `search_url` for the whole list — never to an `/api/v1` URL.\n\nNo authentication required. Rate limit: 50 requests / 10 seconds per IP across all `/api/v1/*` paths — exceeding it returns HTTP 429 with a JSON body carrying `retry_after` (seconds); wait 10 seconds and retry. A full-catalog export at `limit=50` stays under the limit if paced at up to 5 requests/second.\n\nThe API is read-only for integrations. Businesses request changes or removal through web forms on the site (`/change-request`, `/opt-out`), not through this API.",
    "contact": {
      "name": "Transparency Certification",
      "url": "https://transparencycertified.com/about"
    }
  },
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://transparencycertified.com/docs/api"
  },
  "servers": [
    {
      "url": "https://transparencycertified.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "tags": [
          "Status"
        ],
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "service",
                    "ts"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    },
                    "service": {
                      "type": "string",
                      "examples": [
                        "transparencycertified"
                      ]
                    },
                    "ts": {
                      "type": "integer",
                      "description": "Server time, Unix milliseconds."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/businesses": {
      "get": {
        "operationId": "listBusinesses",
        "summary": "List / search businesses",
        "description": "Returns certified, publicly listed businesses — plus audit-passed ones with `include_passed=1`. Without `q` certified businesses come first by default; use `sort=recently-certified` to keep that order for text searches. Same filters and sort options as the directory search on the site. All filters combine with AND (`category`/`categories` and `groups` with each other as OR). Values outside an option list (matching is case-sensitive) are ignored, never an error — except more than 5 categories (400). `q` is fuzzy (name, category, city, plus exact 2-letter US state / Canadian province codes and common city aliases like `nyc`); `category` and `city` are exact, case-sensitive matches; `state` and `zip` accept either case. Use `GET /api/v1/categories` for the canonical category names.",
        "tags": [
          "Businesses"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Fuzzy text search across name, category, and city. Also matches 2-letter US state and Canadian province codes exactly (e.g. `NY`, `AB`) and common city aliases (`nyc` → New York). Longer than 200 characters is truncated. Control characters are treated as spaces.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Exact match on primary category (e.g. `Plumber`). Up to 5 comma-separated categories match any of them (e.g. `Plumber,Electrician`); more than 5 returns 400. Canonical names: `GET /api/v1/categories`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "categories",
            "in": "query",
            "description": "Alias of `category` (the directory's name for it); both merge, and together they take at most 5 categories.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "groups",
            "in": "query",
            "description": "Comma-separated category groups (the `group` of `GET /api/v1/categories`, e.g. `Home Services`; case-sensitive). Matches any category in the groups; combined with `category` as OR. Unknown names are ignored. `Other` also matches businesses without a category.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Exact match on city.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "2-letter US state or Canadian province code (e.g. `IL`, `AB`), case-insensitive.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          },
          {
            "name": "zip",
            "in": "query",
            "description": "US ZIP or full Canadian postal code (any case, with or without the space). A bare Canadian FSA (the first 3 characters, e.g. `T5L`) matches every code in that area.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metro",
            "in": "query",
            "description": "`City, ST` (e.g. `Austin, TX`; the city part is case-sensitive) — sets `city` and `state` in one go and wins over them.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Comma-separated `certified` and/or `passed`. Asking for `passed` includes passed businesses without `include_passed`. Other values (matching is case-sensitive) are ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rating",
            "in": "query",
            "description": "Minimum average rating: `4.5`, `4` or `3`. Other values are ignored.",
            "schema": {
              "type": "number",
              "enum": [
                4.5,
                4,
                3
              ]
            }
          },
          {
            "name": "reviews",
            "in": "query",
            "description": "Minimum review count: `250`, `100`, `50` or `25`. Other values are ignored.",
            "schema": {
              "type": "integer",
              "enum": [
                250,
                100,
                50,
                25
              ]
            }
          },
          {
            "name": "certifiedWithin",
            "in": "query",
            "description": "Certified within the last `30` or `90` days. Other values are ignored. Excludes passed businesses (they have no certification date).",
            "schema": {
              "type": "integer",
              "enum": [
                30,
                90
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IncludePassed"
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Result order (same options as the directory): `relevance` (text match — only with `q`), `recently-certified` (certified first, newest first), `recent-certified-and-passed` (newest certification or audit date, statuses mixed), `recently-passed` (passed first), `longest-certified`, `most-reviews`, `highest-rated`, `az`, `za`. Default (as in the directory search): `relevance` with `q`, otherwise `recently-certified`. Unknown values use the default.",
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "recently-certified",
                "recent-certified-and-passed",
                "recently-passed",
                "longest-certified",
                "most-reviews",
                "highest-rated",
                "az",
                "za"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number. Values outside 1–2000000 are clamped. Results end at 2,000,000 (2,000 with `sort=az`/`za`): deeper pages return an empty `data` with the real `total`, and `totalPages` reflects that cap.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000000,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page. Values outside 1–50 are clamped.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of businesses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "total",
                    "page",
                    "limit",
                    "totalPages",
                    "search_url"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Business"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total matching businesses across all pages."
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "totalPages": {
                      "type": "integer"
                    },
                    "search_url": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri",
                      "description": "The same list as a page on the site (/directory/search), for \"see all results\" links. With `q` the page reads the text like its search box, so its results can differ slightly. Null when the filters can't be shown there (`city` without `state`, a `state` that isn't a 2-letter code, or a `zip` that isn't a postal code)."
                    }
                  }
                }
              }
            },
            "headers": {
              "Link": {
                "description": "Also carries `search_url` as `rel=\"alternate\"; type=\"text/html\"`.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/businesses/{id}": {
      "get": {
        "operationId": "getBusinessById",
        "summary": "Get a business by ID",
        "description": "Single business by **integer ID** (the `id` field from the list endpoint — not the slug). A certified business carries a `certification` block: the machine-readable rationale for why it is certified. With `include_passed=1` (or `status=passed`) an audit-passed business (not certified yet) is returned too, with `status: \"passed\"` and an `audit` block instead — never a `certification` block. Returns 404 if the business is not publicly listed (or, without `include_passed` / `status=passed`, not certified).",
        "tags": [
          "Businesses"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Integer business ID.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "$ref": "#/components/parameters/IncludePassed"
          },
          {
            "name": "status",
            "in": "query",
            "description": "`passed` returns a passed business (same as `include_passed`); other values are ignored.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The business, with its certification rationale (or, for a passed business, its audit facts).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BusinessDetail"
                    },
                    {
                      "$ref": "#/components/schemas/PassedBusinessDetail"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Unknown ID, or the business is not publicly listed (without `include_passed` or `status=passed`: not certified).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List categories",
        "description": "Category names usable in the `category` filter of `GET /api/v1/businesses`, largest first, with the number of listed businesses in each. Counts follow `include_passed` the same way the business list does.",
        "tags": [
          "Businesses"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Case-insensitive substring match on the category name (e.g. `plumb`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IncludePassed"
          },
          {
            "name": "status",
            "in": "query",
            "description": "Comma-separated; `passed` in it makes the counts include passed businesses too (same as `include_passed`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number. Values outside 1–100000 are clamped.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page. Values outside 1–200 are clamped.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "total",
                    "page",
                    "limit",
                    "totalPages"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total matching categories across all pages."
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "totalPages": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Business": {
        "type": "object",
        "description": "A publicly listed business: certified, or — only when passed records are requested (`include_passed=1` or `status=passed`) — audit-passed and not certified yet. Without that opt-in every record is certified. The API never exposes revoked, hidden, or removed records.",
        "required": [
          "id",
          "slug",
          "name",
          "url",
          "status"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Integer ID — use for `GET /api/v1/businesses/{id}`."
          },
          "slug": {
            "type": "string",
            "description": "URL slug (part of `url`)."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public page of this business on transparencycertified.com. Use this link when showing the business to people."
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "Street address; usually already includes city/state/zip."
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ],
            "description": "2-letter US state or Canadian province code (e.g. NY, AB). May be null; always null for records outside the US and Canada — their full address is in address."
          },
          "zip": {
            "type": [
              "string",
              "null"
            ],
            "description": "US ZIP code or Canadian postal code (e.g. 94545, T5L 3C5). May be null; always null for records outside the US and Canada — their postcode is in address."
          },
          "country": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO-3166-1 alpha-2 country code: US or CA for almost all listings; a few records carry another country (e.g. GB). Null when unknown."
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "avg_rating": {
            "type": [
              "string",
              "null"
            ],
            "description": "Average review rating 0–5, serialized as a decimal string (e.g. `\"4.8\"`)."
          },
          "review_count": {
            "type": [
              "integer",
              "null"
            ]
          },
          "primary_category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Business category (e.g. `Plumber`)."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "certified_since": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the business was certified."
          },
          "certificate_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Transparency Certificate ID, format `TC-…` — treat as an opaque string. Always null for a `passed` business (it holds no certificate)."
          },
          "last_monitored": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the record's review data was last monitored."
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the record last changed."
          },
          "status": {
            "type": "string",
            "enum": [
              "certified",
              "passed"
            ],
            "description": "`certified` or `passed`. Without `include_passed` (or `status=passed`) every record is `certified`. `passed` = passed the review-authenticity audit, not certified yet: no owner commitment, no certificate (`certificate_id` is null). Check this field before presenting a business as certified."
          }
        }
      },
      "BusinessDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Business"
          },
          {
            "type": "object",
            "required": [
              "certification"
            ],
            "properties": {
              "certification": {
                "$ref": "#/components/schemas/Certification"
              }
            }
          }
        ]
      },
      "Certification": {
        "type": "object",
        "description": "Machine-readable rationale: why this business is certified.",
        "required": [
          "program",
          "audit_completed_on",
          "platform",
          "reviews_analyzed",
          "checks",
          "scope",
          "owner_attested",
          "methodology"
        ],
        "properties": {
          "program": {
            "type": "string",
            "const": "Transparency Certificate"
          },
          "audit_completed_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the review-authenticity audit passed."
          },
          "platform": {
            "type": "string",
            "description": "Review platform analyzed (e.g. `Google Maps`)."
          },
          "reviews_analyzed": {
            "type": "integer",
            "description": "Number of reviews covered by the audit."
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The authenticity checks passed (fake / paid / coordinated / AI-generated activity)."
          },
          "scope": {
            "type": "string",
            "description": "Scope & limitations statement — quote this when relaying certification claims."
          },
          "owner_attested": {
            "type": "boolean",
            "description": "The owner confirmed the business and committed to responsible review practices. Always `true` on this endpoint.",
            "const": true
          },
          "methodology": {
            "type": "string",
            "format": "uri",
            "description": "URL of the full methodology."
          }
        }
      },
      "NotFoundError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "Not found"
            ]
          }
        }
      },
      "RateLimitError": {
        "type": "object",
        "required": [
          "error",
          "retry_after"
        ],
        "properties": {
          "error": {
            "type": "string",
            "const": "rate_limited"
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds until the limit window clears. There is no `Retry-After` header — use this field."
          }
        }
      },
      "PassedBusinessDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Business"
          },
          {
            "type": "object",
            "required": [
              "status",
              "audit"
            ],
            "properties": {
              "status": {
                "const": "passed"
              },
              "audit": {
                "$ref": "#/components/schemas/Audit"
              }
            }
          }
        ]
      },
      "Audit": {
        "type": "object",
        "description": "Audit facts of a passed (not yet certified) business. Not a certification: the owner has not committed to the standards.",
        "required": [
          "audit_completed_on",
          "platform",
          "reviews_analyzed",
          "checks",
          "scope",
          "owner_attested",
          "methodology"
        ],
        "properties": {
          "audit_completed_on": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the review-authenticity audit passed."
          },
          "platform": {
            "type": "string",
            "description": "Review platform analyzed (e.g. `Google Maps`)."
          },
          "reviews_analyzed": {
            "type": "integer",
            "description": "Number of reviews covered by the audit."
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The authenticity checks passed (fake / paid / coordinated / AI-generated activity)."
          },
          "scope": {
            "type": "string",
            "description": "Scope & limitations of the audit — quote this when relaying what the audit found. A passed audit is not a certification."
          },
          "owner_attested": {
            "type": "boolean",
            "const": false,
            "description": "Always `false`: a passed business has not completed the owner commitment."
          },
          "methodology": {
            "type": "string",
            "format": "uri",
            "description": "URL of the full methodology."
          }
        }
      },
      "Category": {
        "type": "object",
        "required": [
          "name",
          "group",
          "count",
          "search_url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Exact category name for the `category` filter."
          },
          "group": {
            "type": "string",
            "description": "Category group, usable in the `groups` filter. `Other` collects categories outside the named groups."
          },
          "count": {
            "type": "integer",
            "description": "Listed businesses in this category."
          },
          "search_url": {
            "type": "string",
            "format": "uri",
            "description": "Businesses in this category as a page on the site (/directory/search)."
          }
        }
      },
      "BadRequestError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "At most 5 categories"
            ]
          }
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limited: more than 50 requests / 10 seconds from one IP across `/api/v1/*`. The block clears on its own — sleep `retry_after` seconds and retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimitError"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid parameters (e.g. more than 5 categories).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/BadRequestError"
            }
          }
        }
      }
    },
    "parameters": {
      "IncludePassed": {
        "name": "include_passed",
        "in": "query",
        "description": "`1` or `true` (any case) also returns audit-passed businesses that are not certified yet (`status: \"passed\"`). Any other value — or omitting it — keeps the certified-only default.",
        "schema": {
          "type": "string",
          "enum": [
            "1",
            "true"
          ]
        }
      }
    }
  },
  "tags": [
    {
      "name": "Businesses",
      "description": "Read-only directory of Transparency Certified businesses and their categories."
    },
    {
      "name": "Status",
      "description": "Service health."
    }
  ]
}
