Youtube Analytics Reports API

openapi: 3.2.0
info:
  title: YouTube Analytics Analytics Reports API
  description: The YouTube Analytics API enables you to retrieve YouTube Analytics data for channels and content owners.
  version: 2.0.0
  contact:
    name: Google Developers
    url: https://developers.google.com/youtube/analytics
    email: youtube-api-support@google.com
  license:
    name: Creative Commons Attribution 3.0
    url: http://creativecommons.org/licenses/by/3.0/
    identifier: CC-BY-3.0
  termsOfService: https://developers.google.com/terms/
  x-logo:
    url: https://www.youtube.com/img/desktop/yt_1200.png
servers:
- url: https://youtubeanalytics.googleapis.com/v2
  description: YouTube Analytics API Production Server
security:
- OAuth2:
  - https://www.googleapis.com/auth/yt-analytics.readonly
tags:
- name: Analytics Reports
  description: Operations for retrieving YouTube Analytics reports and metrics
paths:
  /reports:
    get:
      tags:
      - Analytics Reports
      operationId: getAnalyticsReports
      summary: Retrieve YouTube Analytics Reports
      description: 'Retrieves YouTube Analytics data for a channel or content owner.

        The API response contains a report with the requested dimensions and metrics

        for the specified date range. You can filter results by various dimensions

        such as video, country, or traffic source.'
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulAnalyticsReportExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/Metrics'
      - $ref: '#/components/parameters/Dimensions'
      - $ref: '#/components/parameters/Filters'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/MaxResults'
      - $ref: '#/components/parameters/StartIndex'
      - $ref: '#/components/parameters/Currency'
      - $ref: '#/components/parameters/AccessToken'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: Successful response containing analytics report data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsReportResponse'
              examples:
                SuccessfulAnalyticsReportExample:
                  $ref: '#/components/examples/SuccessfulAnalyticsReportExample'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestErrorExample:
                  $ref: '#/components/examples/BadRequestErrorExample'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ForbiddenErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
