Youtube Search API

openapi: 3.2.0
info:
  title: Youtube Search API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Search across 2 of this provider''s published API definitions: youtube-data-api-openapi.yml, youtube-data-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://www.googleapis.com/youtube/v3
  description: YouTube Data API v3 base server
tags:
- name: Search
  description: Operations for searching YouTube content
paths:
  /search:
    get:
      operationId: youtube.search.list
      summary: Youtube Search Youtube
      description: Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching video, channel, and playlist resources, but you can also configure queries to only retrieve a specific type of resource.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/part'
      - name: q
        in: query
        description: The query term to search for.
        schema:
          type: string
        example: youtube api tutorial
      - name: type
        in: query
        description: Restricts a search query to only retrieve a particular type of resource. Acceptable values are channel, playlist, and video.
        schema:
          type: string
        example: video
      - name: channelId
        in: query
        description: Indicates that the API response should only contain resources created by the channel.
        schema:
          type: string
        example: '500123'
      - name: order
        in: query
        description: Specifies the method that will be used to order resources in the API response. Acceptable values are date, rating, relevance, title, videoCount, and viewCount.
        schema:
          type: string
          enum:
          - date
          - rating
          - relevance
          - title
          - videoCount
          - viewCount
        example: date
      - name: publishedAfter
        in: query
        description: Restricts results to only include resources created at or after the specified time, in RFC 3339 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - name: publishedBefore
        in: query
        description: Restricts results to only include resources created before or at the specified time, in RFC 3339 format.
        schema:
          type: string
          format: date-time
        example: '2026-01-15T10:30:00Z'
      - $ref: '#/components/parameters/maxResults'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: Successful response containing a list of search result resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchListResponse'
              examples:
                YoutubeSearchList200Example:
                  summary: Default youtube.search.list 200 response
                  x-microcks-default: true
                  value:
                    kind: youtube#video
                    etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                    nextPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    prevPageToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
                    regionCode: US
                    pageInfo:
                      totalResults: 42
                      resultsPerPage: 10
                    items:
                    - kind: youtube#video
                      etag: XI7nbFXulYBIpL0ayR_gDh3eu1k
                      id:
                        kind: youtube#video
                        videoId: '500123'
                        channelId: '500123'
                        playlistId: '500123'
                      snippet:
                        publishedAt: '2026-01-15T10:30:00Z'
                        channelId: '500123'
                        title: Example Title
                        description: A sample description for this resource.
                        thumbnails: example_value
                        channelTitle: example_value
                        liveBroadcastContent: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - oauth2:
        - https://www.googleapis.com/auth/youtube
      - apiKey: []
    servers:
    - url: https://www.googleapis.com/youtube/v3
      description: YouTube Data API v3 base server
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The request was authenticated but the caller does not have permission to perform the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The request was not authenticated or the credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    maxResults:
      name: maxResults
      in: query
      description: The maximum number of items that should be returned in the result set. Acceptable values are 0 to 50, inclusive.
      schema:
        type: integer
        minimum: 0
        maximum: 50
        default: 5
    pageToken:
      name: pageToken
      in: query
      description: Identifies a specific page in the result set that should be returned. In an API response, the nextPageToken and prevPageToken properties identify other pages available.
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: Selector specifying which fields to include in a partial response. Use this parameter to reduce bandwidth usage by selecting only the fields you need.
      schema:
        type: string
    key:
      name: key
      in: query
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
      schema:
        type: string
    part:
      name: part
      in: query
      required: true
      description: Specifies a comma-separated list of one or more resource properties that the API response will include. The part parameter value must include the id property.
      schema:
        type: string
    Part:
      name: part
      in: query
      required: true
      description: 'The part parameter specifies a comma-separated list of one or more

        resource properties that the API response will include.

        '
      schema:
        type: string
        example: snippet,contentDetails,statistics
    ApiKey:
      name: key
      in: query
      required: false
      description: API key for authentication (for read-only operations)
      schema:
        type: string
    MaxResultsSearch:
      name: maxResults
      in: query
      required: false
      description: Maximum number of items to return (0-50)
      schema:
        type: integer
        minimum: 0
        maximum: 50
        default: 25
        example: 10
    SearchType:
      name: type
      in: query
      required: false
      description: Restricts a search to a particular type of resource
      schema:
        type: string
        enum:
        - video
        - channel
        - playlist
        example: video
    PageToken:
      name: pageToken
      in: query
      required: false
      description: Token for retrieving the next page of results
      schema:
        type: string
    SearchQuery:
      name: q
      in: query
      required: false
      description: The search query term to search for
      schema:
        type: string
        example: openapi tutorial
    ChannelId:
      name: channelId
      in: query
      required: false
      description: Filter results to only include resources from this channel
      schema:
        type: string
        example: UC_x5XG1OV2P6uZZ5FSM9Ttw
    RegionCode:
      name: regionCode
      in: query
      required: false
      description: ISO 3166-1 alpha-2 country code for regional filtering
      schema:
        type: string
        pattern: ^[A-Z]{2}$
        example: US
    PublishedBefore:
      name: publishedBefore
      in: query
      required: false
      description: Filter results to only include resources created before this date
      schema:
        type: string
        format: date-time
        example: '2024-12-31T23:59:59Z'
    Order:
      name: order
      in: query
      required: false
      description: The method to use for sorting search results
      schema:
        type: string
        enum:
        - date
        - rating
        - relevance
        - title
        - videoCount
        - viewCount
        default: relevance
        example: viewCount
    PublishedAfter:
      name: publishedAfter
      in: query
      required: false
      description: Filter results to only include resources created after this date
      schema:
        type: string
        format: date-time
        example: '2024-01-01T00:00:00Z'
  schemas:
    ErrorResponse:
      type: object
      description: A standard error response returned by the YouTube Data API.
      properties:
        error:
          type: object
          description: The error details.
          properties:
            code:
              type: integer
              description: The HTTP status code of the error.
            message:
              type: string
              description: A human-readable description of the error.
            errors:
              type: array
              description: A list of individual errors.
              items:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                  domain:
                    type: string
                    description: The domain in which the error occurred.
                  reason:
                    type: string
                    description: The reason for the error.
          example: example_value
    SearchResult:
      type: object
      description: A search result contains information about a YouTube video, channel, or playlist that matches the search query.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#searchResult.
          default: youtube#searchResult
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        id:
          type: object
          description: The id object contains information that can be used to uniquely identify the resource that matches the search request.
          properties:
            kind:
              type: string
              description: The type of the API resource.
            videoId:
              type: string
              description: If the id.kind property's value is youtube#video, then this property is present.
            channelId:
              type: string
              description: If the id.kind property's value is youtube#channel, then this property is present.
            playlistId:
              type: string
              description: If the id.kind property's value is youtube#playlist, then this property is present.
          example: abc123def456
        snippet:
          type: object
          description: The snippet object contains basic details about a search result, such as its title or description.
          properties:
            publishedAt:
              type: string
              format: date-time
              description: The creation date and time of the resource that the search result identifies.
            channelId:
              type: string
              description: The value that YouTube uses to uniquely identify the channel that published the resource identified by the search result.
            title:
              type: string
              description: The title of the search result.
            description:
              type: string
              description: A description of the search result.
            thumbnails:
              type: object
              description: A map of thumbnail images associated with the search result.
            channelTitle:
              type: string
              description: The title of the channel that published the resource identified by the search result.
            liveBroadcastContent:
              type: string
              description: An indication of whether a video or channel resource has live broadcast content.
          example: example_value
    PageInfo:
      type: object
      description: Paging details for a list operation, including information about the total number of resources and the number per page.
      properties:
        totalResults:
          type: integer
          description: The total number of results in the result set.
          example: 42
        resultsPerPage:
          type: integer
          description: The number of results included in the API response.
          example: 10
    SearchListResponse:
      type: object
      description: A list of search results matching the query criteria.
      properties:
        kind:
          type: string
          description: Identifies the API resource's type. Value is youtube#searchListResponse.
          default: youtube#searchListResponse
          example: youtube#video
        etag:
          type: string
          description: The Etag of this resource.
          example: XI7nbFXulYBIpL0ayR_gDh3eu1k
        nextPageToken:
          type: string
          description: The token for the next page of results.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        prevPageToken:
          type: string
          description: The token for the previous page of results.
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
        regionCode:
          type: string
          description: The region code that was used for the search query.
          example: US
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        items:
          type: array
          description: A list of results that match the search criteria.
          items:
            $ref: '#/components/schemas/SearchResult'
          example: []
    ErrorResponse_2:
      type: object
      description: Error response object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
    ThumbnailDetails:
      type: object
      description: Thumbnail images at various resolutions
      properties:
        default:
          $ref: '#/components/schemas/Thumbnail'
        medium:
          $ref: '#/components/schemas/Thumbnail'
        high:
          $ref: '#/components/schemas/Thumbnail'
        standard:
          $ref: '#/components/schemas/Thumbnail'
        maxres:
          $ref: '#/components/schemas/Thumbnail'
    Thumbnail:
      type: object
      description: A thumbnail image
      properties:
        url:
          type: string
          description: URL of the thumbnail image
          example: https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg
        width:
          type: integer
          description: Width of the thumbnail
          example: 120
        height:
          type: integer
          description: Height of the thumbnail
          example: 90
    ResourceId:
      type: object
      description: Identifies the resource in the search result
      required:
      - kind
      properties:
        kind:
          type: string
          description: Type of resource
          enum:
          - youtube#video
          - youtube#channel
          - youtube#playlist
          example: youtube#video
        videoId:
          type: string
          description: Video ID if the result is a video
          example: dQw4w9WgXcQ
        channelId:
          type: string
          description: Channel ID if the result is a channel
          example: UC_x5XG1OV2P6uZZ5FSM9Ttw
        playlistId:
          type: string
          description: Playlist ID if the result is a playlist
          example: PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
    SearchResult_2:
      type: object
      description: A single search result
      required:
      - kind
      - etag
      - id
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#searchResult
        etag:
          type: string
          description: ETag for caching purposes
        id:
          $ref: '#/components/schemas/ResourceId'
        snippet:
          $ref: '#/components/schemas/SearchResultSnippet'
    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'
    SearchListResponse_2:
      type: object
      description: Response containing search results
      required:
      - kind
      - etag
      - items
      properties:
        kind:
          type: string
          description: Identifies the API resource type
          example: youtube#searchListResponse
        etag:
          type: string
          description: ETag for caching purposes
        nextPageToken:
          type: string
          description: Token for the next page of results
        prevPageToken:
          type: string
          description: Token for the previous page of results
        regionCode:
          type: string
          description: Region code used for the search
        pageInfo:
          $ref: '#/components/schemas/PageInfo_2'
        items:
          type: array
          description: List of search results
          items:
            $ref: '#/components/schemas/SearchResult_2'
    PageInfo_2:
      type: object
      description: Pagination information
      properties:
        totalResults:
          type: integer
          description: Total number of results
          example: 1000000
        resultsPerPage:
          type: integer
          description: Number of results per page
          example: 25
    SearchResultSnippet:
      type: object
      description: Basic information about the search result
      properties:
        publishedAt:
          type: string
          format: date-time
          description: When the resource was published
          example: '2024-03-15T10:30:00Z'
        channelId:
          type: string
          description: ID of the channel that owns the resource
          example: UC_x5XG1OV2P6uZZ5FSM9Ttw
        title:
          type: string
          description: Title of the resource
          example: 'OpenAPI Tutorial: Building REST APIs'
        description:
          type: string
          description: Description of the resource
          example: Learn how to build REST APIs using OpenAPI specification...
        thumbnails:
          $ref: '#/components/schemas/ThumbnailDetails'
        channelTitle:
          type: string
          description: Title of the channel
          example: Google Developers
    ErrorItem:
      type: object
      description: Individual error detail
      properties:
        domain:
          type: string
          description: Error domain
          example: youtube.parameter
        reason:
          type: string
          description: Error reason code
          example: invalidParameter
        message:
          type: string
          description: Detailed error message
          example: The parameter 'part' is required
        locationType:
          type: string
          description: Type of location where error occurred
          example: parameter
        location:
          type: string
          description: Specific location of the error
          example: part
  examples:
    BadRequestErrorExample:
      summary: Bad request error
      description: Example error response for invalid parameters
      value:
        error:
          code: 400
          message: Invalid parameter value
          errors:
          - domain: youtube.parameter
            reason: invalidParameter
            message: The parameter 'part' is required
            locationType: parameter
            location: part
    QuotaExceededErrorExample:
      summary: Quota exceeded error
      description: Example error response when API quota is exceeded
      value:
        error:
          code: 403
          message: Quota exceeded
          errors:
          - domain: youtube.quota
            reason: quotaExceeded
            message: The request cannot be completed because you have exceeded your quota
            locationType: global
            location: ''
    SuccessfulSearchExample:
      summary: Successful search results
      description: Example response for a video search query
      value:
        kind: youtube#searchListResponse
        etag: abc123def456
        nextPageToken: CAUQAA
        regionCode: US
        pageInfo:
          totalResults: 1000000
          resultsPerPage: 5
        items:
        - kind: youtube#searchResult
          etag: xyz789abc123
          id:
            kind: youtube#video
            videoId: dQw4w9WgXcQ
          snippet:
            publishedAt: '2024-03-15T10:30:00Z'
            channelId: UC_x5XG1OV2P6uZZ5FSM9Ttw
            title: 'OpenAPI Tutorial: Building REST APIs'
            description: Learn how to build REST APIs using OpenAPI...
            thumbnails:
              default:
                url: https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg
                width: 120
                height: 90
            channelTitle: Google Developers
  securitySchemes:
    oauth2:
      type: oauth2
      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/youtube.upload: Manage your YouTube videos
            https://www.googleapis.com/auth/youtube.force-ssl: See, edit, and permanently delete your YouTube videos, ratings, comments and captions
            https://www.googleapis.com/auth/youtubepartner: View and manage your assets and associated content on YouTube
    apiKey:
      type: apiKey
      in: query
      name: key
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for YouTube Data 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/youtube.upload: Upload videos to YouTube
            https://www.googleapis.com/auth/youtube.force-ssl: Manage your YouTube videos
    ApiKey:
      type: apiKey
      description: API key for read-only operations
      name: key
      in: query
externalDocs:
  description: YouTube Data API Documentation
  url: https://developers.google.com/youtube/v3
x-refined-from:
- youtube-data-api-openapi.yml
- youtube-data-openapi-original.yml