# Universal Search News API (https://www.socialcrawl.dev/platforms/search/news)

> Plans your query into search angles, localizes each angle into the language of every requested country edition (one combined LLM call, fail-open), then fans out up to 12 parallel legs against Google News (50 supported country editions) and merges the articles into one deduplicated list. Every leg reports truthful provenance: `query_source` says whether its keyword was `translated`, confirmed `original`, or a `fallback_original` after a localization failure. Supports streaming via `Accept: text/event-stream` (the `plan_refined` chunk always carries the expanded legs with per-leg provenance before any leg settles) and sync via `Accept: application/json`. Filters: `publisher`, `from`/`to` exact date windows (these pin legs to the primary source), `time_range` recency, `depth` per-leg article depth, `max_legs` cost cap. Billing is metered: a base fee covers planning, then 1 credit per leg that returned articles; the unused ceiling is refunded automatically.

TL;DR: `GET /v1/search/news` costs 2 credits + 1 credit per country/angle leg that returns at least one article. The upfront hold is 2 + min(5 x countries, max_legs, 12) credits (maximum 14) and settles down to the actual charge; empty or failed legs bill 0. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | News topic or question (1-500 chars). Boolean AND/OR/NOT and quoted phrases are supported; Google advanced operators (site:, intitle:, before:) are rejected. |
| `countries` | no | CSV of ISO 3166-1 alpha-2 country codes to search (1-12 of the 50 supported editions, default US). Each country searches its Google News edition in its default language; duplicates collapse. |
| `time_range` | no | Recency window (day \| week \| month \| year, default day). Ignored when from/to is present. (day \| week \| month \| year) |
| `from` | no | Lower publish-date bound, YYYY-MM-DD or Unix seconds. Pins every leg to the primary news source. |
| `to` | no | Upper publish-date bound, YYYY-MM-DD or Unix seconds. Pins every leg to the primary news source. |
| `publisher` | no | Bare publisher domain filter (e.g. bbc.com; no scheme or path). Pins every leg to the primary news source. |
| `depth` | no | Articles requested per leg (10-100 in steps of 10, default 10). |
| `max_legs` | no | Hard cap on billable legs (1-12, default 12). The upfront hold shrinks with it. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/search/news?query=samsung%20galaxy%20launch" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### What is the SocialCrawl news search API?

GET /v1/search/news takes one query, plans it into search angles with an LLM, localizes each angle into the target languages, and fans it out across Google News country editions in parallel. You get one deduplicated article list with per-country, per-language provenance on every item.

### Which countries can I search news in?

50 country editions, from the United States and the United Kingdom to South Korea, Japan, Germany, and Brazil. Pass countries as a CSV of ISO codes (countries=KR,US,JP) and the lane searches up to 12 countries in one call, each in its edition's own language.

### How much does a news search cost?

Each call starts at 2 credits and adds 1 credit per country leg that actually returns articles, so the total lands between 2 and 14 credits. A search that finds nothing bills the 2-credit base only, and if every leg fails outright the whole charge is refunded automatically.

### How does the query localization work?

One combined LLM call plans the search angles and writes each one natively in the target languages, so the Korean edition is searched in Korean and the Japanese edition in Japanese. Every result row carries a query_source stamp (translated, original, or fallback_original) so you can always see exactly which query text a leg ran.

### Can I stream news results as they arrive?

Yes. Send Accept: text/event-stream and you get typed SSE chunks: the refined plan with per-leg provenance first, then each country's articles as its leg settles, then a done summary with the exact credits used. The default Accept: application/json returns one synchronous envelope.

See the full Universal Search API: https://www.socialcrawl.dev/platforms/search

## 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 do I search Google News in multiple countries with one API call?
- Which news API localizes the query into each country's language automatically?