# Google News (/docs/google_news)

Real-time Google News search with country, language, outlet, and exact date-window filters, unified into one canonical article schema

Real-time Google News results behind the unified SocialCrawl envelope. One `GET` call returns up to 100 ranked articles with the outlet name, real article URL, thumbnail, and a precise ISO-8601 publish timestamp.

Base URL: `/v1/google_news/...`

  `depth` (default 10, max 100, multiples of 10) is the only size control, and
  there is no pagination beyond it. To reach further back, narrow the window
  with `from`/`to` rather than asking for a second page.

## Quickstart

### 1. Search the headlines

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=openai" \
  -H "x-api-key: YOUR_API_KEY"
```

One successful call costs 1 credit. Cache hits (5-minute window) cost 0 credits, empty result sets cost 0 credits, and invalid parameters are rejected before billing.

### 2. Narrow to an outlet and a window

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=nvidia%20earnings&publisher=bbc.com&from=2026-07-01&to=2026-07-15&depth=50" \
  -H "x-api-key: YOUR_API_KEY"
```

## Search the news

| Endpoint                     | Credits | What it returns                                                                               | Key parameters                                                                                                                        |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/google_news/search` | 1       | Up to 100 ranked articles with outlet name, publisher URL, thumbnail, and a publish timestamp | `keyword`, `depth`, `location_name`, `location_code`, `location_coordinate`, `language_code`, `time_range`, `publisher`, `from`, `to` |

The search composes five filter families:

- **Query.** `keyword` supports any language, quoted phrases, and boolean operators (`AND`, `OR`, `NOT`): `"Elon Musk" AND (Tesla OR SpaceX) NOT stock`. Google advanced operators like `site:` are rejected with a clear 400. Use `publisher` instead.
- **Market.** `location_name` (country name, for example `South Korea`), `location_code` (numeric), or `location_coordinate` (GPS `lat,lng,radius` for hyper-local news). Use one of the three.
- **Language.** `language_code` (`en`, `ko`, `pt`, `ja`, and so on), independent of the market.
- **Recency.** `time_range` (`hour`, `day`, `week`, `month`, `year`) for friendly windows, or `from`/`to` (`YYYY-MM-DD` or Unix timestamp) for an exact publish-date window. Explicit `from`/`to` overrides `time_range`, and `to` defaults to today when only `from` is set. `time_range` resolves to whole calendar days, so `day` means "since yesterday's date" rather than the last 24 hours. `hour` is the only true rolling window.
- **Outlet.** `publisher` restricts results to one domain (`bbc.com`). Bare domain only.

```bash title="cURL"
# Native-language local market
curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=%EC%82%BC%EC%84%B1%EC%A0%84%EC%9E%90&location_name=South%20Korea&language_code=ko" \
  -H "x-api-key: YOUR_API_KEY"
```

## Reading the response

Each item is one `article` with a stable `id` (same URL, same id, safe to dedupe on), `title`, `url` (the real publisher link, scrape it for the full body), `source` (human outlet name), `domain`, `image_url`, `published_at` (ISO-8601 UTC, second precision, sort on this when recency matters), `rank` (1-based position), `placement`, and a nullable `snippet`. Treat the snippet as a bonus field, never as required.

See the [NewsArticle schema](/docs/schema/news-article.md) for the full field table with per-field nullability.

## All endpoints

## Platform notes

- **`publisher`, `from` and `to` cannot be combined with `location_coordinate` or `time_range=hour`.** The API returns a clear 400 naming the conflict, and it is never billed.
- **There is no pagination.** `depth` is the only size control, and it caps at 100.
- Responses cache for 5 minutes. Send `Cache-Control: no-cache` for a billed fresh fetch.
- Set client timeouts to at least 20 seconds. Typical calls run around 2 seconds, with a resilient tail.
- For a planned, multi-country, auto-localized version of the same question, use [`/v1/search/news`](/docs/search/news.md), which rides on this endpoint per country edition.

## Next steps

- [Universal news search](/docs/search/news.md): One query planned into angles and localized across country editions.
- [NewsArticle schema](/docs/schema/news-article.md): Every field an article carries, and which of them can be null.
- [Caching](/docs/caching.md): TTLs, cache hits, and how to force a fresh fetch.