# @alkalisummer/google-trends-js 中文文档

规范地址：https://npmcn.com/package/%40alkalisummer/google-trends-js/

版本：0\.3\.7
npm 元数据更新时间：2025-09-22T04:43:21.129Z
中文译文更新时间：2026-11-06T00:59:48.394Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alkalisummer/google-trends-js
原文对照：https://npmcn.com/package/%40alkalisummer/google-trends-js/?lang=original
项目主页：https://github.com/alkalisummer/google-trends-js#readme
源码仓库：https://github.com/alkalisummer/google-trends-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：47.1 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-06-05T06:35:41.545Z
- 最新版本发布：2025-09-22T04:43:20.936Z
- 近 30 天下载量：7591（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 0 个）

## 中文简介

用于节点.js的谷歌趋势 API

## 安装

```sh
npm install @alkalisummer/google-trends-js
```

也可以使用：`pnpm add @alkalisummer/google-trends-js`、`yarn add @alkalisummer/google-trends-js`、`bun add @alkalisummer/google-trends-js`

## README

# @ 碱夏/谷歌-趋势-js

这是一个TypeScript库,已经更新,以纳入谷歌趋势API端点的最新修改. 这个软件包为在程序上访问Google趋势数据提供了简单而安全的方式.

这个API是基于有一些添加和修改的功能的@shaivpidadi/trends-js来开发的.

现作如下修改和补充:

-   Daily Trends : 添加了相关的关键词和活化时间.
-   趋势文章:检索与趋势关键词相关的文章信息.
-   利息超越时间:为趋势关键词检索时间序列利息数据.

## 安装

```bash
npm install @alkalisummer/google-trends-js
```

## 特征

-   获得日常趋势话题
-   获取实时趋势话题
-   获取有关趋势话题的文章
-   获取自动补全建议
-   探索趋势数据
-   按区域数据获取兴趣
-   随时间( 时间线) 获取关键字的兴趣
-   类型脚本支持
-   基于承诺的API

## 使用量

### 导入

```typescript
import GoogleTrendsApi from '@alkalisummer/google-trends-js';
```

### 每日趋势

获取特定区域的日常趋势话题:

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

// Result structure:
// {
//   data?: Array<{
//     keyword: string;
//     traffic: number;
//     trafficGrowthRate: number;
//     activeTime: Date;
//     relatedKeywords: string[];
//     articleKeys: ArticleKey[];
//   }>,
//   error?: GoogleTrendsError
// }
//
```

### 趋势文章

获取特定文章密钥的趋势文章

您可以在每日Trends方法返回的回复中从文章Keys字段中取回文章Keys.

```typescript
const result = await GoogleTrendsApi.trendingArticles({
  articleKeys: [[1, hl, geo]], // Array of article keys
  articleCount: 5, // Number of articles to get
});

// Result structure:
// {
//   data?: Array<{
//     title: string;
//     link: string;
//     mediaCompany: string;
//     pressDate: number[];
//     image: string;
//   }>,
//   error?: GoogleTrendsError
// }
```

### 利息随时间演变

获取特定关键字时间数据的兴趣:

```typescript
const result = await GoogleTrendsApi.interestOverTime({
  keyword: 'bitcoin', // or an array of keywords
  geo: 'US', //Default: 'US'
  period: 'now 7-d', // Default: 'now 1-d'
  hl: 'en-US', // Default: 'en-US'
});

// Result structure:
// {
//   data?: {
//     keyword: string | string[];
//     dates: Date[];
//     values: number[][]; // one series per keyword (for single keyword: a single inner array)
//   },
//   error?: GoogleTrendsError
// }
```

多个关键字示例 :

```typescript
const result = await GoogleTrendsApi.interestOverTime({
  keyword: ['bitcoin', 'ethereum'],
  geo: 'US',
  period: 'today 12-m',
});

if (result.data) {
  // result.data.values is number[][] where
  // values[i] corresponds to the i-th sorted date in result.data.dates
}
```

### 实时趋势

获取实时趋势话题 :

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

// Result structure (wrapped):
// {
//   data?: Array<{
//     keyword: string;
//     traffic: number;
//     trafficGrowthRate: number;
//     activeTime: Date;
//     relatedKeywords: string[];
//     articleKeys: ArticleKey[];
//   }>,
//   error?: GoogleTrendsError
// }
```

### 自动完成

获取关键字搜索建议 :

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

if (suggestions.data) {
  // suggestions.data is string[]
}
```

### 探索

获取关键字的部件数据 :

```typescript
const result = await GoogleTrendsApi.explore({
  keyword: 'bitcoin',
  geo: 'US', // Default: 'US'
  time: '2025-06-30 2025-07-01', // Default: 'now 1-d'
  category: 0, // Default: 0
  property: '', // Default: ''
  hl: 'en-US', // Default: 'en-US'
});

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

### 按区域分列的利息

按区域获取兴趣数据 :

```typescript
const result = await GoogleTrendsApi.interestByRegion({
  keyword: 'Stock Market', // Required - string or string[]
  startTime: new Date('2024-01-01'), // Optional - defaults: yesterday
  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
//       }
//     }>
//   }
// }
```

有多个关键词和区域的示例:

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

## API 参考

### DailyTrendingTops 选项

```typescript
interface DailyTrendingTopicsOptions {
  geo?: string; // Default: 'US'
  hl?: string; // Default: 'en'
}
```

### 实时趋势选项

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

### 探索选项

```typescript
interface ExploreOptions {
  keyword: string | string[];
  geo?: string; // Default: 'US'
  time?: string; // Default: 'now 1-d'
  category?: number; // Default: 0
  property?: string; // Default: ''
  hl?: string; // Default: 'en-US'
}
```

### 利息账户选项

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

### 趋势条款选项

```typescript
interface TrendingArticlesOptions {
  articleKeys: ArticleKey[]; // Required - array of article keys
  articleCount: number; // Required - number of articles to get
}

type ArticleKey = [number, string, string]; // [index, lang, geo]
```

### 超时利息备选方案

```typescript
interface InterestOverTimeOptions {
  keyword: string | string[]; // Required - search term(s)
  geo?: string; // Optional - geocode (default: 'US')
  period?: 'now 1-H' | 'now 4-H' | 'now 1-d' | 'now 7-d' | 'now 1-m' | 'today 3-m' | 'today 12-m' | 'today 5-y'; // Optional - time period (default: 'now 1-d')
  hl?: string; // Optional - language (default: 'en-US')
}
```

## 发展

### 大楼

## 常见问题

### @alkalisummer/google-trends-js 是什么？

用于节点\.js的谷歌趋势 API

### 如何安装 @alkalisummer/google-trends-js？

在项目目录运行 npm install @alkalisummer/google-trends-js，或使用 pnpm add / yarn add / bun add。

### @alkalisummer/google-trends-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alkalisummer/google-trends-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @alkalisummer/google-trends-js 可以商用吗？

@alkalisummer/google-trends-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @alkalisummer/google-trends-js 的下载量有多少？

根据 npm 官方下载统计，@alkalisummer/google-trends-js 在 2026/10/06 – 2026/11/04 这 30 天内被下载 7,591 次，日均约 253 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alkalisummer/google-trends-js 还在维护吗？

最新版本 0\.3\.7 发布于 2025/09/22（1\.1 年前）；至今共发布 30 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/06/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。