openapi: 3.0.0
info:
  title: Yahoo Images API
  description: >-
    Search Yahoo Images with size, color, image type, aspect ratio, time period, and usage rights filters, SafeSearch,
    and 25 regional Yahoo markets. Results include original image URLs with their pixel dimensions, source pages,
    thumbnails, suggested searches, related searches, and shopping ads, 60 images per page. Pass a related search query back as q
    to follow it.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Yahoo Images Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to yahoo_images.
        schema:
          type: string
          enum: ["yahoo_images"]
      - name: q
        in: query
        required: true
        description: Search terms used to find images. Quotes and the site operator are supported.
        schema:
          type: string
      - name: yahoo_domain
        in: query
        required: false
        description: Yahoo domain of the market to search. Each market has its own image results.
        schema:
          type: string
          enum: ["search.yahoo.com","espanol.search.yahoo.com","fr.search.yahoo.com","br.search.yahoo.com","ca.search.yahoo.com","de.search.yahoo.com","es.search.yahoo.com","in.search.yahoo.com","id.search.yahoo.com","it.search.yahoo.com","malaysia.search.yahoo.com","nl.search.yahoo.com","no.search.yahoo.com","at.search.yahoo.com","ph.search.yahoo.com","qc.search.yahoo.com","ch.search.yahoo.com","sg.search.yahoo.com","fi.search.yahoo.com","se.search.yahoo.com","uk.search.yahoo.com","vn.search.yahoo.com","ru.search.yahoo.com","hk.search.yahoo.com","tw.search.yahoo.com"]
          default: "search.yahoo.com"
      - name: safe
        in: query
        required: false
        description: SafeSearch filtering of adult content.
        schema:
          type: string
          enum: ["on","off"]
          default: "on"
      - name: size
        in: query
        required: false
        description: Filter by image size.
        schema:
          type: string
          enum: ["small","medium","large","extra_large"]
      - name: color
        in: query
        required: false
        description: Filter by image color.
        schema:
          type: string
          enum: ["color","black_and_white","red","orange","yellow","green","teal","blue","purple","pink","brown","black","gray","white"]
      - name: image_type
        in: query
        required: false
        description: Filter by image type. Can be combined with people.
        schema:
          type: string
          enum: ["photo","clipart","line_drawing","gif","transparent"]
      - name: people
        in: query
        required: false
        description: Apply Yahoo's people filter, alone or with image_type. Results from its No People filter may still show people.
        schema:
          type: string
          enum: ["face","head_and_shoulders","no_people"]
      - name: aspect_ratio
        in: query
        required: false
        description: Filter by image layout.
        schema:
          type: string
          enum: ["square","wide","tall"]
      - name: time_period
        in: query
        required: false
        description: Filter by how recently the image was found.
        schema:
          type: string
          enum: ["last_day","last_week","last_month","last_year"]
      - name: usage_rights
        in: query
        required: false
        description: Filter by license.
        schema:
          type: string
          enum: ["creative_commons_licenses","public_domain","free_to_share_and_use","free_to_share_and_use_commercial","free_to_modify_share_and_use","free_to_modify_share_and_use_commercial"]
      - name: page
        in: query
        required: false
        description: Page of results to return, starting at 1. A page past the last one returns an error.
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: >-
            Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting
            for the limit to reset.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          "$ref": "#/components/schemas/SearchMetadata"
        search_parameters:
          "$ref": "#/components/schemas/SearchParameters"
        search_information:
          "$ref": "#/components/schemas/SearchInformation"
        suggestions:
          type: array
          items:
            "$ref": "#/components/schemas/Suggestion"
        shopping_ads:
          type: array
          items:
            "$ref": "#/components/schemas/ShoppingAd"
        images:
          type: array
          items:
            "$ref": "#/components/schemas/Image"
        related_searches:
          type: array
          items:
            "$ref": "#/components/schemas/RelatedSearch"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        error:
          type: string
          description: Message describing an empty result set or a page past the last one.
    SearchMetadata:
      type: object
      required:
      - status
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Yahoo Images URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          enum: ["yahoo_images"]
          description: Set to yahoo_images.
        q:
          type: string
          description: Search terms used to find images.
        yahoo_domain:
          type: string
          enum: ["search.yahoo.com","espanol.search.yahoo.com","fr.search.yahoo.com","br.search.yahoo.com","ca.search.yahoo.com","de.search.yahoo.com","es.search.yahoo.com","in.search.yahoo.com","id.search.yahoo.com","it.search.yahoo.com","malaysia.search.yahoo.com","nl.search.yahoo.com","no.search.yahoo.com","at.search.yahoo.com","ph.search.yahoo.com","qc.search.yahoo.com","ch.search.yahoo.com","sg.search.yahoo.com","fi.search.yahoo.com","se.search.yahoo.com","uk.search.yahoo.com","vn.search.yahoo.com","ru.search.yahoo.com","hk.search.yahoo.com","tw.search.yahoo.com"]
          default: "search.yahoo.com"
          description: Yahoo domain of the market searched.
        safe:
          type: string
          enum: ["on","off"]
          default: "on"
          description: SafeSearch filtering of adult content.
        size:
          type: string
          enum: ["small","medium","large","extra_large"]
          description: Filter by image size.
        color:
          type: string
          enum: ["color","black_and_white","red","orange","yellow","green","teal","blue","purple","pink","brown","black","gray","white"]
          description: Filter by image color.
        image_type:
          type: string
          enum: ["photo","clipart","line_drawing","gif","transparent"]
        people:
          type: string
          enum: ["face","head_and_shoulders","no_people"]
          description: Filter by image type.
        aspect_ratio:
          type: string
          enum: ["square","wide","tall"]
          description: Filter by image layout.
        time_period:
          type: string
          enum: ["last_day","last_week","last_month","last_year"]
          description: Filter by how recently the image was found.
        usage_rights:
          type: string
          enum: ["creative_commons_licenses","public_domain","free_to_share_and_use","free_to_share_and_use_commercial","free_to_modify_share_and_use","free_to_modify_share_and_use_commercial"]
          description: Filter by license.
        page:
          type: integer
          minimum: 1
          description: Page of results returned, starting at 1.
    SearchInformation:
      type: object
      required:
      - query_displayed
      properties:
        query_displayed:
          type: string
          description: Query displayed in the search box.
    Suggestion:
      type: object
      required:
      - title
      - link
      - thumbnail
      properties:
        title:
          type: string
          description: Title of the suggested search.
        link:
          type: string
          description: Yahoo Images link for the suggested search.
        thumbnail:
          type: string
          description: Thumbnail URL for the suggested search.
    ShoppingAd:
      type: object
      required:
      - position
      - title
      - seller
      - link
      - price
      - extracted_price
      - image
      properties:
        position:
          type: integer
          description: Position in the shopping ads list.
        title:
          type: string
          description: Product title.
        seller:
          type: string
          description: Name of the store selling the product.
        link:
          type: string
          description: Link to the product on the store's website.
        price:
          type: string
          description: Price as displayed.
        extracted_price:
          type: number
          description: Price as a number.
        image:
          type: string
          description: Product image URL.
    Image:
      type: object
      required:
      - position
      - title
      - source
      - original
      - thumbnail
      properties:
        position:
          type: integer
          description: Position of the image on the results page.
        title:
          type: string
          description: Title of the page the image is on.
        source:
          "$ref": "#/components/schemas/Source"
        original:
          "$ref": "#/components/schemas/Original"
        thumbnail:
          type: string
          description: Thumbnail URL for the image.
    Source:
      type: object
      required:
      - name
      - link
      properties:
        name:
          type: string
          description: Domain of the website the image is on.
        link:
          type: string
          description: URL of the page containing the image.
    Original:
      type: object
      required:
      - link
      - width
      - height
      properties:
        link:
          type: string
          description: URL of the full-size image.
        width:
          type: integer
          description: Width of the full-size image in pixels.
        height:
          type: integer
          description: Height of the full-size image in pixels.
    RelatedSearch:
      type: object
      required:
      - query
      - link
      - thumbnail
      properties:
        query:
          type: string
          description: Search terms for the related search.
        link:
          type: string
          description: Yahoo Images link for the related search.
        thumbnail:
          type: string
          description: Thumbnail URL for the related search.
    Pagination:
      type: object
      required:
      - current
      properties:
        current:
          type: integer
          description: Current page number, starting at 1.
        next:
          type: string
          description: Yahoo Images URL for the next results page.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
