Youtube Analytics Groups API

openapi: 3.1.0
info:
  title: YouTube Analytics Analytics Groups API
  description: 'The YouTube Analytics API enables you to retrieve YouTube Analytics data for channels and content owners.

    Use this API to generate custom analytics reports, track video performance metrics, monitor audience engagement,

    and gain insights into viewer demographics and behavior patterns.


    ## Key Features

    - Retrieve channel and video performance metrics

    - Access audience demographics and geographic data

    - Monitor engagement metrics like likes, comments, and shares

    - Track revenue and ad performance data (for monetized content)

    - Generate custom date-range reports


    ## Authentication

    All API requests require OAuth 2.0 authentication with appropriate scopes.

    '
  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 Groups
  description: Operations for managing analytics group definitions
paths:
  /groups:
    get:
      tags:
      - Analytics Groups
      operationId: listAnalyticsGroups
      summary: Youtube List Analytics Groups
      description: 'Returns a collection of analytics groups that match the API request parameters.

        Groups allow you to aggregate data for multiple channels or videos to analyze

        combined performance metrics.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupListExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupId'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/AccessToken'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: Successful response containing list of analytics groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
              examples:
                SuccessfulGroupListExample:
                  $ref: '#/components/examples/SuccessfulGroupListExample'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
    post:
      tags:
      - Analytics Groups
      operationId: createAnalyticsGroup
      summary: Youtube Create Analytics Group
      description: 'Creates a new analytics group. Groups enable you to aggregate analytics data

        for multiple channels or videos, making it easier to analyze combined

        performance across related content.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
            examples:
              GroupCreateRequestExample:
                $ref: '#/components/examples/GroupCreateRequestExample'
      responses:
        '200':
          description: Successfully created analytics group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                SuccessfulGroupCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupCreateExample'
        '400':
          description: Bad request - invalid group data
          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'
  /groups/{groupId}:
    get:
      tags:
      - Analytics Groups
      operationId: getAnalyticsGroup
      summary: Youtube Get Analytics Group
      description: 'Retrieves a specific analytics group by its unique identifier.

        Returns detailed information about the group including its title,

        content details, and associated metadata.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: Successful response containing the analytics group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                SuccessfulGroupCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupCreateExample'
        '404':
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
    put:
      tags:
      - Analytics Groups
      operationId: updateAnalyticsGroup
      summary: Youtube Update Analytics Group
      description: 'Updates an existing analytics group. You can modify the group''s title

        and other editable properties. The group ID cannot be changed.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupUpdateRequest'
            examples:
              GroupUpdateRequestExample:
                $ref: '#/components/examples/GroupUpdateRequestExample'
      responses:
        '200':
          description: Successfully updated analytics group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                SuccessfulGroupCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupCreateExample'
        '400':
          description: Bad request - invalid update data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestErrorExample:
                  $ref: '#/components/examples/BadRequestErrorExample'
        '404':
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
    delete:
      tags:
      - Analytics Groups
      operationId: deleteAnalyticsGroup
      summary: Youtube Delete Analytics Group
      description: 'Deletes an analytics group. This action is permanent and cannot be undone.

        All group items associated with the group will also be removed.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully deleted the analytics group
        '404':
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
components:
  examples:
    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
    SuccessfulGroupListExample:
      summary: Successful group list response
      description: Example response containing analytics groups
      value:
        kind: youtube#groupListResponse
        etag: abc123def456
        items:
        - kind: youtube#group
          etag: xyz789abc123
          id: ABCdef123456
          snippet:
            title: Top Performing Videos Q1 2024
            publishedAt: '2024-01-15T10:30:00Z'
          contentDetails:
            itemCount: 25
            itemType: youtube#video
        - kind: youtube#group
          etag: mno456pqr789
          id: GHIjkl789012
          snippet:
            title: Channel Performance Tracking
            publishedAt: '2024-02-01T14:00:00Z'
          contentDetails:
            itemCount: 5
            itemType: youtube#channel
    NotFoundErrorExample:
      summary: Not found error
      description: Example error response when resource is not found
      value:
        error:
          code: 404
          message: Resource not found
          errors:
          - domain: youtube.analytics
            reason: notFound
            message: The specified group was not found
            locationType: parameter
            location: groupId
    SuccessfulGroupCreateExample:
      summary: Successfully created group
      description: Example response for a newly created analytics group
      value:
        kind: youtube#group
        etag: newgroup123
        id: NEWgroup456789
        snippet:
          title: My New Analytics Group
          publishedAt: '2024-03-01T09:00:00Z'
        contentDetails:
          itemCount: 0
          itemType: youtube#video
    GroupUpdateRequestExample:
      summary: Group update request
      description: Example request body for updating an analytics group
      value:
        id: ABCdef123456
        snippet:
          title: Updated Analytics Group Name
    GroupCreateRequestExample:
      summary: Group creation request
      description: Example request body for creating a new analytics group
      value:
        snippet:
          title: My New Analytics Group
        contentDetails:
          itemType: youtube#video
    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
  schemas:
    GroupListResponse:
      type: object
      description: Response containing a list of analytics groups
      required:
      - kind
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#groupListResponse
        etag:
          type: string
          description: ETag for caching purposes
        items:
          type: array
          description: List of analytics groups
          items:
            $ref: '#/components/schemas/Group'
        nextPageToken:
          type: string
          description: Token to retrieve the next page of results
    GroupSnippet:
      type: object
      description: Basic information about an analytics group
      required:
      - title
      - publishedAt
      properties:
        title:
          type: string
          description: The title of the group
          example: Top Performing Videos Q1 2024
        publishedAt:
          type: string
          format: date-time
          description: When the group was created
          example: '2024-01-15T10:30:00Z'
    GroupContentDetails:
      type: object
      description: Content details for an analytics group
      required:
      - itemCount
      - itemType
      properties:
        itemCount:
          type: integer
          description: Number of items in the group
          example: 25
        itemType:
          type: string
          description: Type of items in the group
          enum:
          - youtube#channel
          - youtube#video
          example: youtube#video
    ErrorResponse:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    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'
    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
    GroupUpdateRequest:
      type: object
      description: Request body for updating an analytics group
      required:
      - id
      - snippet
      properties:
        id:
          type: string
          description: The ID of the group to update
          example: ABCdef123456
        snippet:
          type: object
          required:
          - title
          properties:
            title:
              type: string
              description: The updated title for the group
              example: Updated Analytics Group Name
    GroupCreateRequest:
      type: object
      description: Request body for creating a new analytics group
      required:
      - snippet
      - contentDetails
      properties:
        snippet:
          type: object
          required:
          - title
          properties:
            title:
              type: string
              description: The title for the new group
              example: My New Analytics Group
        contentDetails:
          type: object
          required:
          - itemType
          properties:
            itemType:
              type: string
              description: Type of items the group will contain
              enum:
              - youtube#channel
              - youtube#video
              example: youtube#video
    Group:
      type: object
      description: An analytics group for aggregating channel or video data
      required:
      - kind
      - id
      - snippet
      - contentDetails
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#group
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the group
          example: ABCdef123456
        snippet:
          $ref: '#/components/schemas/GroupSnippet'
        contentDetails:
          $ref: '#/components/schemas/GroupContentDetails'
  parameters:
    AccessToken:
      name: access_token
      in: query
      required: false
      description: OAuth 2.0 access token for authentication
      schema:
        type: string
    GroupId:
      name: id
      in: query
      required: false
      description: The unique identifier of an analytics group to retrieve
      schema:
        type: string
        example: ABCdef123456
    PageToken:
      name: pageToken
      in: query
      required: false
      description: Token for retrieving the next page of results
      schema:
        type: string
    PrettyPrint:
      name: prettyPrint
      in: query
      required: false
      description: Returns response with indentations and line breaks for readability
      schema:
        type: boolean
        default: true
    GroupIdPath:
      name: groupId
      in: path
      required: true
      description: The unique identifier of the analytics group
      schema:
        type: string
        example: ABCdef123456
    OnBehalfOfContentOwner:
      name: onBehalfOfContentOwner
      in: query
      required: false
      description: 'The content owner ID for YouTube content owner operations.

        Required for content owner authenticated requests.

        '
      schema:
        type: string
        example: ContentOwnerXYZ
  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