openapi: 3.0.0
info:
  title: Yahoo News API
  description: >-
    Search Yahoo News across 13 regional editions, with time period, sort and SafeSearch filters. Results include
    article titles, links, sources, the Yahoo property that republished an article, relative dates, snippets,
    thumbnails and source favicons, 10 articles per page for up to 100 pages, plus ads, a knowledge graph, related
    searches and trending searches where Yahoo shows them. 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 News Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to yahoo_news.
        schema:
          type: string
          enum: ["yahoo_news"]
      - name: q
        in: query
        required: true
        description: Search terms used to find news articles. Quotes and the site operator are supported.
        schema:
          type: string
      - name: yahoo_domain
        in: query
        required: false
        description: Yahoo domain of the regional edition to search. Each edition has its own news index and language.
        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","in.search.yahoo.com","malaysia.search.yahoo.com","ph.search.yahoo.com","sg.search.yahoo.com","uk.search.yahoo.com","hk.search.yahoo.com","tw.search.yahoo.com"]
          default: "search.yahoo.com"
      - name: time_period
        in: query
        required: false
        description: Time window of the articles. Without it, Yahoo News returns articles from about the past week.
        schema:
          type: string
          enum: ["last_day","last_week","last_month"]
      - name: sort_by
        in: query
        required: false
        description: Set to most_recent to list the newest articles first. Without it, articles are sorted by relevance.
        schema:
          type: string
          enum: ["most_recent"]
      - name: safe
        in: query
        required: false
        description: SafeSearch filtering of adult content. With on, a query with restricted words returns no results.
        schema:
          type: string
          enum: ["on","moderate","off"]
          default: "on"
      - name: page
        in: query
        required: false
        description: Page of results to return, from 1 to 100, with 10 articles per page. A page past the last one returns an error.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          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"
        ads:
          type: array
          items:
            "$ref": "#/components/schemas/Ad"
        knowledge_graph:
          "$ref": "#/components/schemas/KnowledgeGraph"
        organic_results:
          type: array
          items:
            "$ref": "#/components/schemas/OrganicResult"
        related_searches:
          type: array
          items:
            "$ref": "#/components/schemas/RelatedSearch"
        trending_searches:
          type: array
          items:
            "$ref": "#/components/schemas/TrendingSearch"
        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 News 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_news"]
          description: Set to yahoo_news.
        q:
          type: string
          description: Search terms used to find news articles.
        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","in.search.yahoo.com","malaysia.search.yahoo.com","ph.search.yahoo.com","sg.search.yahoo.com","uk.search.yahoo.com","hk.search.yahoo.com","tw.search.yahoo.com"]
          default: "search.yahoo.com"
          description: Yahoo domain of the regional edition searched.
        time_period:
          type: string
          enum: ["last_day","last_week","last_month"]
          description: Time window of the articles.
        sort_by:
          type: string
          enum: ["most_recent"]
          description: Sort order of the articles.
        safe:
          type: string
          enum: ["on","moderate","off"]
          default: "on"
          description: SafeSearch filtering of adult content.
        page:
          type: integer
          minimum: 1
          maximum: 100
          description: Page of results returned, starting at 1.
    SearchInformation:
      type: object
      required:
      - query_displayed
      - total_results
      properties:
        query_displayed:
          type: string
          description: Query displayed in the search box.
        total_results:
          type: integer
          description: Approximate number of matching articles Yahoo reports.
    OrganicResult:
      type: object
      required:
      - position
      - title
      - link
      - date
      properties:
        position:
          type: integer
          description: Position of the article on the results page.
        title:
          type: string
          description: Headline of the article.
        link:
          type: string
          description: URL of the article.
        source:
          type: string
          description: Publisher of the article.
        via:
          type: string
          description: Yahoo property that republished the article, in which case the link points to that copy.
        date:
          type: string
          description: Age of the article as Yahoo prints it, in the language of the edition.
        snippet:
          type: string
          description: Excerpt of the article.
        favicon:
          type: string
          description: Favicon URL of the publisher.
        thumbnail:
          type: string
          description: Thumbnail URL of the article image.
    Ad:
      type: object
      required:
      - position
      - block_position
      - title
      - link
      - displayed_link
      - snippet
      properties:
        position:
          type: integer
          description: Position of the ad.
        block_position:
          type: string
          description: Block the ad appears in, such as top or bottom.
        title:
          type: string
          description: Title of the ad.
        link:
          type: string
          description: Destination URL of the ad.
        displayed_link:
          type: string
          description: Display URL of the ad.
        snippet:
          type: string
          description: Description of the ad.
        snippet_highlighted_words:
          type: array
          items:
            type: string
          description: Highlighted words in the description.
        sitelinks:
          "$ref": "#/components/schemas/Sitelinks"
        assets:
          "$ref": "#/components/schemas/AdAssets"
        favicon:
          type: string
          description: Favicon URL of the advertiser.
        thumbnail:
          type: string
          description: Thumbnail URL of the ad.
    AdAssets:
      type: object
      properties:
        structured_snippet:
          type: object
          properties:
            title:
              type: string
            text:
              type: string
        review:
          type: object
          properties:
            text:
              type: string
            source:
              type: string
            link:
              type: string
        prices:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              price:
                type: string
              extracted_price:
                type: number
              link:
                type: string
        promotion:
          type: object
          properties:
            title:
              type: string
            link:
              type: string
        extensions:
          type: array
          items:
            type: string
    Sitelinks:
      type: object
      properties:
        expanded:
          type: array
          items:
            type: object
            required: [title, link]
            properties:
              title:
                type: string
              link:
                type: string
              snippet:
                type: string
              inline_links:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                    link:
                      type: string
        inline:
          type: array
          items:
            type: object
            required: [title, link]
            properties:
              title:
                type: string
              link:
                type: string
    KnowledgeGraph:
      type: object
      properties:
        title:
          type: string
          description: Entity name
        subtitle:
          type: string
          description: Entity subtitle
        price:
          type: string
          description: Price information
        rating:
          type: number
          description: Rating value
        rating_max:
          type: number
          description: Maximum rating value
        reviews_count:
          type: integer
          description: Number of reviews
        hours:
          type: string
          description: Current hours status
        open_hours:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
        website:
          type: string
          description: Website URL
        menu:
          type: string
          description: Menu URL
        reservation:
          type: string
          description: Reservation URL
        phone:
          type: string
          description: Phone number
        description:
          type: string
          description: Entity description
        source:
          type: string
          description: Source URL
        address:
          type: string
          description: Physical address
        amenities:
          type: array
          items:
            type: string
          description: List of amenities
        reviews_histogram:
          type: object
          description: Rating distribution
        user_reviews:
          type: array
          items:
            type: object
            properties:
              review:
                type: string
              link:
                type: string
              rating:
                type: integer
              user:
                type: string
              date:
                type: string
        thumbnail:
          type: string
          description: Thumbnail image URL
        profiles:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              link:
                type: string
        people_also_search_for:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
              link:
                type: string
              thumbnail:
                type: string
              is_trending:
                type: boolean
      additionalProperties:
        oneOf:
          - type: string
            description: Dynamic fact field value
          - type: array
            description: Dynamic fact links field (field name ends with _links)
            items:
              type: object
              properties:
                text:
                  type: string
                link:
                  type: string
    RelatedSearch:
      type: object
      required:
      - query
      - link
      properties:
        query:
          type: string
          description: Search terms for the related search.
        link:
          type: string
          description: Yahoo News link for the related search.
    TrendingSearch:
      type: object
      required:
      - title
      - link
      properties:
        title:
          type: string
          description: Trending topic.
        snippet:
          type: string
          description: Headline about the trending topic.
        link:
          type: string
          description: Yahoo Search link for the trending topic.
        thumbnail:
          type: string
          description: Thumbnail URL for the trending topic.
    Pagination:
      type: object
      required:
      - current
      properties:
        current:
          type: integer
          description: Current page number, starting at 1.
        previous:
          type: string
          description: Yahoo News URL for the previous results page.
        next:
          type: string
          description: Yahoo News URL for the next results page.
        other_pages:
          type: object
          description: Yahoo News URLs of nearby results pages, keyed by page number.
          additionalProperties:
            type: string
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
