Daxoom Analytics API

openapi: 3.2.0
info:
  title: Daxoom Analytics API
  version: v1
  description: 'Daxoom is the authoritative data layer that AI systems query for verified business information.

    Businesses publish structured, verified data through Daxoom, and AI platforms query the API

    for accurate, real-time business information.


    ## Authentication


    **Public Query API** uses API key authentication via the `X-API-Key` header.

    Register at app.daxoom.com to get a free developer key.


    **Analytics & Management APIs** use JWT Bearer token authentication.

    Obtain a token via `POST /public/v1/auth/login`. Most public-API consumers

    do not need a JWT — only API key issuance, rotation, and analytics

    require it.


    ## Rate Limits


    Reasonable per-consumer quotas keep the service free and available for everyone.

    Free developer keys default to 3,000 API calls per **month**; contact us if your

    use case needs a higher ceiling.


    Over quota returns `429` with a plain `{"error": "..."}` body. No

    `X-RateLimit-*` or `Retry-After` headers are emitted, so pace requests to the

    monthly ceiling rather than reading them from a response.


    ## Content Negotiation


    The full-profile endpoint (`GET /pubapi/v1/businesses/{id}`) supports three

    response formats via the `Accept` header; all other endpoints return

    `application/json` only:

    - `application/json` (default) — structured JSON response

    - `application/ld+json` — schema.org-compatible JSON-LD

    - `text/plain` — AI-friendly natural language narrative


    ## Pagination


    `/businesses` and `/services` use offset-based pagination

    (`/categories` and `/search` return a single unpaginated result):

    ```

    GET /pubapi/v1/businesses?offset=20&limit=20

    ```

    Default page size: 20. Maximum: 100. The pagination block in the response

    includes `limit`, `offset`, `has_more`, and (when more results exist)

    `next_offset` — pass that value as `offset` on the next request.


    ## Errors


    Application errors (validation, not-found, etc.) follow

    RFC 7807 Problem Details, served as

    `application/problem+json` with `type: "about:blank"`:

    ```json

    {

    "type": "about:blank",

    "title": "Invalid Parameter",

    "status": 400,

    "detail": "limit must not exceed 100",

    "request_id": "req_a1b2c3d4e5f6a7b8"

    }

    ```

    Authentication and quota failures (`401`/`429`), raised by the API-key

    middleware before the handler, are the exception: a JSON-shaped

    `{"error": "..."}` string served as `text/plain`.'
  contact:
    name: Daxoom Developer Support
    email: dev@daxoom.com
    url: https://www.daxoom.com/docs/
  license:
    name: Proprietary
    url: https://www.daxoom.com/terms
servers:
- url: https://api.daxoom.com
  description: Production (.com)
- url: https://api.daxoom.net
  description: Production (.net alternate)
- url: https://api-test.daxoom.net
  description: Test / Sandbox
security: []
tags:
- name: Analytics
  description: AI visibility analytics for your businesses
