openapi: 3.0.0
info:
  title: DuckDuckGo News API
  description: |
    DuckDuckGo News API returns the news articles DuckDuckGo News shows for a query, in the same order, with the title, link, source, relative and ISO publication time, snippet and favicon of each article, and its thumbnail when one is available. You can choose the region and filter articles by the past day, week or month.

    **Cross-linking**: Pass `pagination.next_page_token` back as the `next_page_token` parameter, with the same `q`, to fetch the next page of articles.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: DuckDuckGo News Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to duckduckgo_news
          schema:
            type: string
            enum: ["duckduckgo_news"]
        - name: q
          in: query
          required: true
          description: Search query
          schema:
            type: string
            maxLength: 500
        - name: locale
          in: query
          required: false
          description: Region and language of the news feed, in country-language format
          schema:
            type: string
            enum: ["xa-ar", "xa-en", "ar-es", "au-en", "at-de", "be-fr", "be-nl", "br-pt", "ca-en", "ca-fr", "ct-ca", "cl-es", "cn-zh", "dk-da", "fi-fi", "fr-fr", "de-de", "hk-tzh", "in-en", "id-id", "id-en", "ie-en", "il-he", "it-it", "jp-jp", "kr-kr", "xl-es", "my-ms", "my-en", "mx-es", "nl-nl", "nz-en", "ph-en", "ph-tl", "pl-pl", "pt-pt", "ru-ru", "sg-en", "za-en", "es-es", "se-sv", "ch-de", "ch-fr", "ch-it", "tw-tzh", "th-th", "tr-tr", "uk-en", "us-en", "ue-es", "vn-vi", "wt-wt"]
            default: "us-en"
        - name: time_period
          in: query
          required: false
          description: Limits results to articles published within the time period
          schema:
            type: string
            enum: ["any_time", "past_day", "past_week", "past_month"]
            default: "any_time"
        - name: next_page_token
          in: query
          required: false
          description: Token to retrieve the next page of results. Returned in the pagination object of the response.
          schema:
            type: string
      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'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search returned no articles
    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: DuckDuckGo 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: Search engine used
        q:
          type: string
          description: Search query
        locale:
          type: string
          description: Region and language used
        time_period:
          type: string
          description: Time period filter used
        next_page_token:
          type: string
          description: Pagination token used
    OrganicResult:
      type: object
      required: [position, title, link, source, date, iso_date, snippet, favicon]
      properties:
        position:
          type: integer
          description: Position of the article in the results
        title:
          type: string
          description: Article headline
        link:
          type: string
          description: URL of the article on the publisher's site
        source:
          type: string
          description: Name of the publisher
        date:
          type: string
          description: Time since publication, as DuckDuckGo News shows it
        iso_date:
          type: string
          format: date-time
          description: Publication time in ISO 8601 UTC
        snippet:
          type: string
          description: Excerpt of the article
        favicon:
          type: string
          description: URL of the publisher's favicon
        thumbnail:
          type: string
          description: URL of the article image
    Pagination:
      type: object
      required: [next_page_token]
      properties:
        next_page_token:
          type: string
          description: Token to retrieve the next page of results
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
