> ## Documentation Index
> Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Google News

> Extract structured news articles from Google News including titles, links, snippets, sources, dates, and thumbnails

## Overview

The Google News endpoint extracts structured news articles from Google News, including titles, links, snippets, sources, publication dates, and thumbnail images.

## Request parameters

**Required parameters:**

* `query` (string): The search query to execute on Google News (1-10,000 characters)

**Optional parameters:**

* `country` (string): ISO 3166-1 alpha-2 country code for localized news results. Defaults to `US`
* `device` (string): Device type for news results. Options: `desktop` (default), `mobile`
* `pages` (integer): Number of news results pages to scrape (1-10). Defaults to `1`
* `include.html` (boolean): Include raw HTML response. Defaults to `false`

## Response schema

Includes [common response fields](/guides/making-requests/sync#common-response-fields) plus:

### Google News results

| Field                | Type  | Description                                                                         |
| -------------------- | ----- | ----------------------------------------------------------------------------------- |
| `result.newsResults` | array | [News articles](/api-reference/endpoint/google-news/news-articles) from Google News |
| `result.html`        | array | Raw HTML response (if requested)                                                    |

## Response objects

The response includes the following sections. See each subpage for the full schema.

| Section                                                            | Description                                                                 |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| [News articles](/api-reference/endpoint/google-news/news-articles) | Article titles, links, snippets, sources, publication dates, and thumbnails |

## Usage examples

### Basic news search

```json theme={null}
{
  "query": "climate change",
  "country": "US"
}
```

### Multi-page news search

Scrape multiple pages of news results:

```json theme={null}
{
  "query": "artificial intelligence",
  "pages": 3,
  "country": "GB"
}
```

This will scrape the first 3 pages of Google News results, combining all news articles into a single response.

### Mobile news results

Get news results optimized for mobile devices:

```json theme={null}
{
  "query": "technology news",
  "device": "mobile",
  "country": "US"
}
```

### Include HTML response

Request raw HTML alongside structured data:

```json theme={null}
{
  "query": "sports news",
  "country": "US",
  "include": {
    "html": true
  }
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/monitor/google/news
openapi: 3.1.0
info:
  title: cloro
  description: API for monitoring AI responses across different providers and regions
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.cloro.dev
    description: Production server
security:
  - bearerAuth: []
paths:
  /v1/monitor/google/news:
    post:
      summary: Monitor Google News Results
      description: >-
        Extract structured news articles from Google News including titles,
        links, snippets, sources, dates, and thumbnails
      operationId: monitorGoogleNews
      requestBody:
        description: Request parameters for monitoring Google News results
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleNewsMonitorRequest'
        required: true
      responses:
        '200':
          description: successful Google News monitoring response
          headers:
            X-Concurrent-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrent-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrent-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 7
            X-Credits-Remaining:
              description: Number of credits remaining in user account
              schema:
                type: integer
                example: 997
            X-Credits-Charged:
              description: Number of credits charged for this request
              schema:
                type: integer
                example: 3
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleNewsMonitorResponse'
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Forbidden - Insufficient credits or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not Found - Route not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '409':
          description: Conflict - Resource conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrent-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrent-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrent-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-Credits-Remaining:
              description: Number of credits remaining in user account
              schema:
                type: integer
                example: 4
            X-Credits-Charged:
              description: Number of credits charged for this request
              schema:
                type: integer
                example: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConcurrentLimitError'
        '499':
          description: Client Closed Request - Request was canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CanceledError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '502':
          description: Bad Gateway - External service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalServiceError'
components:
  schemas:
    GoogleNewsMonitorRequest:
      required:
        - query
        - country
      type: object
      properties:
        query:
          description: The search query to execute on Google News
          type: string
          minLength: 1
          maxLength: 10000
          example: climate change
        country:
          description: ISO 3166-1 alpha-2 country code for localized news results
          type: string
          example: US
        device:
          description: Device type for news results
          type: string
          enum:
            - desktop
            - mobile
          default: desktop
          example: desktop
        pages:
          description: Number of news results pages to scrape (1-10)
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          example: 1
        include:
          description: Optional flags for including additional response data
          type: object
          properties:
            html:
              description: Include raw HTML response from Google News
              type: boolean
              default: false
              example: false
          default:
            html: false
          additionalProperties: false
      additionalProperties: false
    GoogleNewsMonitorResponse:
      required:
        - success
        - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: Google News results data
          type: object
          properties:
            newsResults:
              type: array
              description: News articles from Google News
              items:
                type: object
                properties:
                  position:
                    type: number
                    description: Position in news results (1-indexed)
                    example: 1
                  title:
                    type: string
                    description: Title of the news article
                    example: Major Climate Summit Reaches Historic Agreement
                  link:
                    type: string
                    description: URL of the news article
                    example: https://example.com/climate-summit-agreement
                  snippet:
                    type: string
                    description: Text snippet describing the article
                    example: >-
                      World leaders agreed on new climate targets at the
                      summit...
                  source:
                    type: string
                    description: News source/publisher name
                    example: The Guardian
                  date:
                    type: string
                    description: Publication date
                    example: 2 hours ago
                  page:
                    type: number
                    description: Page number this result appeared on (1-indexed)
                    example: 1
                  thumbnail:
                    type: string
                    description: Thumbnail image URL (if available)
                    example: https://example.com/images/climate-summit.jpg
            html:
              type: array
              description: Raw HTML from Google News pages (if requested)
              items:
                type: string
                format: uri
              example:
                - >-
                  https://storage.cloro.dev/results/a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6/page-1.html
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Request validation failed
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: prompt
              message:
                type: string
                example: Prompt cannot be empty
    AuthenticationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - MISSING_API_KEY
                - INVALID_API_KEY_FORMAT
                - INVALID_OR_EXPIRED_API_KEY
              example: MISSING_API_KEY
            message:
              type: string
              example: Missing or invalid API key
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    ForbiddenError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INSUFFICIENT_PERMISSIONS
                - INSUFFICIENT_CREDITS
              example: INSUFFICIENT_PERMISSIONS
            message:
              type: string
              example: Insufficient permissions
            details:
              type: object
              properties:
                requiredScopes:
                  type: array
                  items:
                    type: string
                  example:
                    - read:monitor
                    - write:monitor
              required: []
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    NotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: Route not found
            details:
              type: object
              properties:
                id:
                  type: string
                  example: /v1/invalid-endpoint
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    ConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_CONFLICT
            message:
              type: string
              example: Resource conflict
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    ConcurrentLimitError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: CONCURRENT_LIMIT_EXCEEDED
            message:
              type: string
              example: Concurrent limit exceeded
            details:
              type: object
              properties:
                limit:
                  type: number
                  example: 10
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    CanceledError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Request was canceled
    InternalError:
      type: object
      oneOf:
        - properties:
            success:
              type: boolean
              example: false
            error:
              type: string
              example: Maximum retries exceeded
        - properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  example: INTERNAL_SERVER_ERROR
                message:
                  type: string
                  example: Internal server error
                timestamp:
                  type: string
                  format: date-time
                  example: '2025-01-15T12:00:00.000Z'
    ExternalServiceError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: EXTERNAL_SERVICE_ERROR
            message:
              type: string
              example: 'External service error: OpenAI'
            details:
              type: object
              properties:
                service:
                  type: string
                  example: OpenAI
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````