{"_id":"@arham-rumi/google-trends-api","_rev":"6-d36ab2e96e1cb1923583cb8dce210faf","name":"@arham-rumi/google-trends-api","dist-tags":{"latest":"0.2.4"},"versions":{"0.1.0":{"name":"@arham-rumi/google-trends-api","version":"0.1.0","keywords":["google-trends","trends","typescript","analytics","search"],"license":"MIT","_id":"@arham-rumi/google-trends-api@0.1.0","maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"homepage":"https://github.com/arham-rumi/google-trends-api#readme","bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"dist":{"shasum":"8242111799ccf0e8bbfa814d902b9d14c99bcf37","tarball":"https://registry.npmjs.org/@arham-rumi/google-trends-api/-/google-trends-api-0.1.0.tgz","fileCount":10,"integrity":"sha512-JlJivHwfPFHMvfpEHh5k4U6Ml3kpLYWTWag538biFpO8EmhXouse/C6VGLJ9LskftXC3FqtpVvzFQyLzqZXQEg==","signatures":[{"sig":"MEQCICIvCWj0LBwrnQUT1jvkvP9RoUarkLLGjcPtMDojPehFAiAbDPfYKMqv78Edm6myQPOBKklyURAWwh337AkZQfxqcA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":371876},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","module":"./dist/index.mjs","engines":{"node":">=22.14.0"},"exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"c02be68373ffdcc98d47ccbc428a2a9ccda36d79","scripts":{"dev":"tsdown --watch","lint":"eslint .","test":"vitest run","build":"tsdown","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run package:check","format":"prettier --write .","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","test:package":"npm run build && node scripts/test-package.mjs","package:check":"npm run build && publint --pack npm && attw --pack .","release:check":"npm run check && npm run test:package && npm publish --dry-run --ignore-scripts","prepublishOnly":"npm run check","test:integration":"vitest run --config vitest.integration.config.ts"},"_npmUser":{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"},"repository":{"url":"git+https://github.com/arham-rumi/google-trends-api.git","type":"git"},"_npmVersion":"12.0.2","description":"Modern, typed, unofficial Google Trends client for Node.js.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.1","dependencies":{"fetch-cookie":"^3.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.8.0","tsdown":"^0.22.14","vitest":"^4.1.10","globals":"^17.8.0","publint":"^0.3.22","prettier":"^3.9.6","@eslint/js":"^10.0.1","typescript":"~6.0.0","@types/node":"^24.13.3","typescript-eslint":"^8.65.0","@arethetypeswrong/cli":"^0.18.5"},"_npmOperationalInternal":{"tmp":"tmp/google-trends-api_0.1.0_1785779199896_0.7801029324417126","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@arham-rumi/google-trends-api","version":"0.2.0","keywords":["google-trends","trends","typescript","analytics","search"],"license":"MIT","_id":"@arham-rumi/google-trends-api@0.2.0","maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"homepage":"https://github.com/arham-rumi/google-trends-api#readme","bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"dist":{"shasum":"0d71e82e7baf28d0e6eca2311fa1ad19434b7d6f","tarball":"https://registry.npmjs.org/@arham-rumi/google-trends-api/-/google-trends-api-0.2.0.tgz","fileCount":10,"integrity":"sha512-C4/Ki/IWgkncae/ku1V0MWXg9pQewRPg+4sZbYooHHplbhCpoGl805+bhHa41Df4Iz2YX9BS0xuvqUxTSLtxyg==","signatures":[{"sig":"MEQCIDzn5IEW+HKGguPExRPW6jmxGWxnErTsYWbshL+hOaEzAiAzXyUryhn6Ngmnu9rzAX7kvhrOgp+Il2Etd/+csynSxQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arham-rumi%2fgoogle-trends-api@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":436399},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","volta":{"node":"24.19.0"},"module":"./dist/index.mjs","engines":{"node":">=22.14.0"},"exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"1ee791589e017196b713799bad269f76ef984463","scripts":{"dev":"tsdown --watch","lint":"eslint .","test":"vitest run","build":"tsdown","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run package:check","format":"prettier --write .","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","test:package":"npm run build && node scripts/test-package.mjs","package:check":"npm run build && publint --pack npm && attw --pack .","release:check":"npm run check && npm run test:package && npm publish --dry-run --ignore-scripts","prepublishOnly":"npm run check","test:integration":"vitest run --config vitest.integration.config.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:dd89ea86-7bd4-4c97-9f0b-a172c68ebd4b"}},"repository":{"url":"git+https://github.com/arham-rumi/google-trends-api.git","type":"git"},"_npmVersion":"12.0.2","description":"Modern, typed, unofficial Google Trends client for Node.js.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","dependencies":{"fetch-cookie":"^3.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.8.0","tsdown":"^0.22.14","vitest":"^4.1.10","globals":"^17.8.0","publint":"^0.3.22","prettier":"^3.9.6","@eslint/js":"^10.0.1","typescript":"~6.0.0","@types/node":"^24.13.3","typescript-eslint":"^8.65.0","@arethetypeswrong/cli":"^0.18.5"},"_npmOperationalInternal":{"tmp":"tmp/google-trends-api_0.2.0_1785864383509_0.9748419999276889","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@arham-rumi/google-trends-api","version":"0.2.1","keywords":["google-trends","trends","typescript","analytics","search"],"license":"MIT","_id":"@arham-rumi/google-trends-api@0.2.1","maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"homepage":"https://github.com/arham-rumi/google-trends-api#readme","bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"dist":{"shasum":"2cf3b63fcf02c5f08991fa1d4921305cb4b7f3f9","tarball":"https://registry.npmjs.org/@arham-rumi/google-trends-api/-/google-trends-api-0.2.1.tgz","fileCount":10,"integrity":"sha512-o+IYqfFChSJJkZ/4A95TJlnGMQxQHBOHpDNwdrM8HjiI3Mg9R1TITEaA9bQwWjijcgX55UH0KcN0OAgJUQDD9g==","signatures":[{"sig":"MEUCIQD7YZkMtFbAuvk9GA7MZ+bWmaTFn7dfp6c0XHbDzm5bOwIgLA8B0apPSM6K2szCZNI3w/ZDjK8POv23Gurp+zwSqV4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arham-rumi%2fgoogle-trends-api@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":451191},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","volta":{"node":"24.19.0"},"module":"./dist/index.mjs","engines":{"node":">=22.14.0"},"exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"a6f433c0d0501cd6ffc64b5d90862accf1ce0ef5","scripts":{"dev":"tsdown --watch","lint":"eslint .","test":"vitest run","build":"tsdown","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run package:check","format":"prettier --write .","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","test:package":"npm run build && node scripts/test-package.mjs","package:check":"npm run build && publint --pack npm && attw --pack .","release:check":"npm run check && npm run test:package && npm publish --dry-run --ignore-scripts","prepublishOnly":"npm run check","test:integration":"vitest run --config vitest.integration.config.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:dd89ea86-7bd4-4c97-9f0b-a172c68ebd4b"}},"repository":{"url":"git+https://github.com/arham-rumi/google-trends-api.git","type":"git"},"_npmVersion":"12.0.2","description":"Modern, typed, unofficial Google Trends client for Node.js.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","dependencies":{"fetch-cookie":"^3.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.8.0","tsdown":"^0.22.14","vitest":"^4.1.10","globals":"^17.8.0","publint":"^0.3.22","prettier":"^3.9.6","@eslint/js":"^10.0.1","typescript":"~6.0.0","@types/node":"^24.13.3","typescript-eslint":"^8.65.0","@arethetypeswrong/cli":"^0.18.5"},"_npmOperationalInternal":{"tmp":"tmp/google-trends-api_0.2.1_1785872266537_0.904285808462004","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@arham-rumi/google-trends-api","version":"0.2.2","keywords":["google-trends","trends","typescript","analytics","search"],"license":"MIT","_id":"@arham-rumi/google-trends-api@0.2.2","maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"homepage":"https://github.com/arham-rumi/google-trends-api#readme","bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"dist":{"shasum":"1e59fe7e9eefb1d09a2fa342dcc121816663aff2","tarball":"https://registry.npmjs.org/@arham-rumi/google-trends-api/-/google-trends-api-0.2.2.tgz","fileCount":10,"integrity":"sha512-QeliE94mSdsx2gbqsQKpmXLj4Wkv4mfo7ctGg3o2ZdILlTmw9M3szmEoEWogU0dA2ZgeGAUIf348ft/4Jfl/3A==","signatures":[{"sig":"MEUCIEWT8wbNGB2dAR4RNIdHcgl/I4EJ0p19AaLNLv8vn2+VAiEA5AD6N/JKGvkh+kbt1RDIval6tdsE3r3RGxXHPDgCwxo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arham-rumi%2fgoogle-trends-api@0.2.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":463452},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","volta":{"node":"24.19.0"},"module":"./dist/index.mjs","engines":{"node":">=22.14.0"},"exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"30087a186877bc3f5a3df6ad81f610465ff69d2a","scripts":{"dev":"tsdown --watch","lint":"eslint .","test":"vitest run","build":"tsdown","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run package:check","format":"prettier --write .","typecheck":"tsc --noEmit","smoke:live":"npm run build && node scripts/live-smoke.mjs","test:watch":"vitest","format:check":"prettier --check .","test:package":"npm run build && node scripts/test-package.mjs","package:check":"npm run build && publint --pack npm && attw --pack .","release:check":"npm run check && npm run test:package && npm publish --dry-run --ignore-scripts","prepublishOnly":"npm run check","test:integration":"vitest run --config vitest.integration.config.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:dd89ea86-7bd4-4c97-9f0b-a172c68ebd4b"}},"repository":{"url":"git+https://github.com/arham-rumi/google-trends-api.git","type":"git"},"_npmVersion":"12.0.2","description":"Modern, typed, unofficial Google Trends client for Node.js.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","dependencies":{"fetch-cookie":"^3.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.8.0","tsdown":"^0.22.14","vitest":"^4.1.10","globals":"^17.8.0","publint":"^0.3.22","prettier":"^3.9.6","@eslint/js":"^10.0.1","typescript":"~6.0.0","@types/node":"^24.13.3","typescript-eslint":"^8.65.0","@arethetypeswrong/cli":"^0.18.5"},"_npmOperationalInternal":{"tmp":"tmp/google-trends-api_0.2.2_1786005754959_0.5735728152778965","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@arham-rumi/google-trends-api","version":"0.2.3","keywords":["google-trends","trends","typescript","analytics","search"],"license":"MIT","_id":"@arham-rumi/google-trends-api@0.2.3","maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"homepage":"https://github.com/arham-rumi/google-trends-api#readme","bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"dist":{"shasum":"c0cbd8862f7a77676751578a1495a5a8c357a771","tarball":"https://registry.npmjs.org/@arham-rumi/google-trends-api/-/google-trends-api-0.2.3.tgz","fileCount":10,"integrity":"sha512-gbfdoGTTJMPe3vGcNUIOBuDQEzmbPf7yVMuFX8inlBRgge4+mxZCbTfLSYc7mHKhiQwG0e/k95BJyVxgIu3OEg==","signatures":[{"sig":"MEUCIQDaD72nZIOe9EZVPT405UKvdfdrmr275LBoi7u+JylNvAIgU8T4EwRgMgLlj/PYnTg/1achIq6YR1dHb9TPQL3LUeM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arham-rumi%2fgoogle-trends-api@0.2.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":463926},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.mts","volta":{"node":"24.19.0"},"module":"./dist/index.mjs","engines":{"node":">=22.14.0"},"exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"40e5cd71bce6ad9e3f40452d73fdf789288114ec","scripts":{"dev":"tsdown --watch","lint":"eslint .","test":"vitest run","build":"tsdown","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run package:check","format":"prettier --write .","typecheck":"tsc --noEmit","smoke:live":"npm run build && node scripts/live-smoke.mjs","test:watch":"vitest","format:check":"prettier --check .","test:package":"npm run build && node scripts/test-package.mjs","package:check":"npm run build && publint --pack npm && attw --pack .","release:check":"npm run check && npm run test:package && npm publish --dry-run --ignore-scripts","prepublishOnly":"npm run check","test:integration":"vitest run --config vitest.integration.config.ts","verify:interest-live":"npm run build && node scripts/verify-interest-over-time-live.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:dd89ea86-7bd4-4c97-9f0b-a172c68ebd4b"}},"repository":{"url":"git+https://github.com/arham-rumi/google-trends-api.git","type":"git"},"_npmVersion":"12.0.2","description":"Modern, typed, unofficial Google Trends client for Node.js.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","dependencies":{"fetch-cookie":"^3.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.8.0","tsdown":"^0.22.14","vitest":"^4.1.10","globals":"^17.8.0","publint":"^0.3.22","prettier":"^3.9.6","@eslint/js":"^10.0.1","typescript":"~6.0.0","@types/node":"^24.13.3","typescript-eslint":"^8.65.0","@arethetypeswrong/cli":"^0.18.5"},"_npmOperationalInternal":{"tmp":"tmp/google-trends-api_0.2.3_1786126124235_0.30759314540963234","host":"s3://npm-registry-packages-npm-production"}},"0.2.4":{"name":"@arham-rumi/google-trends-api","version":"0.2.4","description":"Modern, typed, unofficial Google Trends client for Node.js.","type":"module","license":"MIT","sideEffects":false,"engines":{"node":">=22.14.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/arham-rumi/google-trends-api.git"},"bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"homepage":"https://github.com/arham-rumi/google-trends-api#readme","keywords":["google-trends","trends","typescript","analytics","search"],"scripts":{"build":"tsdown","dev":"tsdown --watch","typecheck":"tsc --noEmit","lint":"eslint .","format":"prettier --write .","format:check":"prettier --check .","test":"vitest run","test:watch":"vitest","test:integration":"vitest run --config vitest.integration.config.ts","package:check":"npm run build && publint --pack npm && attw --pack .","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run package:check","prepublishOnly":"npm run check","test:package":"npm run build && node scripts/test-package.mjs","release:check":"npm run check && npm run test:package && npm publish --dry-run --ignore-scripts","smoke:live":"npm run build && node scripts/live-smoke.mjs","verify:interest-live":"npm run build && node scripts/verify-interest-over-time-live.mjs","verify:region-live":"npm run build && node scripts/verify-interest-by-region-live.mjs","verify:related-queries-live":"npm run build && node scripts/verify-related-queries-live.mjs","verify:related-topics-live":"npm run build && node scripts/verify-related-topics-live.mjs","verify:trending-live":"npm run build && node scripts/verify-trending-now-live.mjs","verify:autocomplete-live":"npm run build && node scripts/verify-autocomplete-live.mjs"},"devDependencies":{"@arethetypeswrong/cli":"^0.18.5","@eslint/js":"^10.0.1","@types/node":"^24.13.3","eslint":"^10.8.0","globals":"^17.8.0","prettier":"^3.9.6","publint":"^0.3.22","tsdown":"^0.22.14","typescript":"~6.0.0","typescript-eslint":"^8.65.0","vitest":"^4.1.10"},"main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.mts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"dependencies":{"fetch-cookie":"^3.2.0"},"volta":{"node":"24.19.0"},"gitHead":"69acc1902a35acee43f3c093cbb64ddac2f8d27c","_id":"@arham-rumi/google-trends-api@0.2.4","_nodeVersion":"24.18.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-8DJ770RhVME8pRto4R+Rxzb/kqy4V9ylPKp/FCRPoCGNfhoA28s5a91/MOID1dJmvxggA+34kN8s35bcoRkmTQ==","shasum":"8ad44cfeea1ca787c75d27f03e5af0c5f32beaa2","tarball":"https://registry.npmjs.org/@arham-rumi/google-trends-api/-/google-trends-api-0.2.4.tgz","fileCount":10,"unpackedSize":469184,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arham-rumi%2fgoogle-trends-api@0.2.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGV+AHkvxDFlX2JAFbmYl3toIYaWOaezfgEbE7ihaEe+AiB/BUfr/Odg2y4CqdMNMCGGcPHf/N72sCrGvrcZlEgtCg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:dd89ea86-7bd4-4c97-9f0b-a172c68ebd4b"}},"directories":{},"maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/google-trends-api_0.2.4_1786132369443_0.7341069181890569"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T17:46:39.709Z","modified":"2026-08-07T19:52:49.947Z","0.1.0":"2026-08-03T17:46:40.026Z","0.2.0":"2026-08-04T17:26:23.668Z","0.2.1":"2026-08-04T19:37:46.694Z","0.2.2":"2026-08-06T08:42:35.115Z","0.2.3":"2026-08-07T18:08:44.418Z","0.2.4":"2026-08-07T19:52:49.633Z"},"bugs":{"url":"https://github.com/arham-rumi/google-trends-api/issues"},"license":"MIT","homepage":"https://github.com/arham-rumi/google-trends-api#readme","keywords":["google-trends","trends","typescript","analytics","search"],"repository":{"type":"git","url":"git+https://github.com/arham-rumi/google-trends-api.git"},"description":"Modern, typed, unofficial Google Trends client for Node.js.","maintainers":[{"name":"arham-rumi","email":"arhamrumi.dev@gmail.com"}],"readme":"# @arham-rumi/google-trends-api\n\n[![CI](https://github.com/arham-rumi/google-trends-api/actions/workflows/ci.yml/badge.svg)](https://github.com/arham-rumi/google-trends-api/actions/workflows/ci.yml)\n[![Live Integration](https://github.com/arham-rumi/google-trends-api/actions/workflows/live-integration.yml/badge.svg)](https://github.com/arham-rumi/google-trends-api/actions/workflows/live-integration.yml)\n\nA modern, typed, unofficial Google Trends client for Node.js.\n\n> This package is not affiliated with, maintained by, or endorsed by Google.\n> It uses endpoints that Google may change without notice.\n\n## Features\n\n- TypeScript-first API with generated declarations\n- ESM and CommonJS builds\n- Interest over time for up to five terms or topics\n- Interest by country, region, city, or DMA\n- Related queries and related topics\n- Trending Now RSS data\n- Search-term and topic autocomplete\n- Cookie-aware sessions, timeouts, retries, abort signals, and typed errors\n- Lazy session warm-up, serialized requests, deduplication, caching, and 429 cooldowns\n\n## Requirements\n\n- Node.js 22.14.0 or newer\n\n## Installation\n\n```bash\nnpm install @arham-rumi/google-trends-api\n```\n\n## Quick start\n\n```ts\nimport { createClient } from '@arham-rumi/google-trends-api';\n\nconst trends = createClient({\n  locale: 'en-US',\n  timeoutMs: 15_000,\n  retries: 2,\n});\n\nconst result = await trends.interestOverTime({\n  keywords: ['node.js', 'deno'],\n  geo: 'US',\n  timeRange: 'today 12-m',\n});\n\nfor (const point of result.timeline) {\n  console.log(point.date, point.values);\n}\n```\n\nGoogle Trends values are normalized relative scores, usually from `0` to `100`. They are not absolute search volumes.\n\n## Rate-limit protection and cache metadata\n\nBy default, the client serializes requests, spaces them by 2.5 seconds, deduplicates identical concurrent calls, and caches successful results for 15 minutes. HTTP 429 responses are never retried immediately. When a stale cached result is available, it is returned during the shared cooldown.\n\n```ts\nimport { getResultMetadata } from '@arham-rumi/google-trends-api';\n\nconst result = await trends.interestOverTime({ keywords: 'node.js' });\nconsole.log(getResultMetadata(result));\n// { source: 'network' | 'cache' | 'stale-cache', stale: boolean, cachedAt?: Date }\n\ntrends.clearCache();\nconsole.log(trends.cooldownRemainingMs);\n```\n\nThe cache is per client instance and stored in memory. It does not bypass Google limits; it reduces avoidable requests and keeps applications useful during temporary 429 periods.\n\n## Client configuration\n\n```ts\nconst trends = createClient({\n  locale: 'en-US',\n  timezone: 0,\n  timeoutMs: 10_000,\n  retries: 2,\n  userAgent: 'my-app/1.0 (+https://example.com)',\n  rateLimit: {\n    minIntervalMs: 2_500,\n    cooldownMs: 60_000,\n  },\n  cache: {\n    ttlMs: 15 * 60_000,\n    staleIfErrorMs: 24 * 60 * 60_000,\n    maxEntries: 100,\n  },\n});\n```\n\n| Option      | Default         | Description                                         |\n| ----------- | --------------- | --------------------------------------------------- |\n| `locale`    | `en-US`         | Locale sent to Google Trends.                       |\n| `timezone`  | `0`             | Google Trends timezone offset in minutes.           |\n| `timeoutMs` | `10000`         | Timeout for each HTTP attempt.                      |\n| `retries`   | `2`             | Additional attempts for temporary non-429 failures. |\n| `userAgent` | Package default | User agent sent with requests.                      |\n| `rateLimit` | See below       | Request spacing and shared HTTP 429 cooldown.       |\n| `cache`     | See below       | Fresh and stale in-memory result caching.           |\n| `fetch`     | Native `fetch`  | Optional custom fetch implementation.               |\n\n## Interest over time\n\n```ts\nconst result = await trends.interestOverTime({\n  keywords: ['typescript', 'javascript'],\n  geo: 'PK',\n  timeRange: 'now 7-d',\n  category: 0,\n  property: '',\n});\n\nconsole.log(result.timeline);\nconsole.log(result.averages);\n```\n\n`keywords` accepts one value or up to five values. A topic machine ID returned by `autocomplete()` can also be used as a keyword.\n\n## Interest by region\n\n```ts\nimport { INTEREST_BY_REGION_RESOLUTIONS, createClient } from '@arham-rumi/google-trends-api';\n\nconsole.log(INTEREST_BY_REGION_RESOLUTIONS);\n\nconst result = await trends.interestByRegion({\n  keywords: 'artificial intelligence',\n  geo: 'US',\n  resolution: 'REGION',\n  includeLowSearchVolumeGeos: true,\n});\n\nconsole.log(result.regions);\n```\n\nSupported resolutions are `COUNTRY`, `REGION`, `CITY`, and `DMA`. Availability depends on the selected geography and Google Trends data.\n\n## Related queries\n\n```ts\nconst results = await trends.relatedQueries({\n  keywords: ['node.js', 'bun'],\n  geo: 'US',\n  timeRange: 'today 3-m',\n});\n\nfor (const result of results) {\n  console.log(result.keyword, result.top, result.rising);\n}\n```\n\n## Related topics\n\n```ts\nconst results = await trends.relatedTopics({\n  keywords: 'machine learning',\n  geo: 'US',\n});\n\nconsole.log(results[0]?.top);\nconsole.log(results[0]?.rising);\n```\n\n## Trending Now\n\n```ts\nconst result = await trends.trendingNow({\n  geo: 'PK',\n  limit: 10,\n});\n\nfor (const trend of result.trends) {\n  console.log(trend.title, trend.approxTraffic, trend.publishedAt);\n}\n```\n\n`geo` must be a two-letter country or territory code.\n\n## Autocomplete\n\n```ts\nconst result = await trends.autocomplete({\n  keyword: 'tesla',\n  limit: 10,\n});\n\nfor (const suggestion of result.suggestions) {\n  console.log(suggestion.kind, suggestion.title, suggestion.keyword);\n}\n```\n\nFor topic suggestions, `suggestion.keyword` is the Google Knowledge Graph machine ID that can be passed to other methods.\n\n## Search properties\n\n```ts\nimport { GOOGLE_TRENDS_PROPERTIES } from '@arham-rumi/google-trends-api';\n\nconsole.log(GOOGLE_TRENDS_PROPERTIES);\n```\n\nValid `property` values are:\n\n| Value       | Search surface  |\n| ----------- | --------------- |\n| `''`        | Web Search      |\n| `'images'`  | Image Search    |\n| `'news'`    | News Search     |\n| `'youtube'` | YouTube Search  |\n| `'froogle'` | Google Shopping |\n\n## Cancellation\n\nEvery public request method accepts an `AbortSignal`:\n\n```ts\nconst controller = new AbortController();\n\nconst request = trends.interestOverTime({\n  keywords: 'node.js',\n  signal: controller.signal,\n});\n\ncontroller.abort();\nawait request;\n```\n\n## Error handling\n\n```ts\nimport {\n  GoogleTrendsError,\n  RateLimitError,\n  RequestTimeoutError,\n  createClient,\n} from '@arham-rumi/google-trends-api';\n\ntry {\n  await createClient().trendingNow({ geo: 'US' });\n} catch (error) {\n  if (error instanceof RateLimitError) {\n    console.error('Rate limited. Retry later.', error.retryAfterMs);\n  } else if (error instanceof RequestTimeoutError) {\n    console.error('Request timed out.');\n  } else if (error instanceof GoogleTrendsError) {\n    console.error(error.code, error.message);\n  } else {\n    throw error;\n  }\n}\n```\n\nExported error classes include:\n\n- `HttpStatusError`\n- `RateLimitError`\n- `RequestTimeoutError`\n- `RequestAbortedError`\n- `NetworkError`\n- `InvalidResponseError`\n- `WidgetNotFoundError`\n\n## CommonJS\n\n```js\nconst { createClient } = require('@arham-rumi/google-trends-api');\n\nconst trends = createClient();\n```\n\n## Development\n\n```bash\nnpm install\nnpm run check\n```\n\nRun the repository example after building:\n\n```bash\nnpm run build\nnode examples/basic.mjs\n```\n\nRun the opt-in live integration suite:\n\n```bash\nnpm run test:integration\n```\n\nRun the broad real-data smoke test against the built package:\n\n```bash\nnpm run smoke:live\n```\n\nRun the deep Interest Over Time validator, which compares parsed package output with the raw Google timeline response for the same request:\n\n```bash\nnpm run verify:interest-live\n```\n\nThe live checks call Google endpoints and may fail when Google changes an endpoint, presents a challenge page, or rate-limits the runner. They intentionally remain separate from the deterministic unit-test pipeline. GitHub Actions runs the live integration suite weekly and also supports manual runs.\n\n## Limitations and responsible use\n\nGoogle Trends does not provide these internal endpoints as a stable public contract. Responses, tokens, rate limits, or endpoint behavior can change. Applications should handle errors, cache appropriate results, avoid high-frequency polling, and comply with applicable Google terms and policies.\n\n## License\n\nMIT © 2026 arham-rumi contributors\n","readmeFilename":"README.md"}