Name: Google News API: Monitor Brands and Tickers in News
Brand: steadyscrape
SKU: api-steadyscrape-google-news-monitor
Availability: InStock
Author: API Market

# Google News Monitor API

## Overview

The Google News Monitor API tracks brands, companies and stock tickers in Google News and returns articles as JSON with title, URL, domain, snippet, publish time, rank and top story flag. You send up to 5 search phrases or ticker-qualified companies such as `NVDA: Nvidia`. In `oneOff` mode a job returns the current top articles; in `monitor` mode the API remembers what you have already seen and returns only new articles on the next run.

Jobs are asynchronous: `POST /v1/news/jobs` returns a job id and `GET /v1/news/jobs/{jobId}` returns the articles when the job has `succeeded`, usually within 30 to 90 seconds. It is built for brand and competitor monitoring, investor news alerts, PR teams and AI agents. In our tests a `oneOff` job for `Cloudflare Workers` finished in about a minute with 5 articles from the Cloudflare blog published in the previous 10 hours, and an empty request returned a clear `400`.

## Features

*   **2 endpoints**: start a job and poll it.
*   **Brands and tickers**: search phrases or `TICKER: Company` entries, up to 5 per job.
*   **Monitor mode**: returns only articles you have not seen before.
*   **Article fields**: title, URL, canonical URL, domain, snippet, publish time, rank and top story flag.
*   **Fair billing**: one unit per article; starts, polls and empty results are free.

## Use Cases

*   **Brand monitoring**: alert on new coverage of your company.
*   **Investor alerts**: follow news for the tickers in a portfolio.
*   **PR and comms**: track coverage of launches and competitors.
*   **AI agents**: give an agent fresh news on a topic.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/steadyscrape/google-news-monitor
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Start a news job

Starts a job and returns its id.

**Method:** `POST`

**Endpoint:** `/v1/news/jobs`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `queries` | body | Search phrases, up to 5 together with `financeCompanies` | array of strings | Yes, or `financeCompanies` | - | 5 |
| `financeCompanies` | body | Companies as `TICKER: Name`, for example `NVDA: Nvidia` | array of strings | No | - | 5 |
| `mode` | body | `oneOff` (current top articles) or `monitor` (only new articles) | string | No | `oneOff` | - |
| `maxResultsPerQuery` | body | Articles per query | integer | No | 10 | - |
| `location` | body | Google News location, for example `United States` | string | No | - | - |
| `language` | body | Language code, for example `en` | string | No | - | - |
| `Idempotency-Key` | header | Optional key so a retried start is not run twice | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/steadyscrape/google-news-monitor/v1/news/jobs' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"queries": ["Cloudflare Workers"], "mode": "oneOff", "maxResultsPerQuery": 5, "location": "United States", "language": "en"}'
```

**Example Response (202 Accepted):**

```json
{
  "success": true,
  "endpoint": "news.jobs",
  "count": 0,
  "partial": false,
  "items": [],
  "job": {
    "id": "7de1aa8d37317738bd08f04c3deec9bf9a07ddd1562180df80b660c9f2d7fd82",
    "status": "running",
    "partial": false,
    "truncated": false,
    "billable": false,
    "expiresAt": "2026-11-15T00:21:08.936Z"
  }
}
```

A request without queries returns `400`:

```json
{
  "success": false,
  "error": {
    "code": "bad_input",
    "message": "Add a query or a finance company."
  }
}
```

#### 2. Poll a news job

Returns the job status and, once it has succeeded, the articles.

**Method:** `GET`

**Endpoint:** `/v1/news/jobs/{jobId}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `jobId` | path | The `job.id` from the start call | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/steadyscrape/google-news-monitor/v1/news/jobs/7de1aa8d37317738bd08f04c3deec9bf9a07ddd1562180df80b660c9f2d7fd82' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "success": true,
  "endpoint": "news.jobs",
  "count": 5,
  "partial": false,
  "items": [
    {
      "query": "Cloudflare Workers",
      "articleId": "09e5e80125ce2409ff00",
      "title": "Kitesurf is now open source",
      "url": "https://blog.cloudflare.com/kitesurf-open-source/",
      "canonicalUrl": "https://blog.cloudflare.com/kitesurf-open-source",
      "source": null,
      "domain": "blog.cloudflare.com",
      "snippet": "We introduced Kitesurf, our stateless browser for AI agents that runs entirely on top of Workers, in August and followed up in September...",
      "publishedAt": "2026-11-13T20:21:18Z",
      "publishedText": "4 hours ago",
      "imageUrl": null,
      "rank": 1,
      "isTopStory": false,
      "firstSeenAt": "2026-11-14T00:21:51Z"
    }
  ],
  "job": {
    "id": "7de1aa8d37317738bd08f04c3deec9bf9a07ddd1562180df80b660c9f2d7fd82",
    "status": "succeeded",
    "partial": false,
    "truncated": false,
    "billable": true,
    "expiresAt": "2026-11-15T00:21:08.936Z"
  }
}
```

The `items` list above is shortened to one of five articles. While the job runs, the poll returns `202` with `job.status` `running`.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 202 | Accepted | The job was accepted (start) or is still running (poll). Poll again after a few seconds. |
| 400 | Bad Request | The body is invalid, for example no URL or keyword. The message says what to send. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The job id is unknown or the job has expired (jobs are kept 24 hours). |
| 429 | Too Many Requests | You went over 10 requests per second, used up your plan, or the service is busy. Retry after a short wait. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second. The Free trial includes 25 units. Starter includes 500 units per month for $9.99, Pro 2,000 for $29.99 and Business 6,000 for $79.99. Starting a job and polling it use no units; units are charged only for usable results, reported in the response that finishes the job. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **How do I get the result?**
    Start a job with `POST`, keep the `job.id`, and call the poll endpoint every few seconds until `job.status` is `succeeded` (or `failed`). Results are kept for 24 hours.

*   **How does monitor mode know what I have seen?**
    It keeps the article ids returned to your account and returns only new ones on the next job with the same queries.

*   **What is billed?**
    Only usable results, one unit each. Starting a job, polling, refused or failed items and empty results are free.

*   **How fresh are the articles?**
    They are read from Google News when the job runs, so a job returns the current top articles.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Google News monitoring API: track brands, companies and stock tickers and get new articles as JSON with title, source, URL, snippet and publish time.

Google News API: Monitor Brands and Tickers in News