openapi: 3.1.0
info:
  title: TradeBooks Pro — Local Trades Directory API
  version: 2.0.0
  description: >
    TradeBooks Pro is a directory of local trade and service businesses.
    This API returns teaser information only (business name, trade, city, and
    a link to the full listing on tradebookspro.com). Full business details
    are available only by visiting the listing page on our website.
servers:
  - url: https://tradebookspro.com
    description: Production
paths:
  /api/search:
    post:
      operationId: searchBusinesses
      summary: Find local trade professionals that serve a location.
      description: >
        Returns a list of matching businesses with name, trade, city, and a
        link to their TradeBooks Pro listing page. Full contact details and
        service information are available only on the listing page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
      responses:
        "200":
          description: Teaser results with links to full listings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "429": { description: Rate limit exceeded (60 requests/min). }
  /api/business:
    post:
      operationId: getBusiness
      summary: Get a business listing teaser by ID or slug.
      description: >
        Returns the business name, trade, city, and a link to the full
        listing page on tradebookspro.com.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id: { type: string, description: Business ID. }
                slug: { type: string, description: Business URL slug. }
              anyOf:
                - required: [id]
                - required: [slug]
      responses:
        "200":
          description: Business teaser with link to full listing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BusinessTeaser"
        "400": { description: Neither id nor slug provided. }
        "404": { description: Not found. }
        "429": { description: Rate limit exceeded. }
components:
  schemas:
    Location:
      type: object
      description: The user's location (required for search).
      properties:
        zip: { type: string, description: 5-digit US ZIP code. }
        city: { type: string }
        state: { type: string, description: 2-letter state code, e.g. GA. }
    SearchRequest:
      type: object
      required: [query, location]
      properties:
        query: { type: string, description: What the user needs help with. }
        location: { $ref: "#/components/schemas/Location" }
    BusinessTeaser:
      type: object
      properties:
        businessName: { type: string }
        trade: { type: string }
        city: { type: string }
        state: { type: string }
        distanceMiles: { type: [number, "null"] }
        url: { type: string, description: Full listing page on tradebookspro.com }
        message: { type: string }
    SearchResponse:
      type: object
      properties:
        coverage:
          type: string
          enum: [found, none, need_location]
        total: { type: integer }
        results:
          type: array
          items: { $ref: "#/components/schemas/BusinessTeaser" }
        message: { type: string }