# Google News Search API (https://www.socialcrawl.dev/platforms/google_news/search)

> Returns a unified NewsArticleList of the top Google News results for a keyword, right now: headline, source outlet, thumbnail, article URL, and absolute UTC publish time (a text snippet may be present on some results). Ranked results land in one list: `rank` is the 1-based position of the row in the list you were served, on every source, and `placement` distinguishes a Top Stories block when present. `source` is the outlet name where the provider supplies one and the article's domain otherwise; `domain` is always the hostname. The keyword supports quoted phrases and boolean operators (AND, OR, NOT). Localize with `location_name`/`location_code`/`location_coordinate` + `language_code` (non-Latin scripts supported). Filter by recency with `time_range`, by an exact date window with `from`/`to` (YYYY-MM-DD or Unix timestamp; overrides `time_range` when present), or by outlet with `publisher` (a bare domain like bbc.com). `publisher`/`from`/`to` cannot be combined with `location_coordinate` or `time_range=hour` (clear 400, never billed). There is no pagination beyond `depth`. This surface returns at most 100 articles per query (default 10). For the full article body, scrape the returned `url`. Served live from Google News: an ordinary synchronous request.

TL;DR: `GET /v1/google_news/search` costs 1 credit per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `keyword` | yes | Search query (e.g. 'openai'). Supports any language; pass the matching language_code. Advanced operators (site:, intitle:, cache:, …) are not supported. |
| `depth` | no | Number of articles to retrieve (default 10, multiples of 10, max 100). The response is cut to exactly this many. No pagination beyond depth. |
| `location_code` | no | Google location code (e.g. 2840 = United States: the codes are 2000 + the ISO 3166 numeric code, so small integers are not valid and are rejected). Use one of location_code / location_name / location_coordinate. |
| `location_name` | no | Google location name (e.g. 'South Korea'). |
| `location_coordinate` | no | GPS target as 'latitude,longitude,radius_mm' (e.g. '40.7128,-74.0060,200') for local-news radius queries. |
| `language_code` | no | Google language code (e.g. 'en', 'ko'). Default 'en'. Without a location, en and es get the US edition and most other languages their home edition (bn = Bangladesh, ko = South Korea). Region codes such as pt-BR, zh-TW or zh-Hans are accepted and pick that edition. |
| `time_range` | no | Only return articles published within this window: hour, day, week, month, or year. Ignored when from/to is present. Resolution is a calendar DAY on the primary source, so `day` means 'since yesterday', not the last 24 hours; only `hour` is a true rolling window, and it is served by the fallback. (hour \| day \| week \| month \| year) |
| `publisher` | no | Limit results to a single outlet's domain (e.g. 'bbc.com'). Bare domain only, no scheme, no path. Not combinable with location_coordinate or time_range=hour. |
| `from` | no | Start of an exact publish-date window, as YYYY-MM-DD or a Unix timestamp. Overrides time_range. Not combinable with location_coordinate or time_range=hour. |
| `to` | no | End of the publish-date window (inclusive), as YYYY-MM-DD or a Unix timestamp. Defaults to now when only from is set. |
| `since` | no | Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. |
| `until` | no | Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/google_news/search" \
  --data-urlencode "keyword=openai" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I get Google News results with an API?

Send a GET request to /v1/google_news/search with the keyword parameter (e.g. openai). SocialCrawl returns the top news articles as unified JSON: headline, source, snippet, thumbnail, article URL, and absolute UTC publish time.

### What fields does the Google News Search API return?

Each article carries title, source outlet (or host domain), domain, snippet, thumbnail image_url, article url, published_at (absolute UTC), rank, and a placement tag of news_search or top_stories so you can tell the main ranking from the Top Stories carousel.

### How do I filter Google News by recency?

Pass time_range as hour, day, week, month, or year to return only articles from that window, verified in production to return sub-60-minute articles for time_range=hour. It maps to Google's tbs=qdr recency operator.

### Can I control how many news articles come back?

Use depth (default 10, multiples of 10, max 100). Google News exposes at most 200 articles per query with no cursor, so there is no pagination beyond depth. Depth simply widens the single result page.

### How much does the Google News Search API cost?

Each search is a flat 1 credit on the standard tier, no matter the depth. New accounts get 100 free credits with no credit card required, so you can test it before paying anything.

See the full Google News API: https://www.socialcrawl.dev/platforms/google_news

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to search Google News by keyword using the SocialCrawl API
- What does the SocialCrawl Google News Search API return?