@iyromanov/trends-js

v1.1.0

Published

a month ago

Google Trends API for Node.js (Fork of @shaivpidadi/trends-js)

0High
0Medium
0Low

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.

About This Fork

This is a fork of @shaivpidadi/trends-js maintained by @iyromanov.

Showcase

EliteTimesNews.com — Built with the original `@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 @iyromanov/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
Get combined related data (topics + queries)
TypeScript support
Promise-based API

Usage

Importing

import GoogleTrendsApi from '@iyromanov/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<...>,
//   summary: string[]
// }

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<...>,
//   summary: string[]
// }

Autocomplete

Get search suggestions for a keyword:

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

// Returns: string[]

Explore

Get widget data for a keyword:

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'
});

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

Interest by Region

Get interest data by region:

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
});

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

Example with multiple keywords and regions:

const result = await GoogleTrendsApi.interestByRegion({
  keyword: ['wine', 'peanuts'],
  geo: ['US-CA', 'US-VA'],
  startTime: new Date('2024-01-01'),
  endTime: new Date(),
  resolution: 'CITY',
});

Related Queries

Get related queries for any keyword:

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:

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

DailyTrendsOptions

interface DailyTrendsOptions {
  geo?: string; // Default: 'US'
  lang?: string; // Default: 'en'
}

RealTimeTrendsOptions

interface RealTimeTrendsOptions {
  geo: string;
  trendingHours?: number; // Default: 4
}

ExploreOptions

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'
}

InterestByRegionOptions

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)
  resolution?: 'COUNTRY' | 'REGION' | 'CITY' | 'DMA'; // Optional
  hl?: string; // Optional - language code
  timezone?: number; // Optional - timezone offset
  category?: number; // Optional - category number
}

RelatedTopicsResponse

interface RelatedTopicsResponse {
  default: {
    rankedList: Array<{
      rankedKeyword: Array<{
        topic: {
          mid: string;
          title: string;
          type: string;
        };
        value: number;
        formattedValue: string;
        hasData: boolean;
        link: string;
      }>;
    }>;
  };
}

RelatedQueriesResponse

interface RelatedQueriesResponse {
  default: {
    rankedList: Array<{
      rankedKeyword: Array<{
        query: string;
        value: number;
        formattedValue: string;
        hasData: boolean;
        link: string;
      }>;
    }>;
  };
}

RelatedData

interface RelatedData {
  topics: Array<RelatedTopic>;
  queries: Array<RelatedQuery>;
}

Development

Building

npm run build

Testing

npm test

Publishing

This package uses automated versioning and publishing through GitHub Actions.

How to Release a New Version

Go to the Actions tab in your GitHub repository
Select the Release workflow
Click Run workflow
Choose the version bump type:
- patch: Bug fixes (1.0.0 → 1.0.1)
- minor: New features (1.0.0 → 1.1.0)
- major: Breaking changes (1.0.0 → 2.0.0)
The workflow will:
- Run tests
- Bump the version in package.json
- Create a git tag
- Push the changes and tag
The Publish Package workflow will automatically trigger on the new tag and publish to npm

Prerequisites for Publishing

Before you can publish, you need to:

Create an npm account at https://www.npmjs.com/signup
Generate an npm access token:
- Log in to npm
- Go to your profile → Access Tokens
- Generate a new token with "Automation" type
Add the token to GitHub Secrets:
- Go to your repository Settings → Secrets and variables → Actions
- Create a new secret named NPM_TOKEN
- Paste your npm token as the value
Configure npm scope (one-time setup):
- Make sure you have access to publish under the @iyromanov scope on npm

Manual Publishing (Alternative)

You can also publish manually:

npm version patch  # or minor, or major
git push origin main --tags
npm publish --access public