@shaivpidadi/trends-js 0.0.0-beta.7 → 1.0.0

package/README.md

@@ -1,8 +1,11 @@
-🚧 WIP: Temporary workaround for [#175](https://github.com/pat310/google-trends-api/issues/175)
+A TypeScript library for interacting with the Google Trends API. This package provides a simple and type-safe way to access Google Trends data programmatically.
 
-# @shaivpidadi/trends-js
+## Showcase
+
+### EliteTimesNews.com — Built with `@shaivpidadi/trends-js`
+**URL:** https://elitetimesnews.com  
+**What it uses:** `dailyTrends()` (US, en) to power the home page “Daily Trending” rail, refreshed on a schedule.
 
-A TypeScript library for interacting with the Google Trends API. This package provides a simple and type-safe way to access Google Trends data programmatically.
 
 ## Installation
 
@@ -17,6 +20,9 @@ npm install @shaivpidadi/trends-js
 - Get autocomplete suggestions
 - Explore trends data
 - Get interest by region data
+- Get related topics for any keyword
+- Get related queries for any keyword
+- Get combined related data (topics + queries)
 - TypeScript support
 - Promise-based API
 
@@ -33,9 +39,9 @@ import GoogleTrendsApi from '@shaivpidadi/trends-js';
 Get daily trending topics for a specific region:
 
 ```typescript
-const result = await GoogleTrendsApi.dailyTrends({ 
-  geo: 'US',  // Default: 'US'
-  lang: 'en'  // Default: 'en'
+const result = await GoogleTrendsApi.dailyTrends({
+  geo: 'US', // Default: 'US'
+  lang: 'en', // Default: 'en'
 });
 
 // Result structure:
@@ -50,9 +56,9 @@ const result = await GoogleTrendsApi.dailyTrends({
 Get real-time trending topics:
 
 ```typescript
-const result = await GoogleTrendsApi.realTimeTrends({ 
-  geo: 'US',           // Default: 'US'
-  trendingHours: 4     // Default: 4
+const result = await GoogleTrendsApi.realTimeTrends({
+  geo: 'US', // Default: 'US'
+  trendingHours: 4, // Default: 4
 });
 
 // Result structure:
@@ -68,8 +74,8 @@ Get search suggestions for a keyword:
 
 ```typescript
 const suggestions = await GoogleTrendsApi.autocomplete(
-  'bitcoin',           // Keyword to get suggestions for
-  'en-US'              // Language (default: 'en-US')
+  'bitcoin', // Keyword to get suggestions for
+  'en-US', // Language (default: 'en-US')
 );
 
 // Returns: string[]
@@ -80,13 +86,13 @@ const suggestions = await GoogleTrendsApi.autocomplete(
 Get widget data for a keyword:
 
 ```typescript
-const result = await GoogleTrendsApi.explore({ 
+const result = await GoogleTrendsApi.explore({
   keyword: 'bitcoin',
-  geo: 'US',           // Default: 'US'
-  time: 'today 12-m',  // Default: 'today 12-m'
-  category: 0,         // Default: 0
-  property: '',        // Default: ''
-  hl: 'en-US'         // Default: 'en-US'
+  geo: 'US', // Default: 'US'
+  time: 'today 12-m', // Default: 'today 12-m'
+  category: 0, // Default: 0
+  property: '', // Default: ''
+  hl: 'en-US', // Default: 'en-US'
 });
 
 // Result structure:
@@ -104,15 +110,15 @@ const result = await GoogleTrendsApi.explore({
 Get interest data by region:
 
 ```typescript
-const result = await GoogleTrendsApi.interestByRegion({ 
-  keyword: 'Stock Market',           // Required - string or string[]
+const result = await GoogleTrendsApi.interestByRegion({
+  keyword: 'Stock Market', // Required - string or string[]
   startTime: new Date('2024-01-01'), // Optional - defaults to 2004-01-01
-  endTime: new Date(),               // Optional - defaults to current date
-  geo: 'US',                         // Optional - string or string[] - defaults to 'US'
-  resolution: 'REGION',              // Optional - 'COUNTRY' | 'REGION' | 'CITY' | 'DMA'
-  hl: 'en-US',                      // Optional - defaults to 'en-US'
-  timezone: -240,                   // Optional - defaults to local timezone
-  category: 0                       // Optional - defaults to 0
+  endTime: new Date(), // Optional - defaults to current date
+  geo: 'US', // Optional - string or string[] - defaults to 'US'
+  resolution: 'REGION', // Optional - 'COUNTRY' | 'REGION' | 'CITY' | 'DMA'
+  hl: 'en-US', // Optional - defaults to 'en-US'
+  timezone: -240, // Optional - defaults to local timezone
+  category: 0, // Optional - defaults to 0
 });
 
 // Result structure:
@@ -137,13 +143,104 @@ const result = await GoogleTrendsApi.interestByRegion({
 Example with multiple keywords and regions:
 
 ```typescript
-const result = await GoogleTrendsApi.interestByRegion({ 
+const result = await GoogleTrendsApi.interestByRegion({
   keyword: ['wine', 'peanuts'],
   geo: ['US-CA', 'US-VA'],
   startTime: new Date('2024-01-01'),
   endTime: new Date(),
-  resolution: 'CITY'
+  resolution: 'CITY',
+});
+```
+
+### Related Topics
+
+Get related topics for any keyword:
+
+```typescript
+const result = await GoogleTrendsApi.relatedTopics({
+  keyword: 'artificial intelligence', // Required
+  geo: 'US', // Optional - defaults to 'US'
+  time: 'now 1-d', // Optional - defaults to 'now 1-d'
+  category: 0, // Optional - defaults to 0
+  property: '', // Optional - defaults to ''
+  hl: 'en-US', // Optional - defaults to 'en-US'
+});
+
+// Result structure:
+// {
+//   data: {
+//     default: {
+//       rankedList: Array<{
+//         rankedKeyword: Array<{
+//           topic: {
+//             mid: string,
+//             title: string,
+//             type: string
+//           },
+//           value: number,
+//           formattedValue: string,
+//           hasData: boolean,
+//           link: string
+//         }>
+//       }>
+//     }
+//   }
+// }
+```
+
+### Related Queries
+
+Get related queries for any keyword:
+
+```typescript
+const result = await GoogleTrendsApi.relatedQueries({
+  keyword: 'machine learning', // Required
+  geo: 'US', // Optional - defaults to 'US'
+  time: 'now 1-d', // Optional - defaults to 'now 1-d'
+  category: 0, // Optional - defaults to 0
+  property: '', // Optional - defaults to ''
+  hl: 'en-US', // Optional - defaults to 'en-US'
+});
+
+// Result structure:
+// {
+//   data: {
+//     default: {
+//       rankedList: Array<{
+//         rankedKeyword: Array<{
+//           query: string,
+//           value: number,
+//           formattedValue: string,
+//           hasData: boolean,
+//           link: string
+//         }>
+//       }>
+//     }
+//   }
+// }
+```
+
+### Combined Related Data
+
+Get both related topics and queries in a single call:
+
+```typescript
+const result = await GoogleTrendsApi.relatedData({
+  keyword: 'blockchain', // Required
+  geo: 'US', // Optional - defaults to 'US'
+  time: 'now 1-d', // Optional - defaults to 'now 1-d'
+  category: 0, // Optional - defaults to 0
+  property: '', // Optional - defaults to ''
+  hl: 'en-US', // Optional - defaults to 'en-US'
 });
+
+// Result structure:
+// {
+//   data: {
+//     topics: Array<RelatedTopic>,
+//     queries: Array<RelatedQuery>
+//   }
+// }
 ```
 
 ## API Reference
@@ -152,7 +249,7 @@ const result = await GoogleTrendsApi.interestByRegion({
 
 ```typescript
 interface DailyTrendsOptions {
-  geo?: string;  // Default: 'US'
+  geo?: string; // Default: 'US'
   lang?: string; // Default: 'en'
 }
 ```
@@ -171,11 +268,11 @@ interface RealTimeTrendsOptions {
 ```typescript
 interface ExploreOptions {
   keyword: string;
-  geo?: string;           // Default: 'US'
-  time?: string;          // Default: 'today 12-m'
-  category?: number;      // Default: 0
-  property?: string;      // Default: ''
-  hl?: string;           // Default: 'en-US'
+  geo?: string; // Default: 'US'
+  time?: string; // Default: 'today 12-m'
+  category?: number; // Default: 0
+  property?: string; // Default: ''
+  hl?: string; // Default: 'en-US'
 }
 ```
 
@@ -183,14 +280,63 @@ interface ExploreOptions {
 
 ```typescript
 interface InterestByRegionOptions {
-  keyword: string | string[];        // Required - search term(s)
-  startTime?: Date;                  // Optional - start date
-  endTime?: Date;                    // Optional - end date
-  geo?: string | string[];           // Optional - geocode(s)
+  keyword: string | string[]; // Required - search term(s)
+  startTime?: Date; // Optional - start date
+  endTime?: Date; // Optional - end date
+  geo?: string | string[]; // Optional - geocode(s)
   resolution?: 'COUNTRY' | 'REGION' | 'CITY' | 'DMA'; // Optional
-  hl?: string;                       // Optional - language code
-  timezone?: number;                 // Optional - timezone offset
-  category?: number;                 // Optional - category number
+  hl?: string; // Optional - language code
+  timezone?: number; // Optional - timezone offset
+  category?: number; // Optional - category number
+}
+```
+
+### RelatedTopicsResponse
+
+```typescript
+interface RelatedTopicsResponse {
+  default: {
+    rankedList: Array<{
+      rankedKeyword: Array<{
+        topic: {
+          mid: string;
+          title: string;
+          type: string;
+        };
+        value: number;
+        formattedValue: string;
+        hasData: boolean;
+        link: string;
+      }>;
+    }>;
+  };
+}
+```
+
+### RelatedQueriesResponse
+
+```typescript
+interface RelatedQueriesResponse {
+  default: {
+    rankedList: Array<{
+      rankedKeyword: Array<{
+        query: string;
+        value: number;
+        formattedValue: string;
+        hasData: boolean;
+        link: string;
+      }>;
+    }>;
+  };
+}
+```
+
+### RelatedData
+
+```typescript
+interface RelatedData {
+  topics: Array<RelatedTopic>;
+  queries: Array<RelatedQuery>;
 }
 ```
 
@@ -198,4 +344,6 @@ interface InterestByRegionOptions {
 
 ### Building
 
-```
+```
+
+```

package/dist/cjs/constants.d.ts

@@ -1,3 +1,3 @@
-import { GoogleTrendsEndpoints } from './types/enums';
-import { GoogleTrendsMapper } from './types';
+import { GoogleTrendsEndpoints } from './types/enums.js';
+import { GoogleTrendsMapper } from './types/index.js';
 export declare const GOOGLE_TRENDS_MAPPER: Record<GoogleTrendsEndpoints, GoogleTrendsMapper>;

package/dist/cjs/constants.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GOOGLE_TRENDS_MAPPER = void 0;
-const enums_1 = require("./types/enums");
+const enums_js_1 = require("./types/enums.js");
 const GOOGLE_TRENDS_BASE_URL = 'trends.google.com';
 exports.GOOGLE_TRENDS_MAPPER = {
-    [enums_1.GoogleTrendsEndpoints.dailyTrends]: {
+    [enums_js_1.GoogleTrendsEndpoints.dailyTrends]: {
         path: '/_/TrendsUi/data/batchexecute',
         method: 'POST',
         host: GOOGLE_TRENDS_BASE_URL,
@@ -13,7 +13,7 @@ exports.GOOGLE_TRENDS_MAPPER = {
             'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
         },
     },
-    [enums_1.GoogleTrendsEndpoints.autocomplete]: {
+    [enums_js_1.GoogleTrendsEndpoints.autocomplete]: {
         path: '/trends/api/autocomplete',
         method: 'GET',
         host: GOOGLE_TRENDS_BASE_URL,
@@ -22,18 +22,32 @@ exports.GOOGLE_TRENDS_MAPPER = {
             accept: 'application/json, text/plain, */*',
         },
     },
-    [enums_1.GoogleTrendsEndpoints.explore]: {
+    [enums_js_1.GoogleTrendsEndpoints.explore]: {
         path: '/trends/api/explore',
         method: 'POST',
         host: GOOGLE_TRENDS_BASE_URL,
         url: `https://${GOOGLE_TRENDS_BASE_URL}/trends/api/explore`,
         headers: {},
     },
-    [enums_1.GoogleTrendsEndpoints.interestByRegion]: {
+    [enums_js_1.GoogleTrendsEndpoints.interestByRegion]: {
         path: '/trends/api/widgetdata/comparedgeo',
         method: 'GET',
         host: GOOGLE_TRENDS_BASE_URL,
         url: `https://${GOOGLE_TRENDS_BASE_URL}/trends/api/widgetdata/comparedgeo`,
         headers: {},
     },
+    [enums_js_1.GoogleTrendsEndpoints.relatedTopics]: {
+        path: '/trends/api/widgetdata/relatedtopics',
+        method: 'GET',
+        host: GOOGLE_TRENDS_BASE_URL,
+        url: `https://${GOOGLE_TRENDS_BASE_URL}/trends/api/widgetdata/relatedtopics`,
+        headers: {},
+    },
+    [enums_js_1.GoogleTrendsEndpoints.relatedQueries]: {
+        path: '/trends/api/widgetdata/relatedqueries',
+        method: 'GET',
+        host: GOOGLE_TRENDS_BASE_URL,
+        url: `https://${GOOGLE_TRENDS_BASE_URL}/trends/api/widgetdata/relatedqueries`,
+        headers: {},
+    },
 };

package/dist/cjs/errors/GoogleTrendsError.d.ts

@@ -1,4 +1,4 @@
-import { GoogleTrendsError } from '../types';
+import { GoogleTrendsError } from '../types/index.js';
 export declare class RateLimitError extends Error implements GoogleTrendsError {
     code: string;
     statusCode: number;

package/dist/cjs/helpers/format.d.ts

@@ -1,2 +1,2 @@
-import { DailyTrendingTopics } from '../types';
+import { DailyTrendingTopics } from '../types/index.js';
 export declare const extractJsonFromResponse: (text: string) => DailyTrendingTopics | null;

package/dist/cjs/helpers/format.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractJsonFromResponse = void 0;
-const GoogleTrendsError_1 = require("../errors/GoogleTrendsError");
+const GoogleTrendsError_js_1 = require("../errors/GoogleTrendsError.js");
 // For future refrence and update: from google trends page rpc call response,
 // 0	"twitter down"	The main trending search term.
 // 1	null	Unused (reserved for future Google Trends data).
@@ -21,29 +21,29 @@ const extractJsonFromResponse = (text) => {
     try {
         const parsedResponse = JSON.parse(cleanedText);
         if (!Array.isArray(parsedResponse) || parsedResponse.length === 0) {
-            throw new GoogleTrendsError_1.ParseError('Invalid response format: empty array');
+            throw new GoogleTrendsError_js_1.ParseError('Invalid response format: empty array');
         }
         const nestedJsonString = parsedResponse[0][2];
         if (!nestedJsonString) {
-            throw new GoogleTrendsError_1.ParseError('Invalid response format: missing nested JSON');
+            throw new GoogleTrendsError_js_1.ParseError('Invalid response format: missing nested JSON');
         }
         const data = JSON.parse(nestedJsonString);
         if (!data || !Array.isArray(data) || data.length < 2) {
-            throw new GoogleTrendsError_1.ParseError('Invalid response format: missing data array');
+            throw new GoogleTrendsError_js_1.ParseError('Invalid response format: missing data array');
         }
         return updateResponseObject(data[1]);
     }
     catch (e) {
-        if (e instanceof GoogleTrendsError_1.ParseError) {
+        if (e instanceof GoogleTrendsError_js_1.ParseError) {
             throw e;
         }
-        throw new GoogleTrendsError_1.ParseError('Failed to parse response');
+        throw new GoogleTrendsError_js_1.ParseError('Failed to parse response');
     }
 };
 exports.extractJsonFromResponse = extractJsonFromResponse;
 const updateResponseObject = (data) => {
     if (!Array.isArray(data)) {
-        throw new GoogleTrendsError_1.ParseError('Invalid data format: expected array');
+        throw new GoogleTrendsError_js_1.ParseError('Invalid data format: expected array');
     }
     const allTrendingStories = [];
     const summary = [];

package/dist/cjs/helpers/googleTrendsAPI.d.ts

@@ -1,4 +1,4 @@
-import { DailyTrendingTopics, DailyTrendingTopicsOptions, RealTimeTrendsOptions, ExploreOptions, ExploreResponse, InterestByRegionOptions, InterestByRegionResponse, GoogleTrendsResponse } from '../types/index';
+import { DailyTrendingTopics, DailyTrendingTopicsOptions, RealTimeTrendsOptions, ExploreOptions, ExploreResponse, InterestByRegionOptions, InterestByRegionResponse, GoogleTrendsResponse, GoogleTrendsError, RelatedTopicsResponse, RelatedQueriesResponse, RelatedData } from '../types/index.js';
 export declare class GoogleTrendsApi {
     /**
      * Get autocomplete suggestions for a keyword
@@ -19,8 +19,15 @@ export declare class GoogleTrendsApi {
      * @returns Promise with trending topics data
      */
     realTimeTrends({ geo, trendingHours }: RealTimeTrendsOptions): Promise<GoogleTrendsResponse<DailyTrendingTopics>>;
-    explore({ keyword, geo, time, category, property, hl, }: ExploreOptions): Promise<ExploreResponse>;
-    interestByRegion({ keyword, startTime, endTime, geo, resolution, hl, timezone, category }: InterestByRegionOptions): Promise<InterestByRegionResponse>;
+    explore({ keyword, geo, time, category, property, hl, }: ExploreOptions): Promise<ExploreResponse | {
+        error: GoogleTrendsError;
+    }>;
+    interestByRegion({ keyword, startTime, endTime, geo, resolution, hl, timezone, category }: InterestByRegionOptions): Promise<InterestByRegionResponse | {
+        error: GoogleTrendsError;
+    }>;
+    relatedTopics({ keyword, geo, time, category, property, hl, }: ExploreOptions): Promise<GoogleTrendsResponse<RelatedTopicsResponse>>;
+    relatedQueries({ keyword, geo, time, category, property, hl, }: ExploreOptions): Promise<GoogleTrendsResponse<RelatedQueriesResponse>>;
+    relatedData({ keyword, geo, time, category, property, hl, }: ExploreOptions): Promise<GoogleTrendsResponse<RelatedData>>;
 }
 declare const _default: GoogleTrendsApi;
 export default _default;