openapi: 3.0.0
info:
  title: Baidu News API
  description: |
    The Baidu News API returns the news articles Baidu News lists for a query. Each result includes the headline, the article link, the publisher and a snippet, plus the publish date as Baidu shows it, the publisher icon, a thumbnail and a Baijiahao flag when available. The response also includes the total number of results, and related searches, the Baidu hot search board and the pages of the results when Baidu News shows them.

    Results can be sorted by date and limited to media outlets or Baijiahao posts, to a preset time period or a custom date range, and to Simplified or Traditional Chinese. Dates are shown in Beijing time, often as relative strings.

    Baidu News lists a limited number of results per query. A search with no results, or a page past the last one, returns an `error` message in place of the results.

    **Cross-linking**: The `query` of an entry in `related_searches` or `top_searches` can be passed as the `q` parameter of this API. The `query` of an entry in `top_searches` can also be passed as the `q` parameter of the Baidu API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Baidu News Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["baidu_news"]
        - name: q
          in: query
          required: true
          description: Search query. Operators such as `site:` and `intitle:` are supported.
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: Sorts the results by publish date, newest first. Results are sorted by relevance when omitted.
          schema:
            type: string
            enum: ["most_recent"]
        - name: source_type
          in: query
          required: false
          description: Limits the results to every source, to news sites and media outlets, or to Baijiahao posts.
          schema:
            type: string
            enum: ["all", "media", "baijiahao"]
            default: "all"
        - name: time_period
          in: query
          required: false
          description: Limits the results to articles published within the time period. Ignored when `time_period_min` or `time_period_max` is set.
          schema:
            type: string
            enum: ["last_hour", "last_day", "last_week", "last_month", "last_year"]
        - name: time_period_min
          in: query
          required: false
          description: First day of a custom time period in MM/DD/YYYY format, starting at midnight Beijing time. When used alone, the range ends today in Beijing.
          schema:
            type: string
            pattern: '^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/(19|20)\d\d$'
        - name: time_period_max
          in: query
          required: false
          description: Last day of a custom time period in MM/DD/YYYY format, included up to midnight Beijing time. The earliest supported end date is 01/01/1970.
          schema:
            type: string
            pattern: '^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/(19|20)\d\d$'
        - name: ct
          in: query
          required: false
          description: 'Script of the results: `0` for Simplified and Traditional Chinese, `1` for Simplified Chinese, `2` for Traditional Chinese.'
          schema:
            type: string
            enum: ["0", "1", "2"]
            default: "0"
        - name: page
          in: query
          required: false
          description: Page number of the results.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: num
          in: query
          required: false
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      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'
        error:
          type: string
          description: Message saying that Baidu News returned no results for the search.
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
        related_searches:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSearch'
        top_searches:
          type: array
          items:
            $ref: '#/components/schemas/TopSearch'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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: Baidu 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
          description: Engine used for the search
        q:
          type: string
          description: Search query
        sort_by:
          type: string
          description: Sort order of the results
        source_type:
          type: string
          description: Type of source the results are limited to
        time_period:
          type: string
          description: Preset time period the results are limited to
        time_period_min:
          type: string
          description: First day of the custom time period
        time_period_max:
          type: string
          description: Last day of the custom time period
        ct:
          type: string
          description: Script of the results
        page:
          type: string
          description: Page number of the results
        num:
          type: string
          description: Number of results per page
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: Number of results Baidu News reports for the search.
    OrganicResult:
      type: object
      required: [position, title, link, source, snippet]
      properties:
        position:
          type: integer
          description: Position of the article in the results.
        title:
          type: string
          description: Headline of the article.
        link:
          type: string
          description: URL of the article.
        source:
          type: string
          description: Name of the publisher.
        date:
          type: string
          description: Publish date as Baidu News shows it, in Beijing time.
        snippet:
          type: string
          description: Excerpt of the article.
        snippet_highlighted_words:
          type: array
          items:
            type: string
          description: Words of the snippet that Baidu News highlights for the query.
        favicon:
          type: string
          description: URL of the publisher icon.
        thumbnail:
          type: string
          description: URL of the article thumbnail.
        is_baijiahao:
          type: boolean
          description: Whether the article is a Baijiahao post.
    RelatedSearch:
      type: object
      required: [query, link]
      properties:
        query:
          type: string
          description: Related search query.
        link:
          type: string
          description: Baidu News URL of the related search.
    TopSearch:
      type: object
      required: [position, query, link]
      properties:
        position:
          type: integer
          description: Rank on the Baidu hot search board.
        query:
          type: string
          description: Trending search query.
        link:
          type: string
          description: Baidu URL of the trending search.
        is_hot:
          type: boolean
          description: Whether Baidu marks the search as hot.
        is_new:
          type: boolean
          description: Whether Baidu marks the search as new.
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page number.
        next:
          type: string
          description: Baidu News URL of the next page.
        previous:
          type: string
          description: Baidu News URL of the previous page.
        other_pages:
          type: object
          additionalProperties:
            type: string
          description: Baidu News URLs of the other pages, keyed by page number.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