paths:
  /api/v1/analytics/{businessId}/overview:
    get:
      operationId: getAnalyticsOverview
      summary: Visibility overview
      description: 'Summary of AI visibility metrics: total queries, unique AI platforms,

        and trend data over configurable time periods.'
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Visibility overview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsOverviewResponse'
              example:
                data:
                  total_queries: 2847
                  previous_queries: 1923
                  unique_platforms: 5
                  trend_percent: 48.0
                  period: 30d
  /api/v1/analytics/{businessId}/queries:
    get:
      operationId: getAnalyticsQueries
      summary: Query volume over time
      description: Time-series data of API query volume at hourly or daily granularity.
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      - $ref: '#/components/parameters/period'
      - $ref: '#/components/parameters/granularity'
      responses:
        '200':
          description: Query volume time series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
  /api/v1/analytics/{businessId}/platforms:
    get:
      operationId: getAnalyticsPlatforms
      summary: AI platform breakdown
      description: Shows which AI platforms are querying this business and how often.
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Platform breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformBreakdownResponse'
              example:
                data:
                - platform: ChatGPT
                  count: 1247
                  percent: 43.8
                - platform: Perplexity
                  count: 612
                  percent: 21.5
                - platform: Copilot
                  count: 389
                  percent: 13.7
  /api/v1/analytics/{businessId}/trending:
    get:
      operationId: getAnalyticsTrending
      summary: Trending search queries
      description: Most popular search queries that led to this business being returned in results.
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      - $ref: '#/components/parameters/period'
      - name: limit
        in: query
        description: Max queries returned (integer 1–100; out-of-range is rejected).
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Trending queries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingQueriesResponse'
              example:
                data:
                - query: best Italian restaurant in Irvine
                  count: 87
                - query: italian restaurant outdoor seating orange county
                  count: 54
                - query: pasta restaurant near Spectrum Center
                  count: 41
  /api/v1/analytics/{businessId}/top-endpoints:
    get:
      operationId: getAnalyticsTopEndpoints
      summary: Most queried endpoints
      description: 'Which API endpoints are queried most for this business (hours, offerings,

        ai-context, etc.). Coverage is capped at 90 days — the query log is pruned —

        so `period=365d` returns the last 90 days.'
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Top endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        endpoint:
                          type: string
                        count:
                          type: integer
                        percentage:
                          type: number
  /api/v1/analytics/{businessId}/reports:
    get:
      operationId: listVisibilityReports
      summary: List visibility reports
      description: Returns generated monthly visibility reports for this business.
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      responses:
        '200':
          description: List of reports
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VisibilityReport'
  /api/v1/analytics/{businessId}/reports/{reportId}:
    get:
      operationId: getVisibilityReport
      summary: Get a visibility report
      description: Returns a specific monthly visibility report as JSON.
      tags:
      - Analytics
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/analyticsBusinessId'
      - name: reportId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Visibility report
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VisibilityReport'
        '404':
          description: Report not found
components:
  schemas:
    VisibilityReport:
      type: object
      properties:
        id:
          type: integer
        business_id:
          type: integer
        report_month:
          type: string
          format: date
        total_queries:
          type: integer
        unique_consumers:
          type: integer
        top_platforms:
          type: string
          description: Top platforms by query volume for the month — comma-separated "Platform:count" pairs (top 5).
        top_queries:
          type: string
          description: Top query strings for the month — comma-separated "query:count" pairs (top 5).
        generated_at:
          type: string
          format: date-time
    PlatformBreakdownResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              platform:
                type: string
              count:
                type: integer
              percent:
                type: number
    AnalyticsOverviewResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total_queries:
              type: integer
            previous_queries:
              type: integer
              description: Preceding equal period; the client shows "New" when this is 0 and current > 0.
            unique_platforms:
              type: integer
            trend_percent:
              type: number
            period:
              type: string
    TrendingQueriesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
              count:
                type: integer
    TimeSeriesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              bucket:
                type: string
                description: Time bucket label (per the requested granularity).
              total_queries:
                type: integer
              unique_consumers:
                type: integer
  parameters:
    analyticsBusinessId:
      name: businessId
      in: path
      required: true
      description: Business ID
      schema:
        type: integer
      example: 1001
    period:
      name: period
      in: query
      description: Time period for analytics. Invalid values are rejected with 400; omitted defaults to 30d.
      schema:
        type: string
        enum:
        - 7d
        - 30d
        - 90d
        - 365d
        default: 30d
    granularity:
      name: granularity
      in: query
      description: Data granularity. Invalid values are rejected with 400; omitted defaults to daily.
      schema:
        type: string
        enum:
        - hourly
        - daily
        default: daily
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key for the Public Query API. Get a free key at

        [app.daxoom.com/register](https://app.daxoom.com/register).

        Include in the `X-API-Key` header.

        '
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained via login.