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.

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.

Installation

npm install @shaivpidadi/trends-js

Features

• Get daily trending topics
• Get real-time trending topics
• Get autocomplete suggestions
• Explore trends data
• Get interest by region data
• Get related topics for any keyword
• Get related queries for any keyword
• TypeScript support
• Promise-based API

Usage

Importing

import GoogleTrendsApi from '@shaivpidadi/trends-js';

Daily Trends

Get daily trending topics for a specific region:

const result = await GoogleTrendsApi.dailyTrends({
  geo: 'US', // Default: 'US'
  lang: 'en', // Default: 'en'
});

// Result structure:
// {
//   allTrendingStories: Array<{
//     title: string,
//     traffic: string,
//     image?: {
//       newsUrl: string,
//       source: string,
//       imageUrl: string
//     },
//     articles: Array<{
//       title: string,
//       url: string,
//       source: string,
//       time: string,
//       snippet: string
//     }>,
//     shareUrl: string,
//     startTime: number,      // Unix timestamp
//     endTime?: number        // Unix timestamp (optional)
//   }>,
//   summary: Array<...>
// }

Real-Time Trends

Get real-time trending topics:

const result = await GoogleTrendsApi.realTimeTrends({
  geo: 'US', // Default: 'US'
  trendingHours: 4, // Default: 4
});

// Result structure:
// {
//   allTrendingStories: Array<{
//     title: string,
//     traffic: string,
//     image?: {
//       newsUrl: string,
//       source: string,
//       imageUrl: string
//     },
//     articles: Array<{
//       title: string,
//       url: string,
//       source: string,
//       time: string,
//       snippet: string
//     }>,
//     shareUrl: string,
//     startTime: number,      // Unix timestamp
//     endTime?: number        // Unix timestamp (optional)
//   }>,
//   summary: Array<...>
// }

Autocomplete

Get search suggestions for a keyword:

const suggestions = await GoogleTrendsApi.autocomplete(
  'bitcoin', // Keyword to get suggestions for
  'en-US', // Language (default: 'en-US')
);

Explore

Get widget data for a keyword:

const result = await GoogleTrendsApi.explore({
  keyword: 'bitcoin',
  geo: 'US' // Default: 'US',
  time: 'today 12-m',
  category: 0, // Default: 0
  property: '', // Default: ''
  hl: 'en-US', // Default: 'en-US'
});

// Result structure:
// {
//   widgets: Array<{
//     id: string,
//     request: {...},
//     token: string
//   }>
// }

Note: For all methods below, it is recommended to set enableBackoff: true in the options to automatically handle and bypass Google's rate limiting.

Interest by Region

Get interest data by region:

const result = await GoogleTrendsApi.interestByRegion({
  keyword: 'Stock Market', // Required - 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 - 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
  enableBackoff: true // Optional - defaults to false
});

// Result structure:
// {
//   default: {
//     geoMapData: Array<{
//       geoCode: string,
//       geoName: string,
//       value: number[],
//       formattedValue: string[],
//       maxValueIndex: number,
//       hasData: boolean[],
//       coordinates?: {
//         lat: number,
//         lng: number
//       }
//     }>
//   }
// }

Related Topics

Get related topics for any keyword:

const result = await GoogleTrendsApi.relatedTopics({
  keyword: 'artificial intelligence',
  startTime: new Date('2024-01-01'),
  endTime: new Date(),
  category: 0, // Optional - defaults to 0
  geo: 'US', // Optional - defaults to 'US'
  property: '', // Optional - defaults to ''
  hl: 'en-US', // Optional - defaults to 'en-US'
  enableBackoff: true // Optional - defaults to false
});

// 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:

const result = await GoogleTrendsApi.relatedQueries({
  keyword: 'machine learning',
  geo: 'US',
  startTime: new Date('2024-01-01'),
  endTime: new Date(),
  category: 0,
  hl: 'en-US',
  enableBackoff: true // Optional - defaults to false
});

// Result structure:
// {
//   data: {
//     default: {
//       rankedList: Array<{
//         rankedKeyword: Array<{
//           query: string,
//           value: number,
//           formattedValue: string,
//           hasData: boolean,
//           link: string
//         }>
//       }>
//     }
//   }
// }

API Reference

DailyTrendsOptions

interface DailyTrendsOptions {
  geo?: string;
  lang?: string;
}

RealTimeTrendsOptions

interface RealTimeTrendsOptions {
  geo: string;
  trendingHours?: number;
}

ExploreOptions

interface ExploreOptions {
  keyword: string;
  geo?: string;
  time?: string;
  category?: number;
  property?: string;
  hl?: string;
}

InterestByRegionOptions

interface InterestByRegionOptions {
  keyword: string;
  startTime?: Date;
  endTime?: Date;
  geo?: string;
  resolution?: 'COUNTRY' | 'REGION' | 'CITY' | 'DMA';
  hl?: string;
  timezone?: number;
  category?: number;
  enableBackoff?: boolean;
}

RelatedTopicsOptions

interface RelatedTopicsOptions {
  keyword: string;
  geo?: string;
  startTime?: Date;
  endTime?: Date;
  category?: number;
  property?: string;
  hl?: string;
  enableBackoff?: boolean;
}

RelatedQueriesOptions

interface RelatedQueriesOptions {
  keyword: string;
  geo?: string;
  startTime?: Date;
  endTime?: Date;
  category?: number;
  property?: string;
  hl?: string;
  enableBackoff?: boolean;
}

Development

Building

npm run build

Testing

npm test

License

MIT