openapi: 3.0.0
info:
  title: The Statista Data API
  contact:
    name: API Support
    email: api@statista.com
  version: 2.8.0
  description: The Statista Data API provides access to statistical data, market-insights data and reports
tags: []
paths:
  /v1/data/consumer-insights:
    get:
      operationId: consumerInsights
      parameters:
        - name: rows
          in: query
          required: true
          description: The question or answer ID from a survey to select data for the crosstable.
          schema:
            type: string
          explode: false
        - name: columns
          in: query
          required: false
          description: The question or answer ID from a survey to select data for the crosstable.
          schema:
            type: string
          explode: false
        - name: filters
          in: query
          required: false
          description: Comma-separated list of answer IDs. Enables filtering respondents by target group.
          schema:
            type: string
          explode: false
        - name: country
          in: query
          required: false
          description: Single, 3 letter, ISO 3166-1 alpha-3 country code, such as 'USA' or 'GBR', to target a specific country.
          schema:
            type: string
            minLength: 3
            maxLength: 3
          explode: false
        - name: year
          in: query
          required: false
          description: 'Survey year as 4 digit value, default: current year'
          schema:
            type: integer
            format: uint16
            minimum: 1900
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api.Response.Data.ConsumerInsightsDataResponse'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '401':
          description: Access is unauthorized.
        '403':
          description: Access is forbidden.
        '404':
          description: The server cannot find the requested resource.
  /v1/data/market-insights/indicator:
    get:
      operationId: marketInsights
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of the Market Insights indicator to be retrieved.
          schema:
            type: string
            format: uuid
          explode: false
        - name: geo
          in: query
          required: false
          description: "Comma-separated list of geo codes. Max items: 5.  Available geo codes per indicator are part of the search result. Defaults to 'WLD'"
          schema:
            type: string
            default: WLD
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api.Response.Data.MarketInsightsIndicator'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '401':
          description: Access is unauthorized.
        '403':
          description: Access is forbidden.
        '404':
          description: The server cannot find the requested resource.
  /v1/data/report:
    get:
      operationId: report
      description: Returns the Report file as binary data
      parameters:
        - name: t
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          explode: false
      responses:
        '200':
          description: The request has succeeded.
        '400':
          description: The server could not understand the request due to invalid syntax.
        '401':
          description: Access is unauthorized.
        '403':
          description: Access is forbidden.
        '404':
          description: The server cannot find the requested resource.
  /v1/data/reports:
    get:
      operationId: reports
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of a content information to be retrieved.
          schema:
            $ref: '#/components/schemas/Type.Id'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsResponse'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '401':
          description: Access is unauthorized.
        '403':
          description: Access is forbidden.
        '404':
          description: The server cannot find the requested resource.
  /v1/data/statistic:
    get:
      operationId: statistic
      parameters:
        - name: id
          in: query
          required: true
          description: The unique identifier of a content information to be retrieved.
          schema:
            $ref: '#/components/schemas/Type.Id'
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api.Data.Response.Statistic'
        '400':
          description: The server could not understand the request due to invalid syntax.
        '401':
          description: Access is unauthorized.
        '403':
          description: Access is forbidden.
        '404':
          description: The server cannot find the requested resource.
security:
  - ApiKeyAuth: []
