> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt). ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** --- # Google News API. One JSON shape for the whole edition. Search, top stories, topics, publishers, Full Coverage stories and article links, with the edition, source and publisher URL on every article. Pick a supported language and country, get JSON. - Supported editions - Typed not_found - 1 credit per request Social Fetch exposes eleven routes under `/v1/google-news`. Search takes words and the operators the edition understands, plus a time window. Top stories returns story clusters, with the other outlets covering each lead in `relatedArticles`. Headlines groups articles by section, and the home route returns the edition's briefing and navigation. Topic routes take the ids other routes return. `topics/resolve` turns a place, section, Knowledge Graph MID or name into a topic or publisher id, and `topics/{topicId}` returns that topic's stream. A sub-tab id from `topic.tabs` returns one tab. Publishers take a `source.publicationId` from an article record. `stories/{storyId}` returns a Full Coverage story, and `articles/resolve` turns up to ten article ids into publisher URLs. Every response uses the `{ data, meta }` envelope. An id that does not exist comes back as `lookupStatus: not_found` with the object null, not an HTTP error. Publisher streams are scoped to the edition: pass the outlet's own language and country, or a real publisher can come back as found with an empty list and `streamStatus: unavailable`. Articles carry `id`, `title`, `publishedAt`, `source`, `authors`, `image`, `storyId`, `clusterHeadline` and `relatedArticles`, so search and topic results share one shape. Editions are a `language` and `country` pair. The supported pairs include `en-US`/`US`, `en-GB`/`GB`, `de`/`DE`, `ja`/`JP`, `pt-BR`/`BR` and `iw`/`IL`; `language=en` with `country=US` selects `en-US`. A pair outside the supported list is rejected with a 400 that lists every supported pair. The edition is returned on every response. ## What you can get - Search the edition with words, quotes, `site:`, `intitle:`, `source:`, `OR`, `-term`, `when:`, `after:` and `before:`. - Top stories as clusters, each lead article carrying up to four more outlets in `relatedArticles`. - Topic streams with the publisher URL, image, authors, label, Full Coverage `storyId` and `clusterHeadline`. - Headlines grouped by section, up to 50 groups and 200 articles per answer. - Publishers by `source.publicationId`, with recent articles and the publisher record. - Full Coverage stories by `storyId`, with the articles from different outlets. - Article ids resolved to publisher URLs, up to ten per request. - Place, section, MID and name resolution to a topic or publisher id, with the other candidates. ## Google News endpoints | Endpoint | Request | Credits | Docs | | --- | --- | --- | --- | | Search | GET /v1/google-news/search | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/search/get) | | Top stories | GET /v1/google-news/top-stories | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/top-stories/get) | | Suggestions | GET /v1/google-news/suggest | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/suggest/get) | | Headlines | GET /v1/google-news/headlines | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/headlines/get) | | Home briefing | GET /v1/google-news/home | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/home/get) | | Sections | GET /v1/google-news/sections | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/sections/get) | | Resolve topic | GET /v1/google-news/topics/resolve | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/topics/resolve/get) | | Topic articles | GET /v1/google-news/topics/{topicId} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/topics/topicid/get) | | Full Coverage | GET /v1/google-news/stories/{storyId} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/stories/storyid/get) | | Publisher articles | GET /v1/google-news/publishers/{publicationId} | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/publishers/publicationid/get) | | Resolve article links | GET /v1/google-news/articles/resolve | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-news/articles/resolve/get) | ## How to start 1. **Create an API key.** Sign up at Social Fetch and copy a key (`sfk_…`). New accounts get 100 free credits, enough to try every Google News route across a few editions. 2. **Pick an edition and a route.** Send `language` and `country`, for example `GET /v1/google-news/top-stories?language=en-US&country=US` or `GET /v1/google-news/search?query=openai&when=7d&language=en-US&country=US`. Send `x-api-key` on every request. 3. **Resolve, then read.** Use `topics/resolve` to turn a name or place into an id, or read `source.publicationId` and `storyId` from an article. Then call the topic, publisher or story route. Check `data.lookupStatus` before you store a row. ## Pricing Each Google News route charges one credit per completed request, and each search page is its own request. Credits never expire on pay-as-you-go packs, and `meta.creditsCharged` on every response is the billing source of truth. ## Compared with the official API Google News does not publish one general read API for search, topic streams, publishers, Headlines and Full Coverage stories. Social Fetch puts those surfaces behind one base URL and one article shape: the same `id`, `title`, `source`, `image`, `authors`, `storyId` and `clusterHeadline` fields whether the article came from search, a topic or a story. A not_found answer is a typed status, not a special page, and every route is metered the same way. ## FAQ ### What can I get from the Google News API? Eleven routes: search, top stories, topic streams, topic resolution, Full Coverage stories, publisher articles, navigation sections, the home briefing, Headlines by section, topic and publisher suggestions, and article-link resolution. Every route returns the `{ data, meta }` envelope. ### How do I choose an edition? Send a supported `language` and `country` pair, for example `en-US` and `US`, `en-GB` and `GB`, `de` and `DE`, or `ja` and `JP`. You can send the language family with a country, so `en` with `US` selects the `en-US` edition. An unsupported pair is rejected with a 400 that lists every supported pair. The resolved edition is returned in `data.edition`. ### How does search paging work? The first search call returns the ranked Google News results, about 100 articles. When it pages, the first `page.nextCursor` covers today's Pacific day, then each later cursor one older day, with an `after:` plus `before:` bound, up to 100 items per window. With an `after` and `before` range, the first cursor covers the last day of that range, then earlier days down to `after`. A busier window is cut short; `page.windowFull` is true when that happened, so you can tell a complete window from a truncated one. A first call with `after`, `before` or `when` already has a date bound, and it says so too. The walk stops after seven empty days or at your own `after`/`when` floor. Keep the effective `query`; a cursor cannot be combined with `when`, `after`, or `before`. ### Why would a topic return no articles? Some entity topics have no stories for a period. The answer is still `lookupStatus: found` with `articles: []`, because the topic exists. Do not retry it as a miss; a genuinely unknown topic returns `not_found` with `topic: null`. ### How do I go from an article to its publisher or Full Coverage story? Read `source.publicationId` and pass it to `GET /v1/google-news/publishers/{publicationId}` with the outlet's own language and country. Read `storyId` and pass it to `GET /v1/google-news/stories/{storyId}`. Both fields are null when the article record does not carry them. ### How do I resolve a place, section or name to a topic id? Call `GET /v1/google-news/topics/resolve` with exactly one of `place`, `section`, `mid` or `query`. The answer carries `resolved` plus `candidates` from the suggestion box. `resolved.matchedInput` is false when a place name fell back to the U.S. topic, for example an unknown place resolving to `U.S.`; an unknown place can also return `not_found`. A localised name for a real place, such as München for Munich, is still a match. ### How do I turn article ids into publisher URLs? Call `GET /v1/google-news/articles/resolve?ids=…` with 1 to 10 article ids, comma-separated. Each entry in `results` is `{ id, url }` in request order. `url` is null when it is not available, which is a normal answer rather than a failure. ### Are publisher links and images included? `url` is the publisher article URL on topic, story, publisher and Headlines results. It is null on search and top-stories results, where `googleUrl` is the Google News link; call `articles/resolve` to turn those ids into publisher URLs. `image` is the publisher's image with its width and height. Authors, labels and favicons come through when the record has them. ### How much does the Google News API cost? Each route charges one credit per completed request, and each search page is a separate request. Check `meta.creditsCharged` on every response. New accounts start with 100 free credits. ### Does HTTP 200 mean the topic, story or publisher exists? No. HTTP 200 means the request finished. Check `data.lookupStatus`: `not_found` means the id does not exist or the story has expired, and the object is null. For a publisher, also check `streamStatus`: an outlet requested in the wrong language and country is found with an empty list and `streamStatus: unavailable`. ## Related - [Google News Search API](https://www.socialfetch.dev/platforms/google-news/search): Search by words, operators, edition and time window (`GET /v1/google-news/search`). - [Google News Topic API](https://www.socialfetch.dev/platforms/google-news/topics-topicid): Get a topic, tab or publisher stream (`GET /v1/google-news/topics/{topicId}`). - [Google News Full Coverage API](https://www.socialfetch.dev/platforms/google-news/stories-storyid): A story's articles from different outlets (`GET /v1/google-news/stories/{storyId}`). - [Google News Article Link API](https://www.socialfetch.dev/platforms/google-news/articles-resolve): Resolve up to ten article ids to publisher URLs (`GET /v1/google-news/articles/resolve`). - [Ask in plain English](https://www.socialfetch.dev/ask): Route a natural-language news question to the matching Google News operation. - [Hosted MCP](https://www.socialfetch.dev/mcp): Call Google News tools from Cursor or Claude with the same credit metering as REST.