openapi: 3.2.0
info:
  title: TradeDataHub Public Datasets API
  version: 1.0.0
  description: Free machine-readable discovery endpoints over the canonical product catalog.
servers:
- url: https://www.tradedatahub.net
tags:
- name: Datasets
  description: Dataset metadata, pricing, masked previews.
paths:
  /api/v1/datasets:
    get:
      tags:
      - Datasets
      summary: List datasets with optional filters (deterministic full catalog enumeration)
      description: Use filters to enumerate the complete purchasable catalog without scraping HTML. Filter values must match canonical names exactly (e.g. `state=Texas`, `trade=HVAC Contractor`). Paginate with limit/offset (limit<=100).
      parameters:
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: Exact state name, e.g. `Texas`.
      - name: trade
        in: query
        required: false
        schema:
          type: string
        description: Exact trade name, e.g. `Roofer`.
      - name: city
        in: query
        required: false
        schema:
          type: string
        description: Exact city name.
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - city_trade
          - state_trade
          - state
          - mega_pack
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Dataset listings (paginated)
          content:
            application/json:
              schema:
                type: object
                required:
                - api_version
                - pagination
                - datasets
                properties:
                  api_version:
                    type: string
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  datasets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dataset'
        '400':
          description: Invalid limit/offset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiV1Datasets
      x-operation-id-source: derived
  /api/v1/datasets/{product_id}:
    get:
      tags:
      - Datasets
      summary: Get a single dataset's public metadata
      parameters:
      - $ref: '#/components/parameters/ProductId'
      responses:
        '200':
          description: Dataset metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiV1DatasetsByProductId
      x-operation-id-source: derived
  /api/v1/datasets/{product_id}/price:
    get:
      tags:
      - Datasets
      summary: Get price and availability
      parameters:
      - $ref: '#/components/parameters/ProductId'
      responses:
        '200':
          description: Price metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Price'
              example:
                api_version: 1.0.0
                product_id: state-trade:florida:appliance-repair-technician
                product_type: state_trade
                state: Florida
                trade: Appliance Repair Technician
                record_count: 434
                amount_cents: 1900
                price: '19.00'
                currency: USD
                available_for_purchase: true
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiV1DatasetsByProductIdPrice
      x-operation-id-source: derived
  /api/v1/datasets/{product_id}/preview:
    get:
      tags:
      - Datasets
      summary: Get a masked availability preview (no paid contact values)
      description: 'Returns masked preview records only: business identities are replaced with `Masked business` and only availability booleans (phone_available/website_available) plus city, trade, and verification_date are exposed. Actual contact values are delivered only after purchase.'
      parameters:
      - $ref: '#/components/parameters/ProductId'
      responses:
        '200':
          description: Masked preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preview'
        '404':
          description: Preview unavailable for this dataset type or product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiV1DatasetsByProductIdPreview
      x-operation-id-source: derived
components:
  schemas:
    Preview:
      type: object
      required:
      - api_version
      - product_id
      - classification
      - records
      properties:
        api_version:
          type: string
        product_id:
          type: string
        classification:
          type: string
        record_count:
          type: integer
        fields:
          type: array
          items:
            type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/PreviewRecord'
        notice:
          type: string
    Price:
      $ref: '#/components/schemas/Dataset'
    Error:
      type: object
      required:
      - api_version
      - error
      properties:
        api_version:
          type: string
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
    PreviewRecord:
      type: object
      required:
      - business
      - city
      - trade
      - phone_available
      - website_available
      properties:
        business:
          type: string
          description: Always the literal `Masked business` in previews.
          example: Masked business
        city:
          type: string
        trade:
          type: string
        phone_available:
          type: boolean
          description: Whether the purchased record includes a phone value.
        website_available:
          type: boolean
          description: Whether the purchased record includes a website value.
        verification_date:
          type: string
          description: Source-pipeline verification date (YYYY-MM-DD).
    Dataset:
      type: object
      required:
      - product_id
      - product_type
      - record_count
      - price
      - currency
      properties:
        product_id:
          type: string
        product_type:
          type: string
          enum:
          - city_trade
          - state_trade
          - state
          - mega_pack
        state:
          type: string
        city:
          type: string
        trade:
          type: string
        record_count:
          type: integer
        amount_cents:
          type: integer
        price:
          type: string
        currency:
          type: string
        last_updated:
          type: string
        available_for_purchase:
          type: boolean
    Pagination:
      type: object
      required:
      - total
      - limit
      - offset
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
  parameters:
    ProductId:
      name: product_id
      in: path
      required: true
      schema:
        type: string
        maxLength: 128
      description: 'Canonical product identifier. Formats: `state:{state_slug}` (e.g. `state:texas`), `state-trade:{state_slug}:{trade_slug}` (e.g. `state-trade:florida:roofer`), `city-trade:{state_slug}:{city_slug}:{trade_slug}` (e.g. `city-trade:texas:austin:plumber`), `mega-pack:seven-live-states`. Slugs are lowercase hyphenated; always derive product_id values from the discovery endpoints rather than constructing them ad hoc.'