components:
  schemas:
    Api.Data.Response.Chart:
      type: object
      required:
        - graphType
        - horizontal
        - data
      properties:
        unit:
          type: string
        graphType:
          $ref: '#/components/schemas/Api.Data.Response.GraphType'
        description:
          type: string
        horizontal:
          type: boolean
        data:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Api.Data.Response.DataPoint'
    Api.Data.Response.DataPoint:
      type: object
      required:
        - data
      properties:
        data:
          anyOf:
            - type: string
            - type: number
            - type: integer
              format: int32
        name:
          type: string
    Api.Data.Response.GraphType:
      type: string
      enum:
        - annotations
        - bar
        - stacked-areas
        - stacked-bars
        - dual-y-axes
        - line-standard
        - line-zoomable
        - pie
        - table
    Api.Data.Response.Industry:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
        id:
          $ref: '#/components/schemas/Type.IndustryId'
    Api.Data.Response.Region:
      type: object
      required:
        - name
        - code
      properties:
        name:
          type: string
        code:
          type: string
    Api.Data.Response.Source:
      type: object
      required:
        - title
        - subtitle
      properties:
        title:
          type: string
        subtitle:
          type: string
    Api.Data.Response.Statistic:
      type: object
      required:
        - identifier
        - title
        - link
        - date
        - subject
        - is_premium
        - teaser_image_urls
        - platform
        - chart
      properties:
        identifier:
          $ref: '#/components/schemas/Type.Id'
        title:
          type: string
        link:
          type: string
        date:
          type: string
          format: date-time
        subject:
          type: string
        is_premium:
          type: boolean
        description:
          type: string
        teaser_image_urls:
          type: array
          items:
            $ref: '#/components/schemas/Api.Response.TeaserImage'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Api.Data.Response.Source'
        publishers:
          type: array
          items:
            $ref: '#/components/schemas/Api.Data.Response.Source'
        chargers:
          type: array
          items:
            $ref: '#/components/schemas/Api.Data.Response.Source'
        industries:
          type: array
          items:
            $ref: '#/components/schemas/Api.Data.Response.Industry'
        geolocations:
          type: array
          items:
            $ref: '#/components/schemas/Api.Data.Response.Region'
        platform:
          $ref: '#/components/schemas/Type.LanguageLocale'
        image_url:
          type: string
        chart:
          $ref: '#/components/schemas/Api.Data.Response.Chart'
    Api.Response.Data.Chart:
      type: object
      required:
        - description
        - dataFormat
        - valueUnit
        - data
      properties:
        description:
          type: string
          description: A short text or headline that explains the the data.
        dataFormat:
          type: string
          description: The name of the data format in the data poinsts, e.g. 'percentage'.
        valueUnit:
          type: string
          description: Provided the unit/symbol of the numeric values, e.g. '%'.
        data:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Api.Response.Data.ChartData'
          description: List of the actual numeric values in the cross-tabe.
    Api.Response.Data.ChartData:
      type: object
      required:
        - name
        - percentage
        - respondents
      properties:
        name:
          type: string
          description: Name of this data point, which can be used a column name.
        percentage:
          type: number
          format: float
          description: Percentage representation of the absolute value.
        respondents:
          type: integer
          format: uint32
          description: Absolute number of people who responded to the question.
    Api.Response.Data.ConsumerInsightsDataResponse:
      type: object
      required:
        - identifier
        - title
        - subject
        - description
        - link
        - date
        - sources
        - interpretation_hint
        - geolocations
        - chart
      properties:
        identifier:
          allOf:
            - $ref: '#/components/schemas/Api.Response.Data.Identifier'
          description: A composit ID for this cross-table
        title:
          type: string
          description: What is the data about.
        subject:
          type: string
          description: A short summary of what the data shows.
        description:
          type: string
          description: A more comprehensive text, explaining the most important facts about the data.
        link:
          type: string
          description: The website address (URL) where you can see the full content off the survey.
        date:
          type: string
          description: 'The year when data was compiled. Format: YYYY.'
        sources:
          type: array
          items:
            type: string
          description: List of sources, from which was the data derived.
        interpretation_hint:
          type: string
          description: Short description to help LLMs interpret the data.
        geolocations:
          type: array
          items:
            $ref: '#/components/schemas/Api.Response.Data.GeoLocation'
          description: The countries the data is covering.
        chart:
          allOf:
            - $ref: '#/components/schemas/Api.Response.Data.Chart'
          description: Descriptions and the actual numeric data of the cross-table.
    Api.Response.Data.GeoLocation:
      type: object
      required:
        - name
        - code
      properties:
        name:
          type: string
          description: Country name.
        code:
          type: string
          description: 3 letter, ISO 3166-1 alpha-3 country code.
    Api.Response.Data.Identifier:
      type: object
      required:
        - rows
        - survey_id
      properties:
        rows:
          type: string
          description: A question or answer ID.
        columns:
          type: string
          description: A question or answer ID.
        filters:
          type: array
          items:
            type: string
          description: The list of answer IDs used to filter the cross-table.
        survey_id:
          type: string
          description: The survey ID, from which the data was taken to compute the cross-table
    Api.Response.Data.MarketInsightsChart:
      type: object
      required:
        - name
        - graphType
        - data
      properties:
        name:
          type: string
          description: The name of the chart. It tells what the data is about.
        graphType:
          type: string
          description: The default graph rendering type.
        unit:
          type: string
          description: The unit description for the numeric data points.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Api.Response.Data.MarketInsightsChartDataPoint'
          description: The chart data points.
    Api.Response.Data.MarketInsightsChartDataPoint:
      type: object
      required:
        - geo
        - categories
        - series
      properties:
        geo:
          type: string
          description: The geo location covered in this time series.
        categories:
          type: array
          items:
            type: string
          description: The categories / headlines for the time series columns.
        series:
          type: array
          items:
            type: number
            format: float
          description: The numeric values of the time series.
    Api.Response.Data.MarketInsightsIndicator:
      type: object
      required:
        - identifier
        - title
        - description
        - chart
      properties:
        identifier:
          type: string
          description: A unique ID for this indicator. Helps find or refer to this data.
        title:
          type: string
          description: Short headline, what the data is about.
        description:
          type: string
          description: A short text explaining the most important facts in the data.
        market_type:
          type: string
          description: The type of market this data is descrypting.
        market_type_description:
          type: string
          description: A short text that explains what the market is about.
        chart:
          allOf:
            - $ref: '#/components/schemas/Api.Response.Data.MarketInsightsChart'
          description: The chart data, covering one or more geo locations.
    Api.Response.TeaserImage:
      type: object
      required:
        - width
        - src
      properties:
        width:
          type: integer
          format: uint32
          description: The width of the image in pixels.
        src:
          type: string
          description: The image link (URL).
    ReportsResponse:
      type: object
      properties:
        pdf:
          type: string
          description: The PDF file of this Report
        ppt:
          type: string
          description: The PowerPoint file of this Report
        xls:
          type: string
          description: The Excel file of this Report
      description: The request has succeeded.
    Type.Id:
      type: integer
      format: uint64
    Type.IndustryId:
      type: integer
      format: uint16
    Type.LanguageLocale:
      type: string
      enum:
        - de
        - en
        - fr
        - es
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
servers:
  - url: https://api.statista.ai/
    description: Single Server endpoint
    variables: {}