Youtube Group Items API

openapi: 3.1.0
info:
  title: YouTube Analytics Analytics Groups Group Items 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: Group Items
  description: Operations for managing items within analytics groups
paths:
  /groupItems:
    get:
      tags:
      - Group Items
      operationId: listGroupItems
      summary: Youtube List Group Items
      description: 'Returns a collection of group items that match the API request parameters.

        Group items represent the individual channels or videos that belong to

        an analytics group.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupItemListExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/GroupIdQuery'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      - $ref: '#/components/parameters/PrettyPrint'
      responses:
        '200':
          description: Successful response containing list of group items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupItemListResponse'
              examples:
                SuccessfulGroupItemListExample:
                  $ref: '#/components/examples/SuccessfulGroupItemListExample'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
    post:
      tags:
      - Group Items
      operationId: createGroupItem
      summary: Youtube Add Item to Group
      description: 'Adds a channel or video to an analytics group. The item will be included

        in the group''s aggregated analytics data going forward.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulGroupItemCreateExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupItemCreateRequest'
            examples:
              GroupItemCreateRequestExample:
                $ref: '#/components/examples/GroupItemCreateRequestExample'
      responses:
        '200':
          description: Successfully added item to group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupItem'
              examples:
                SuccessfulGroupItemCreateExample:
                  $ref: '#/components/examples/SuccessfulGroupItemCreateExample'
        '400':
          description: Bad request - invalid item data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestErrorExample:
                  $ref: '#/components/examples/BadRequestErrorExample'
  /groupItems/{itemId}:
    delete:
      tags:
      - Group Items
      operationId: deleteGroupItem
      summary: Youtube Remove Item from Group
      description: 'Removes a channel or video from an analytics group. The item''s historical

        data will no longer be included in the group''s aggregated metrics.

        '
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: "{\n  \"dispatcher\": \"FALLBACK\",\n  \"fallback\": \"SuccessfulDeleteExample\"\n}\n"
      parameters:
      - $ref: '#/components/parameters/ItemIdPath'
      - $ref: '#/components/parameters/OnBehalfOfContentOwner'
      - $ref: '#/components/parameters/AccessToken'
      responses:
        '204':
          description: Successfully removed item from group
        '404':
          description: Item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundErrorExample:
                  $ref: '#/components/examples/NotFoundErrorExample'
components:
  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
    SuccessfulGroupItemCreateExample:
      summary: Successfully added item to group
      description: Example response for a newly added group item
      value:
        kind: youtube#groupItem
        etag: newitem789
        id: NEWitem123456
        groupId: ABCdef123456
        resource:
          kind: youtube#video
          id: dQw4w9WgXcQ
    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
    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
    SuccessfulGroupItemListExample:
      summary: Successful group items list response
      description: Example response containing items in an analytics group
      value:
        kind: youtube#groupItemListResponse
        etag: items123abc
        items:
        - kind: youtube#groupItem
          etag: item1abc
          id: ITEMabc123
          groupId: ABCdef123456
          resource:
            kind: youtube#video
            id: dQw4w9WgXcQ
        - kind: youtube#groupItem
          etag: item2def
          id: ITEMdef456
          groupId: ABCdef123456
          resource:
            kind: youtube#video
            id: abc123XYZ789
    GroupItemCreateRequestExample:
      summary: Add item to group request
      description: Example request body for adding an item to a group
      value:
        groupId: ABCdef123456
        resource:
          kind: youtube#video
          id: dQw4w9WgXcQ
  schemas:
    GroupItemCreateRequest:
      type: object
      description: Request body for adding an item to a group
      required:
      - groupId
      - resource
      properties:
        groupId:
          type: string
          description: ID of the group to add the item to
          example: ABCdef123456
        resource:
          type: object
          required:
          - kind
          - id
          properties:
            kind:
              type: string
              description: Type of resource to add
              enum:
              - youtube#channel
              - youtube#video
              example: youtube#video
            id:
              type: string
              description: YouTube ID of the channel or video
              example: dQw4w9WgXcQ
    GroupItemListResponse:
      type: object
      description: Response containing a list of group items
      required:
      - kind
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#groupItemListResponse
        etag:
          type: string
          description: ETag for caching purposes
        items:
          type: array
          description: List of group items
          items:
            $ref: '#/components/schemas/GroupItem'
    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
    GroupItem:
      type: object
      description: An item (channel or video) within an analytics group
      required:
      - kind
      - id
      - groupId
      - resource
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#groupItem
        etag:
          type: string
          description: ETag for caching purposes
        id:
          type: string
          description: Unique identifier for the group item
          example: XYZ789abc123
        groupId:
          type: string
          description: ID of the group this item belongs to
          example: ABCdef123456
        resource:
          $ref: '#/components/schemas/GroupItemResource'
    GroupItemResource:
      type: object
      description: Resource information for a group item
      required:
      - kind
      - id
      properties:
        kind:
          type: string
          description: Type of resource
          enum:
          - youtube#channel
          - youtube#video
          example: youtube#video
        id:
          type: string
          description: YouTube ID of the channel or video
          example: dQw4w9WgXcQ
  parameters:
    AccessToken:
      name: access_token
      in: query
      required: false
      description: OAuth 2.0 access token for authentication
      schema:
        type: string
    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
    ItemIdPath:
      name: itemId
      in: path
      required: true
      description: The unique identifier of the group item
      schema:
        type: string
        example: XYZ789abc123
    PrettyPrint:
      name: prettyPrint
      in: query
      required: false
      description: Returns response with indentations and line breaks for readability
      schema:
        type: boolean
        default: true
    GroupIdQuery:
      name: groupId
      in: query
      required: true
      description: The group ID to retrieve items for
      schema:
        type: string
        example: ABCdef123456
  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