openapi: 3.0.1
info:
  title: Explore API
  description: >-
    TelmarHelixa Explore / Crosstab API. Bring trusted syndicated survey intelligence into your
    applications — crosstab one population base and up to two target codes against a licensed survey.


    Commercial terms (pricing, contract length, volume commitments) are not published here. Contact
    Sales.
  version: 1.0.0
  summary: Explore / Crosstab API
  contact:
    name: TelmarHelixa Sales
    email: sales@telmar.com
  license:
    name: Commercial licence — terms provided by Sales
    identifier: LicenseRef-Commercial
servers:
  - url: https://engines.api.telmar.com/omg/prd/v1
paths:
  /docs:
    get:
      tags:
        - EngineCalls
      summary: The openAPI specification in json format (This Document as json)
      description: >-
        Returns the full OpenAPI specification for this service as a JSON object.
        Useful for programmatic discovery of the API schema. No authentication is required.
      operationId: docs
      responses:
        "200":
          description: The openAPI specification in json format (This Document as json)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"
  /crosstab:
    post:
      tags:
        - EngineCalls
      requestBody:
        description: OMG - Crosstab request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OMGCrosstabRequest"
            examples:
              sample OMG crosstab request:
                description: This is a basic OMG crosstab request for 2 targets and 1 one population base
                value:
                  SurveyCode: M20F
                  AuthorizationGroup: _ALL_
                  PopulationBaseCode: AR18_24
                  TargetCodes:
                    - OMEN
                    - OWOMEN
        required: true
      responses:
        "200":
          description: OMG - Crosstab Response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OMGCrosstabResponse"
              examples:
                sample OMG crosstab response:
                  description: This is a basic OMG crosstab response for 2 targets and 1 one population base
                  value:
                    ResultCode: 0
                    ResultDescription: ""
                    Results:
                      - Resps: 1000
                        WgtAud: 10000
                        Stbl: 0
                      - Resps: 123
                        WgtAud: 4444
                        Stbl: 1
                    AudienceReportUnits: 1000
        "400":
          description: The request was understood but rejected — usually more than two TargetCodes, a missing
            required field, or an unknown survey/target code.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: The Telmar-Engine-Authorizer header is missing, malformed or expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: The authorizer is valid but the caller is not entitled to the requested survey or
            authorization group.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - Telmar-Lambda-Authorizer: []
      operationId: crosstab
      summary: Executes a crosstab query
      description: >-
        Executes a crosstab query against a specified survey dataset. Returns weighted
        audience counts, unweighted respondent counts, and stability indicators for each
        requested target code.
    options:
      tags:
        - PreflightChecks
      responses:
        "200":
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Empty"
      operationId: crosstabOptions
      summary: CORS pre-flight for crosstab
      description: Pre-flight check. Returns CORS allow headers for browser-based callers.
components:
  schemas:
    Empty:
      title: Empty Schema
      type: object
    OMGCrosstabRequest:
      required:
        - PopulationBaseCode
        - SurveyCode
        - TargetCodes
      type: object
      properties:
        SurveyCode:
          type: string
        PopulationBaseCode:
          type: string
        TargetCodes:
          maxItems: 2
          minItems: 1
          type: array
          items:
            type: string
        AuthorizationGroup:
          type: string
    OMGCrosstabResponse:
      type: object
      properties:
        ResultCode:
          type: integer
        Results:
          maxItems: 2
          minItems: 1
          type: array
          items:
            $ref: "#/components/schemas/OMGCrosstabResult"
        ResultDescription:
          type: string
        AudienceReportUnits:
          type: integer
    OMGCrosstabResult:
      type: object
      properties:
        WgtAud:
          type: number
          description: Weighted number of respondents (Projected Audience)
          format: float
        Resps:
          type: integer
          description: Un-weighted number of respondents for this code.
        Stbl:
          type: integer
          description: |-
            Stability Factor – denotes how stable is this result:
             * `0` - Stable
             * `1` - Unstable
          enum:
            - 0
            - 1
    Error:
      type: object
      required:
        - ResultCode
        - ResultDescription
      properties:
        ResultCode:
          type: integer
          description: Non-zero on failure.
        ResultDescription:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            field:
              type: string
            hint:
              type: string
  securitySchemes:
    Telmar-Lambda-Authorizer:
      type: apiKey
      name: Telmar-Engine-Authorizer
      in: header
