# google_trends.trending **stable** **Standard** Google Trends 'Trending now' searches for a country or region (query, approximate traffic, top news). `GET /v1/google_trends/trending` ## What you get A list of Google Trends results in Onekey's unified shape, in `data` (an array). An empty array is a normal, successful answer and is charged like any other; a source that reports "nothing found" as an error returns a free `404 not_found` instead. **Also known as:** `/google_trends/explore` on APIs that nest their paths. See [Alternatives and equivalents](https://onekey.dev/docs/alternatives.md). ## What it costs - **Standard · 1 credit** for a fresh fetch, charged only when it succeeds. - **Free when served from cache (0.2 credit for a cached response over 100 KB).** - **Free** if the request is invalid (never charged) or the source fails or reports not found (refunded). ## Parameters | Name | Type | Required | Default | What it is | Constraints | | --- | --- | --- | --- | --- | --- | | `location` | string | no | `US` | ISO country code (US, DE) or ISO 3166-2 region (US-CA); uppercase | max 6 chars; must match `[A-Z]{2}(?:-[A-Z0-9]{1,3})?`; trimmed | ## Request ```bash curl "https://api.onekey.dev/v1/google_trends/trending?location=US" \ -H "x-api-key: YOUR_API_KEY" ``` ```python import requests res = requests.get( "https://api.onekey.dev/v1/google_trends/trending", params={"location": "US"}, headers={"x-api-key": "YOUR_API_KEY"}, ) body = res.json() if body["success"]: print(body["data"]) else: print(body["error"]["code"], body["error"]["message"]) ``` ```javascript const params = new URLSearchParams({ location: "US" }); const res = await fetch(`https://api.onekey.dev/v1/google_trends/trending?${params}`, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const body = await res.json(); if (body.success) console.log(body.data); else console.error(body.error.code, body.error.message); ``` ## Recorded response A real Google Trends response, recorded and returned in Onekey's shape. Fields the platform does not provide are `null`. ```json { "success": true, "data": [ { "content": { "title": "retirement age", "createdAt": "2026-10-01T19:20:00Z", "url": "https://trends.google.com/trends/explore?q=retirement%20age" }, "engagement": { "views": 1000 }, "media": { "url": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQ8r9B056BoWLYtt836ugTr84LbhUBGgiiqCFve-t7IRIEeFJi1P3yl5K54O3I" }, "ext": { "topNewsUrl": "https://www.cnbc.com/2026/10/01/claiming-age-clarity-act-social-security.html", "news": [ { "title": "Social Security claiming ages may soon get new names. What retirees need to know", "url": "https://www.cnbc.com/2026/10/01/claiming-age-clarity-act-social-security.html", "source": "CNBC", "snippet": null }, { "title": "Smucker’s Bipartisan Claiming Age Clarity Act Heads to President’s Desk", "url": "https://smucker.house.gov/media/press-releases/smuckers-bipartisan-claiming-age-clarity-act-heads-presidents-desk", "source": "Congressman Lloyd Smucker (.gov)", "snippet": null } ] } }, { "content": { "title": "speea", "createdAt": "2026-10-01T19:20:00Z", "url": "https://trends.google.com/trends/explore?q=speea" }, "engagement": { "views": 1000 }, "media": { "url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcQZ3rRekmYbjj7k6xYOXgR_mYMt29czrxHpSXpouKrUZkMcXCtobjj6--Cvvok" }, "ext": { "topNewsUrl": "https://www.king5.com/article/tech/science/aerospace/boeing-engineers-technical-workers-face-noon-deadline-vote-contract-offer/281-5094fa91-7065-41ad-9d0e-4f01d060dde1", "news": [ { "title": "Boeing engineers, technical workers face noon deadline to vote on contract offer", "url": "https://www.king5.com/article/tech/science/aerospace/boeing-engineers-technical-workers-face-noon-deadline-vote-contract-offer/281-5094fa91-7065-41ad-9d0e-4f01d060dde1", "source": "KING5.com", "snippet": null }, { "title": "Boeing SPEEA engineers reject contract, authorize strike", "url": "https://finance.yahoo.com/markets/stocks/articles/boeing-speea-engineers-reject-contract-174049112.html", "source": "Yahoo Finance", "snippet": null } ] } } ], "metadata": { "platform": "google_trends", "endpoint": "trending", "cached": false, "stale": false, "age_s": 0, "fetched_at": "2026-01-01T12:00:00+00:00", "credits_charged": 1, "request_id": "7f3a9c2e5b1d4c8fa2e6d0b9c4f18e37" }, "error": null } ``` ## Field mapping How this endpoint's source fields become Onekey's [unified schema](https://onekey.dev/docs/schema.md). Fields the source lacks come back as `null`. | Source path | Onekey field | Transform | | --- | --- | --- | | `query` | `content.title` | - | | `approxTraffic` | `engagement.views` | `toNumber` | | `publishedAt` | `content.createdAt` | `toIsoDate` | | `imageUrl` | `media.url` | `safeUrl` | | `exploreUrl` | `content.url` | `safeUrl` | | `topNewsUrl` | `ext.topNewsUrl` | `safeUrl` | | `news` | `ext.news` | - | ## Caching and freshness - Fresh for about 30 seconds. Repeat calls in that window are served from cache and are free. - Between 30 seconds and 5 minutes the cached copy is still served instantly and marked `stale: true` while Onekey refreshes it in the background. - If the source is down when a refresh is needed, the last copy can be served for up to 15 minutes more (marked stale). - A "not found" is remembered for 1 minute and is free. - The cache is shared across all customers, which is what keeps repeat calls cheap. ## What can go wrong | Status | Code | What to do | | --- | --- | --- | | 401 | `unauthorized` | Check the `x-api-key` header. | | 402 | `insufficient_credits` | [Add credits](https://onekey.dev/pricing); your balance must cover the price. | | 404 | `not_found` | Unknown endpoint path. | | 422 | `invalid_params` | Fix the parameters using the table above. Free. | | 429 | `rate_limited` | Wait `Retry-After` seconds, then retry. | | 502 | `upstream_error` | The source failed. Refunded; retry with backoff. | See [Errors](https://onekey.dev/docs/errors.md) for the full list and retry guidance. Status: stable (verified against the live source).