# Google News (/docs/google_news)



Google News [#google-news]

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/...`

Getting started [#getting-started]

Every request is a `GET` with query parameters and an `x-api-key` header:

```bash
curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=openai" \
  -H "x-api-key: $SOCIALCRAWL_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.

Filtering [#filtering]

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, e.g. `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`, ...), 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`; `to` defaults to today when only `from` is set.
* **Outlet**: `publisher` restricts results to one domain (`bbc.com`). Bare domain only.

Two rules to remember: `depth` (default 10, max 100, multiples of 10) is the only size control,
and there is no pagination beyond it; and `publisher`/`from`/`to` cannot be combined with
`location_coordinate` or `time_range=hour` (the API returns a clear 400 naming the conflict,
never billed).

Typical flow [#typical-flow]

```bash
# 1. Monitor an outlet for fresh coverage
curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=artificial%20intelligence&publisher=bbc.com&time_range=day&depth=20" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Research an exact window
curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=nvidia%20earnings&from=2026-07-01&to=2026-07-15&depth=50" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 3. 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: $SOCIALCRAWL_API_KEY"
```

Reading the response [#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 it 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.

Endpoints [#endpoints]

<PlatformEndpoints platform="google_news" />

Notes [#notes]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema
* 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 \~2s, with a resilient tail