Circana Liquid Data API

openapi: 3.0.3
info:
  title: Circana Liquid Data API
  description: >-
    Circana's Liquid Data platform provides cross-industry data and advanced
    analytics in a single, open platform. This API enables programmatic access
    to market measurement, consumer panel, and retail analytics data deployable
    across Azure, AWS, Google Cloud, and Oracle Cloud environments.
  version: 1.0.0
  contact:
    name: Circana
    url: https://www.circana.com
    email: [email protected]
  license:
    name: Proprietary
    url: https://www.circana.com/terms-and-conditions
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
  - url: https://api.circana.com/liquid-data/v1
    description: Circana Liquid Data Production API
security:
  - bearerAuth: []
tags:
  - name: Market Data
    description: Access point-of-sale and market measurement data
  - name: Consumer Panel
    description: Consumer panel data and shopper insights
  - name: Categories
    description: Product category hierarchy and management
  - name: Brands
    description: Brand performance and analytics
  - name: Retailers
    description: Retailer data and channel analytics
  - name: Reports
    description: Report generation and management
  - name: Exports
    description: Data export and download operations
paths:
  /market-data/pos:
    get:
      operationId: getPointOfSaleData
      summary: Circana Get Point of Sale Data
      description: >-
        Retrieve point-of-sale data with filters for time period, geography,
        category, and retailer. Returns sales volume, revenue, and unit data.
      tags:
        - Market Data
      parameters:
        - name: category_id
          in: query
          required: true
          description: Product category identifier
          schema:
            type: string
          example: cpg-beverages
        - name: start_date
          in: query
          required: true
          description: Start date for the data range in ISO 8601 format
          schema:
            type: string
            format: date
          example: '2026-01-01'
        - name: end_date
          in: query
          required: true
          description: End date for the data range in ISO 8601 format
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - name: geography
          in: query
          required: false
          description: Geographic market filter
          schema:
            type: string
            enum:
              - national
              - regional
              - dma
              - store
          example: national
        - name: retailer_id
          in: query
          required: false
          description: Specific retailer identifier for filtering
          schema:
            type: string
          example: ret-500123
        - name: granularity
          in: query
          required: false
          description: Time granularity of the data
          schema:
            type: string
            enum:
              - weekly
              - monthly
              - quarterly
              - annual
          example: weekly
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
          example: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return
          schema:
            type: integer
            default: 100
            maximum: 1000
          example: 100
      responses:
        '200':
          description: Point-of-sale data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/POSDataResponse'
              examples:
                GetPointOfSaleData200Example:
                  summary: Default getPointOfSaleData 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - period: '2026-W01'
                        category: Beverages
                        brand: Example Brand
                        upc: '012345678901'
                        dollar_sales: 125340.50
                        unit_sales: 45230
                        volume_sales: 67845.0
                        avg_price: 2.77
                        distribution_pct: 85.3
                    pagination:
                      offset: 0
                      limit: 100
                      total: 4523
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions for requested data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /market-data/share:
    get:
      operationId: getMarketShare
      summary: Circana Get Market Share Data
      description: >-
        Retrieve market share data showing brand and category share metrics
        across retailers and geographies.
      tags:
        - Market Data
      parameters:
        - name: category_id
          in: query
          required: true
          description: Product category identifier
          schema:
            type: string
          example: cpg-snacks
        - name: start_date
          in: query
          required: true
          description: Start date for the data range
          schema:
            type: string
            format: date
          example: '2026-01-01'
        - name: end_date
          in: query
          required: true
          description: End date for the data range
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - name: metric
          in: query
          required: false
          description: Share metric type
          schema:
            type: string
            enum:
              - dollar_share
              - unit_share
              - volume_share
          example: dollar_share
      responses:
        '200':
          description: Market share data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketShareResponse'
              examples:
                GetMarketShare200Example:
                  summary: Default getMarketShare 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - brand: Example Brand A
                        dollar_share: 24.5
                        unit_share: 22.1
                        share_change: 1.2
                        period: '2026-Q1'
                    pagination:
                      offset: 0
                      limit: 100
                      total: 45
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /consumer-panel/purchases:
    get:
      operationId: getConsumerPurchases
      summary: Circana Get Consumer Purchase Data
      description: >-
        Retrieve aggregated consumer purchase data from panel surveys, receipt
        scanning, and loyalty data covering 200K+ static panelists.
      tags:
        - Consumer Panel
      parameters:
        - name: category_id
          in: query
          required: true
          description: Product category identifier
          schema:
            type: string
          example: cpg-beverages
        - name: start_date
          in: query
          required: true
          description: Start date for the data range
          schema:
            type: string
            format: date
          example: '2026-01-01'
        - name: end_date
          in: query
          required: true
          description: End date for the data range
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - name: demographic
          in: query
          required: false
          description: Demographic segment filter
          schema:
            type: string
            enum:
              - age
              - income
              - household_size
              - ethnicity
              - region
          example: age
        - name: channel
          in: query
          required: false
          description: Purchase channel filter
          schema:
            type: string
            enum:
              - grocery
              - mass
              - club
              - dollar
              - convenience
              - online
              - drug
          example: grocery
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
          example: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return
          schema:
            type: integer
            default: 100
          example: 100
      responses:
        '200':
          description: Consumer purchase data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumerPurchaseResponse'
              examples:
                GetConsumerPurchases200Example:
                  summary: Default getConsumerPurchases 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - segment: 18-34
                        category: Beverages
                        penetration_pct: 72.5
                        buy_rate: 3.2
                        avg_spend: 15.80
                        trips_per_buyer: 4.1
                        channel: grocery
                    pagination:
                      offset: 0
                      limit: 100
                      total: 156
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /consumer-panel/segments:
    get:
      operationId: getConsumerSegments
      summary: Circana Get Consumer Segments
      description: >-
        Retrieve consumer segmentation data based on purchase behavior,
        demographics, and shopping patterns.
      tags:
        - Consumer Panel
      parameters:
        - name: category_id
          in: query
          required: true
          description: Product category identifier
          schema:
            type: string
          example: cpg-snacks
        - name: segmentation_type
          in: query
          required: false
          description: Type of segmentation analysis
          schema:
            type: string
            enum:
              - behavioral
              - demographic
              - psychographic
              - channel
          example: behavioral
      responses:
        '200':
          description: Consumer segments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumerSegmentResponse'
              examples:
                GetConsumerSegments200Example:
                  summary: Default getConsumerSegments 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - segment_id: seg-001
                        name: Health-Conscious Shoppers
                        size_pct: 18.5
                        avg_basket_size: 42.30
                        preferred_channels:
                          - grocery
                          - online
                        key_categories:
                          - Organic Foods
                          - Natural Beverages
                    pagination:
                      offset: 0
                      limit: 100
                      total: 12
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /categories:
    get:
      operationId: listCategories
      summary: Circana List Categories
      description: >-
        List available product categories in the Circana taxonomy hierarchy
        covering CPG, general merchandise, beauty, food, and technology.
      tags:
        - Categories
      parameters:
        - name: parent_id
          in: query
          required: false
          description: Parent category ID to list subcategories
          schema:
            type: string
          example: cpg
        - name: industry
          in: query
          required: false
          description: Industry vertical filter
          schema:
            type: string
            enum:
              - cpg
              - beauty
              - food_beverage
              - technology
              - healthcare
              - general_merchandise
              - apparel
              - home
          example: cpg
        - name: search
          in: query
          required: false
          description: Search term to filter categories
          schema:
            type: string
          example: beverages
      responses:
        '200':
          description: Categories listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryListResponse'
              examples:
                ListCategories200Example:
                  summary: Default listCategories 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - category_id: cpg-beverages
                        name: Beverages
                        parent_id: cpg
                        industry: cpg
                        level: 2
                        subcategory_count: 15
                    pagination:
                      offset: 0
                      limit: 100
                      total: 250
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /categories/{category_id}:
    get:
      operationId: getCategory
      summary: Circana Get Category Details
      description: >-
        Get detailed information about a specific product category including
        hierarchy, metadata, and available data coverage.
      tags:
        - Categories
      parameters:
        - name: category_id
          in: path
          required: true
          description: Unique category identifier
          schema:
            type: string
          example: cpg-beverages
      responses:
        '200':
          description: Category details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryDetail'
              examples:
                GetCategory200Example:
                  summary: Default getCategory 200 response
                  x-microcks-default: true
                  value:
                    category_id: cpg-beverages
                    name: Beverages
                    description: All beverage categories including carbonated, juice, water, and energy drinks
                    parent_id: cpg
                    industry: cpg
                    level: 2
                    subcategories:
                      - category_id: cpg-beverages-carbonated
                        name: Carbonated Beverages
                    data_coverage:
                      pos_available: true
                      panel_available: true
                      earliest_date: '2018-01-01'
                      latest_date: '2026-03-31'
        '404':
          description: Category not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /brands:
    get:
      operationId: listBrands
      summary: Circana List Brands
      description: >-
        List brands within a specific category with performance metrics and
        market share data.
      tags:
        - Brands
      parameters:
        - name: category_id
          in: query
          required: true
          description: Product category to search brands within
          schema:
            type: string
          example: cpg-beverages
        - name: search
          in: query
          required: false
          description: Search term to filter brand names
          schema:
            type: string
          example: cola
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
          example: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return
          schema:
            type: integer
            default: 100
          example: 100
      responses:
        '200':
          description: Brands listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandListResponse'
              examples:
                ListBrands200Example:
                  summary: Default listBrands 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - brand_id: brand-500123
                        name: Example Cola
                        manufacturer: Example Corp
                        category: Carbonated Beverages
                        upc_count: 45
                    pagination:
                      offset: 0
                      limit: 100
                      total: 320
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /brands/{brand_id}:
    get:
      operationId: getBrand
      summary: Circana Get Brand Details
      description: >-
        Get detailed brand information including manufacturer, UPC catalog,
        and available data coverage.
      tags:
        - Brands
      parameters:
        - name: brand_id
          in: path
          required: true
          description: Unique brand identifier
          schema:
            type: string
          example: brand-500123
      responses:
        '200':
          description: Brand details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandDetail'
              examples:
                GetBrand200Example:
                  summary: Default getBrand 200 response
                  x-microcks-default: true
                  value:
                    brand_id: brand-500123
                    name: Example Cola
                    manufacturer: Example Corp
                    categories:
                      - Carbonated Beverages
                    upc_count: 45
                    market_presence:
                      channels: 6
                      retailers: 120
                      geographic_coverage: national
        '404':
          description: Brand not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /retailers:
    get:
      operationId: listRetailers
      summary: Circana List Retailers
      description: >-
        List retailers covered in Circana's measurement universe with channel
        classification and coverage data.
      tags:
        - Retailers
      parameters:
        - name: channel
          in: query
          required: false
          description: Retail channel filter
          schema:
            type: string
            enum:
              - grocery
              - mass
              - club
              - dollar
              - convenience
              - drug
              - online
              - specialty
          example: grocery
        - name: search
          in: query
          required: false
          description: Search term to filter retailer names
          schema:
            type: string
          example: market
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
          example: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return
          schema:
            type: integer
            default: 100
          example: 100
      responses:
        '200':
          description: Retailers listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailerListResponse'
              examples:
                ListRetailers200Example:
                  summary: Default listRetailers 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - retailer_id: ret-500123
                        name: Example Market
                        channel: grocery
                        store_count: 450
                        geographic_coverage: national
                    pagination:
                      offset: 0
                      limit: 100
                      total: 1100
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports:
    get:
      operationId: listReports
      summary: Circana List Reports
      description: >-
        List available reports and saved analyses for the authenticated user.
      tags:
        - Reports
      parameters:
        - name: status
          in: query
          required: false
          description: Report status filter
          schema:
            type: string
            enum:
              - draft
              - processing
              - completed
              - failed
          example: completed
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
          example: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return
          schema:
            type: integer
            default: 100
          example: 100
      responses:
        '200':
          description: Reports listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportListResponse'
              examples:
                ListReports200Example:
                  summary: Default listReports 200 response
                  x-microcks-default: true
                  value:
                    data:
                      - report_id: rpt-500123
                        name: Q1 2026 Beverage Market Review
                        status: completed
                        created_at: '2026-04-01T10:00:00Z'
                        category: Beverages
                        report_type: market_review
                    pagination:
                      offset: 0
                      limit: 100
                      total: 25
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createReport
      summary: Circana Create Report
      description: >-
        Create a new report with specified data parameters, categories, and
        analysis configuration.
      tags:
        - Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReportRequest'
            examples:
              CreateReportRequestExample:
                summary: Default createReport request
                x-microcks-default: true
                value:
                  name: Q1 2026 Snacks Performance
                  report_type: market_review
                  category_id: cpg-snacks
                  start_date: '2026-01-01'
                  end_date: '2026-03-31'
                  geography: national
                  metrics:
                    - dollar_sales
                    - unit_sales
                    - market_share
      responses:
        '201':
          description: Report created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDetail'
              examples:
                CreateReport201Example:
                  summary: Default createReport 201 response
                  x-microcks-default: true
                  value:
                    report_id: rpt-500124
                    name: Q1 2026 Snacks Performance
                    status: processing
                    created_at: '2026-04-18T12:00:00Z'
                    estimated_completion: '2026-04-18T12:05:00Z'
        '400':
          description: Invalid report configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports/{report_id}:
    get:
      operationId: getReport
      summary: Circana Get Report Details
      description: >-
        Get detailed information about a specific report including status,
        configuration, and results.
      tags:
        - Reports
      parameters:
        - name: report_id
          in: path
          required: true
          description: Unique report identifier
          schema:
            type: string
          example: rpt-500123
      responses:
        '200':
          description: Report details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportDetail'
              examples:
                GetReport200Example:
                  summary: Default getReport 200 response
                  x-microcks-default: true
                  value:
                    report_id: rpt-500123
                    name: Q1 2026 Beverage Market Review
                    status: completed
                    created_at: '2026-04-01T10:00:00Z'
                    completed_at: '2026-04-01T10:03:00Z'
                    category: Beverages
                    report_type: market_review
                    row_count: 4523
        '404':
          description: Report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /exports:
    post:
      operationId: createExport
      summary: Circana Create Data Export
      description: >-
        Create a data export job to download market data, consumer panel data,
        or report results in CSV, Excel, or JSON format.
      tags:
        - Exports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportRequest'
            examples:
              CreateExportRequestExample:
                summary: Default createExport request
                x-microcks-default: true
                value:
                  source_type: report
                  source_id: rpt-500123
                  format: csv
                  include_headers: true
      responses:
        '201':
          description: Export job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportDetail'
              examples:
                CreateExport201Example:
                  summary: Default createExport 201 response
                  x-microcks-default: true
                  value:
                    export_id: exp-500123
                    status: processing
                    format: csv
                    created_at: '2026-04-18T12:00:00Z'
        '400':
          description: Invalid export configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication credentials missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /exports/{export_id}:
    get:
      operationId: getExport
      summary: Circana Get Export Status
      description: >-
        Check the status of a data export job and retrieve the download URL
        when complete.
      tags:
        - Exports
      parameters:
        - name: export_id
          in: path
          required: true
          description: Unique export identifier
          schema:
            type: string
          example: exp-500123
      responses:
        '200':


# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/circana/refs/heads/main/openapi/circana-liquid-data.yaml