components:
  parameters:
    Dimensions:
      name: dimensions
      in: query
      required: false
      description: 'A comma-separated list of YouTube Analytics dimensions.

        Common dimensions include video, channel, country, day, month.

        '
      schema:
        type: string
        example: video,day
    StartDate:
      name: startDate
      in: query
      required: true
      description: The start date for the data retrieval in YYYY-MM-DD format
      schema:
        type: string
        format: date
        example: '2024-01-01'
    Ids:
      name: ids
      in: query
      required: true
      description: 'Identifies the YouTube channel or content owner for which you are retrieving

        YouTube Analytics data. Use channel==CHANNEL_ID or contentOwner==CONTENT_OWNER_ID.

        '
      schema:
        type: string
        example: channel==UC_x5XG1OV2P6uZZ5FSM9Ttw
    MaxResults:
      name: maxResults
      in: query
      required: false
      description: Maximum number of rows to include in the response (1-500)
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
        example: 50
    PrettyPrint:
      name: prettyPrint
      in: query
      required: false
      description: Returns response with indentations and line breaks for readability
      schema:
        type: boolean
        default: true
    Currency:
      name: currency
      in: query
      required: false
      description: Currency code for revenue metrics (ISO 4217)
      schema:
        type: string
        pattern: ^[A-Z]{3}$
        example: USD
    Filters:
      name: filters
      in: query
      required: false
      description: 'A list of filters to apply to the data. Filters use the format dimension==value

        and can be combined with semicolons.

        '
      schema:
        type: string
        example: country==US;video==dQw4w9WgXcQ
    EndDate:
      name: endDate
      in: query
      required: true
      description: The end date for the data retrieval in YYYY-MM-DD format
      schema:
        type: string
        format: date
        example: '2024-01-31'
    StartIndex:
      name: startIndex
      in: query
      required: false
      description: Index of the first row to retrieve (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1
    Sort:
      name: sort
      in: query
      required: false
      description: 'A comma-separated list of dimensions or metrics to sort by.

        Prefix with - for descending order.

        '
      schema:
        type: string
        example: -views
    AccessToken:
      name: access_token
      in: query
      required: false
      description: OAuth 2.0 access token for authentication
      schema:
        type: string
    Metrics:
      name: metrics
      in: query
      required: true
      description: 'A comma-separated list of YouTube Analytics metrics to retrieve.

        Common metrics include views, estimatedMinutesWatched, averageViewDuration, likes, dislikes, comments, shares.

        '
      schema:
        type: string
        example: views,estimatedMinutesWatched,averageViewDuration,likes
  schemas:
    ErrorItem:
      type: object
      description: Individual error detail
      properties:
        domain:
          type: string
          description: Error domain
          example: youtube.analytics
        reason:
          type: string
          description: Error reason code
          example: invalidParameter
        message:
          type: string
          description: Detailed error message
          example: The parameter 'startDate' has an invalid value
        locationType:
          type: string
          description: Type of location where error occurred
          example: parameter
        location:
          type: string
          description: Specific location of the error
          example: startDate
    AnalyticsReportResponse:
      type: object
      description: Response object containing YouTube Analytics report data
      required:
      - kind
      - columnHeaders
      - rows
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtubeAnalytics#resultTable
        columnHeaders:
          type: array
          description: Column header definitions for the report data
          items:
            $ref: '#/components/schemas/ColumnHeader'
        rows:
          type: array
          description: Data rows containing the requested metrics and dimensions
          items:
            type: array
            items:
              oneOf:
              - type: string
              - type: number
              - type: integer
    ErrorDetails:
      type: object
      description: Details about an API error
      required:
      - code
      - message
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Human-readable error message
          example: Invalid parameter value
        errors:
          type: array
          description: List of specific errors
          items:
            $ref: '#/components/schemas/ErrorItem'
    ColumnHeader:
      type: object
      description: Defines a column in the analytics report
      required:
      - name
      - columnType
      - dataType
      properties:
        name:
          type: string
          description: The name of the dimension or metric
          example: views
        columnType:
          type: string
          description: Whether the column is a dimension or metric
          enum:
          - DIMENSION
          - METRIC
          example: METRIC
        dataType:
          type: string
          description: The data type of the column values
          enum:
          - STRING
          - INTEGER
          - FLOAT
          example: INTEGER
    ErrorResponse:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
  examples:
    BadRequestErrorExample:
      summary: Bad request error
      description: Example error response for invalid parameters
      value:
        error:
          code: 400
          message: Invalid parameter value
          errors:
          - domain: youtube.analytics
            reason: invalidParameter
            message: The parameter 'startDate' has an invalid value
            locationType: parameter
            location: startDate
    SuccessfulAnalyticsReportExample:
      summary: Successful analytics report response
      description: Example response containing video views and engagement metrics
      value:
        kind: youtubeAnalytics#resultTable
        columnHeaders:
        - name: video
          columnType: DIMENSION
          dataType: STRING
        - name: views
          columnType: METRIC
          dataType: INTEGER
        - name: estimatedMinutesWatched
          columnType: METRIC
          dataType: FLOAT
        - name: averageViewDuration
          columnType: METRIC
          dataType: FLOAT
        - name: likes
          columnType: METRIC
          dataType: INTEGER
        rows:
        - - dQw4w9WgXcQ
          - 1500000
          - 3750000.5
          - 150.2
          - 45000
        - - abc123XYZ789
          - 500000
          - 1000000.0
          - 120.0
          - 15000
    ForbiddenErrorExample:
      summary: Forbidden error
      description: Example error response for insufficient permissions
      value:
        error:
          code: 403
          message: Access forbidden
          errors:
          - domain: youtube.analytics
            reason: forbidden
            message: The authenticated user does not have permission to access this resource
            locationType: header
            location: Authorization
    UnauthorizedErrorExample:
      summary: Unauthorized error
      description: Example error response for authentication failure
      value:
        error:
          code: 401
          message: Invalid credentials
          errors:
          - domain: youtube.analytics
            reason: authError
            message: The access token is invalid or expired
            locationType: header
            location: Authorization
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for YouTube Analytics API
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/youtube: Manage your YouTube account
            https://www.googleapis.com/auth/youtube.readonly: View your YouTube account
            https://www.googleapis.com/auth/yt-analytics.readonly: View YouTube Analytics reports
            https://www.googleapis.com/auth/yt-analytics-monetary.readonly: View YouTube Analytics monetary reports
externalDocs:
  description: YouTube Analytics API Documentation
  url: https://developers.google.com/youtube/analytics