> **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 Trends API. Trends as JSON. Trending searches by place, interest over time, regional interest and related queries for up to five terms, returned as typed JSON with a lookup status on every answer. - Trending by place - Up to 5 terms - 1 credit per request Social Fetch exposes nine routes under `/v1/google-trends`. Two return trending searches: `/trending` returns the full list for a place and window with volume buckets, growth, times, related searches and the trending list's own category ids and names, and `/trending/headlines` returns the ten-item headline list with pictures and news stories. Three routes return the reference trees you need to name inputs: `/suggestions` turns text into topic ids, `/geos` lists countries, subdivisions and US metro areas, and `/categories` lists the explore category ids and names. The other four routes return interest data. `/interest-over-time` compares one to five terms over one range, or one term over two periods, and returns the values as `points[]` with `values`, `hasData`, `label`, `time` and a `period` for two-period answers. `/interest-by-region` returns `regions[]` with a value per term, `hasData` and coordinates for city results where available; DMA rows carry a full place id when the request names a state, and Australia and New Zealand have no city-level breakdown, so that request is refused as a 400. `/related-queries` returns the `top` and `rising` lists for one term, and `/report` returns the time series, regions and related queries for one term in a single request. Every answer uses the `{ data, meta }` envelope. `data.lookupStatus` is `found`, `not_found` or `no_data`; found and no_data answers are HTTP 200, and an input the route refuses is a 400. Branch on the field, not only the status. Interest values are relative to the peak inside the request, not counts. The trending route pages with `page.hasMore` and `page.nextCursor`; the other lists are complete reference trees, fixed-size lists or metric answers. ## What you can get - Trending searches for a country or subdivision with `hours` 4, 24, 48 or 168, optional `category`, `active` and `sort`, and a cursor for the next page. - The ten-item headline list with `searchVolume.label`, `startedAt`, a picture and up to three `news[]` items. - Topic suggestions with the Knowledge Graph id to send back as `id:/m/...` in an explore query. - The full place tree, 250 countries, 3,130 subdivisions and 301 US metro areas, flattened with `level` and `parentId`. - The explore category tree, 1,426 nodes, flattened with `level`, `parentId` and a unique `path` from the root so repeated ids stay distinct by branch. The trending list has its own smaller category set. - Interest over time and by region for one to five terms, with the answer's `resolution`, `notes` and data-gap flags. - `top` and `rising` related queries, including breakout rows, and a combined `report` with the time series, regions and related queries together. ## Google Trends endpoints | Endpoint | Request | Credits | Docs | | --- | --- | --- | --- | | Trending | GET /v1/google-trends/trending | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/trending/get) | | Trending headlines | GET /v1/google-trends/trending/headlines | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/trending/headlines/get) | | Topic suggestions | GET /v1/google-trends/suggestions | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/suggestions/get) | | Places | GET /v1/google-trends/geos | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/geos/get) | | Categories | GET /v1/google-trends/categories | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/categories/get) | | Interest over time | GET /v1/google-trends/interest-over-time | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/interest-over-time/get) | | Interest by region | GET /v1/google-trends/interest-by-region | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/interest-by-region/get) | | Related queries | GET /v1/google-trends/related-queries | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/related-queries/get) | | Report | GET /v1/google-trends/report | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/google-trends/report/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 Trends route. 2. **Name the place and the terms.** Use a country code such as `US` or `DE`, or a subdivision such as `US-CA`; `/geos` lists the places the explore routes accept, while the trending list serves countries and most subdivisions. Terms are plain text or a topic id from `/suggestions`, and an explore request takes up to five of them. 3. **Check the status and the shape.** Read `data.lookupStatus` before using a row, follow `page.nextCursor` while `page.hasMore` is true, and bill from `meta.creditsCharged`. ## Pricing Every Google Trends route costs one credit per completed request, shown on each endpoint page. One trending response is one request even when it returns many rows; following a cursor is a new request. `meta.creditsCharged` on the response is the billing source of truth, and credits never expire on pay-as-you-go packs. ## Compared with the official API The Google Trends website shows one chart at a time, and its exports are arranged for spreadsheets. Social Fetch returns the same kinds of answers as JSON: `trends[]`, `points[]`, `regions[]`, `top` and `rising`, with ISO 8601 times, numeric volume buckets, a lookup status and a cursor. One request can compare up to five terms, and the reference routes return ids you can pass straight back as parameters. ## FAQ ### What can I get from the Google Trends API? Nine routes: trending searches, trending headlines, topic suggestions, the place list, the category list, interest over time, interest by region, related queries and a combined report. Each is a GET under /v1/google-trends and costs one credit per completed request. ### How do I read trending searches for a country? Call GET /v1/google-trends/trending with geo set to a code from the place list and hours set to 4, 24, 48 or 168. Optional filters are category, active and sort; limit takes 1 to 100 rows. Read trends[] and follow page.nextCursor while page.hasMore is true. ### What does lookupStatus mean? found means the answer contains data. not_found means there is no such place or entity. no_data means the answer is valid but has no values for the request. Interest-by-region and report return no_data with no place marked as having data when the term has no data. found, not_found and no_data are HTTP 200; an input the route refuses (an unsupported geo or category, for example) is a 400. Check data.lookupStatus as well as the status code. ### How many terms can I compare? Interest over time and interest by region take one to five terms in query, comma-separated or repeated. Repeat the parameter when a term itself contains a comma. Related queries and the combined report take one term. Interest over time also accepts two time ranges for a single term; two named ranges must be the same length, while custom ranges may differ. ### What time ranges are accepted? Named ranges are now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y and all. A custom range is YYYY-MM-DD YYYY-MM-DD, with an optional THH hour on either end. Two named ranges in a comparison must be the same length and the two ranges must differ; custom ranges may differ in length. A malformed, inverted or future range is refused before any lookup, and a custom range that ends before January 2004 is refused because Google Trends has no data there. ### How do I send a topic instead of a text term? Call GET /v1/google-trends/suggestions?query=coffee. Each item in topics[] has an id such as /m/02vqfm, a title and a type. Send id:/m/02vqfm as the term to mean that topic rather than the text. ### What do the interest values mean? Values are 0 to 100 and are relative to the peak inside that one request, so they cannot be compared across requests. Each point has values and hasData arrays with one entry per term, and each region row has the same. A false entry in hasData means there was no figure there. ### Are the place and category lists complete? geos returns 250 countries, 3,130 subdivisions and 301 US metro areas when unfiltered, and categories returns 1,426 explore nodes. Both are flattened with level and parentId. Explore category ids repeat in different branches, and the same id and parentId can repeat too, so match on path (the ancestor ids from the root through the row), which is unique, rather than treating the id as unique. Trending uses its own category ids and returns their names on each row. ### How much does the Google Trends API cost? One credit per completed request on every route. Following a trending cursor is another request. meta.creditsCharged on each response is the billing source of truth, and new accounts start with 100 free credits. ### Can I use these routes from an agent or MCP? Yes. Each route is a typed MCP tool and can be reached through Ask in plain English. Use the typed routes for production jobs where you need the exact fields. ## Related - [Google Trends Trending API](https://www.socialfetch.dev/platforms/google-trends/trending): Trending searches with volume, growth and paging (`GET /v1/google-trends/trending`). - [Google Trends Interest Over Time API](https://www.socialfetch.dev/platforms/google-trends/interest-over-time): One to five terms as a time series (`GET /v1/google-trends/interest-over-time`). - [Google Trends Interest by Region API](https://www.socialfetch.dev/platforms/google-trends/interest-by-region): Interest by place, including city coordinates where available (`GET /v1/google-trends/interest-by-region`). - [Google Trends Report API](https://www.socialfetch.dev/platforms/google-trends/report): Time series, regions and related queries in one request (`GET /v1/google-trends/report`). - [Ask in plain English](https://www.socialfetch.dev/ask): Route a natural-language trends question to the matching Google Trends operation. - [Hosted MCP](https://www.socialfetch.dev/mcp): Call Google Trends tools from Cursor or Claude with the same credit metering as REST.