API Documentation

Public read-only REST API for the Transparency Certification directory. No authentication required.

Base URL: https://transparencycertified.com/api/v1

Format: All responses are JSON.

Rate limits: 50 requests / 10 seconds per IP, enforced at the edge (Cloudflare). Exceeding it returns 429 with a JSON body containing retry_after (seconds); the block clears automatically after 10 seconds. Contact us for higher throughput.

Versioning: Current version is v1.

Examples: Response examples below use a fictional business. To try the API against live data, grab a real ID from the list endpoint first: GET /api/v1/businesses?category=Plumber&limit=1

List / Search Businesses

Search, filter, and paginate certified businesses.

GET /api/v1/businesses

Query Parameters

Param	Type	Description
`q`	string	Text search (name, category, city)
`category`	string	Filter by primary category
`city`	string	Filter by city
`state`	string	2-letter state code
`zip`	string	ZIP code
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 50)

Example

GET /api/v1/businesses?category=Plumber&state=IL&limit=2

{
  "data": [
    {
      "id": 999999,
      "slug": "example-plumbing-co",
      "name": "Example Plumbing Co.",
      "address": "123 Example St, Springfield, IL 62701",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "lat": 39.7817213,
      "lng": -89.6501481,
      "avg_rating": "4.8",
      "review_count": 132,
      "primary_category": "Plumber",
      "phone": "(217) 555-0142",
      "website": "example-plumbing.example.com",
      "certified_since": "2026-05-01T00:00:00.000Z",
      "certificate_id": "TC-xK4fRq2Lm9B",
      "last_monitored": "2026-08-20T06:00:00.000Z",
      "updated_at": "2026-08-20T06:00:00.000Z"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 2,
  "totalPages": 4
}

Get Business by ID

Retrieve the full profile of a single business by its numeric ID. Includes a certification block explaining why the business is certified: the review-authenticity checks performed, their scope, the audited platform, and the owner attestation. last_monitored and updated_at (on all endpoints) indicate data freshness.

GET /api/v1/businesses/:id

Example

GET /api/v1/businesses/999999

{
  "id": 999999,
  "slug": "example-plumbing-co",
  "name": "Example Plumbing Co.",
  "address": "123 Example St, Springfield, IL 62701",
  "city": "Springfield",
  "state": "IL",
  "zip": "62701",
  "lat": 39.7817213,
  "lng": -89.6501481,
  "avg_rating": "4.8",
  "review_count": 132,
  "primary_category": "Plumber",
  "phone": "(217) 555-0142",
  "website": "example-plumbing.example.com",
  "certified_since": "2026-05-01T00:00:00.000Z",
  "certificate_id": "TC-xK4fRq2Lm9B",
  "last_monitored": "2026-08-20T06:00:00.000Z",
  "updated_at": "2026-08-20T06:00:00.000Z",
  "certification": {
    "program": "Transparency Certificate",
    "audit_completed_on": "2026-04-17",
    "platform": "Google Maps",
    "reviews_analyzed": 132,
    "checks": [
      "No manipulated or fake reviews detected",
      "No paid or incentivized reviews detected",
      "No coordinated posting activity detected",
      "No AI-generated content at scale"
    ],
    "scope": "This is a pattern-based scan of review activity, not a guarantee that every individual review is authentic, and not a rating of the business's service quality.",
    "owner_attested": true,
    "methodology": "https://transparencycertified.com/how-it-works"
  }
}

404 Response

{ "error": "Not found" }

Pagination

List endpoints use offset pagination with page and limit.

{
  "data": [
    "..."
  ],
  "total": 7843,
  "page": 1,
  "limit": 20,
  "totalPages": 393
}

Error Responses

Status	Meaning	Body
200	Success	Result object
400	Bad request	{ "ok": false, "error": "..." }
404	Not found	{ "error": "Not found" }
500	Server error	{ "ok": false, "error": "..." }