search

pat310 / google-trends-api

An API layer on top of google trends
https://www.npmjs.com/package/google-trends-api
MIT License
874 stars 174 forks source link
google-trends

readme

google-trends-api

NPM

npm version Build status Coverage Status Code Climate Dependency Status Known Vulnerabilities

v3 to v4

Big changes! The old google-trends endpoints are deprecated and are heavily throttled so this library has changed significantly. You can choose to download the old version via npm install google-trends-api@3.0.2 but it is discouraged.

Introduction

This library provides an API layer to google trends data. Due to CORS restrictions, this library is intended to be used in node. It is constantly being expanded and improved so please check back frequently. Also, please feel free to contribute to make the library even better! :dog:

Syntax

const googleTrends = require('google-trends-api');

googleTrends.apiMethod(optionsObject, [callback])

Parameters

optionsObject An object with the following options keys:

callback Optional callback function where the first parameter is an error and the second parameter is the result. If no callback is provided, then a promise is returned.

Table of contents

Installation

To install this package, clone this git repository and include it in your project's node_modules or simply:

npm install google-trends-api

Require google-trends-api in your script and give it a variable name:

const googleTrends = require('google-trends-api');

You will now be able to access methods on googleTrends. See the API Methods section below to see the methods available and their syntax.

back to top

API

Promises

By default, all the API's return a promise for the results. Example:

googleTrends.interestOverTime({keyword: 'Women\'s march'})
.then(function(results){
  console.log('These results are awesome', results);
})
.catch(function(err){
  console.error('Oh no there was an error', err);
});

Callbacks

All API methods can alternatively take a callback function as the second parameter. For example:

googleTrends.interestOverTime({keyword: 'Women\'s march'}, function(err, results){
  if(err) console.error('there was an error!', err);
  else console.log('my sweet sweet results', results);
})

Proxy Server

A proxy server can be used by specifying an http agent as part of the query. This example uses https-proxy-agent

const HttpsProxyAgent = require('https-proxy-agent');

let proxyAgent =  new HttpsProxyAgent('http://proxy-host:8888/');

let query = {
    keyword: 'Women\'s march',
    agent: proxyAgent
};

googleTrends.interestOverTime(query)
.then(function(results){
  console.log('These proxied results are incredible', results);
})
.catch(function(err){
  console.error('Oh no there was an error, double check your proxy settings', err);
});

Multiple Keywords

Compare multiple keywords with any of the api methods by supplying an array instead of a single string

googleTrends.interestOverTime({keyword: ['Women\'s march', 'Trump Inauguration']})
.then(function(results){
  console.log('These results are awesome', results);
})
.catch(function(err){
  console.error('Oh no there was an error', err);
});

Examples

There are examples available for each API method in the root directory of the module. Note: Each example in examples.js needs to be uncommented.

API Methods

The following API methods are available:

back to top

autoComplete

Syntax

googleTrends.autoComplete({keyword: string}, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

Example

Returning the auto-complete results for 'Back to School'

Input
googleTrends.autoComplete({keyword: 'Back to School'})
.then(function(results) {
  console.log(results);
})
.catch(function(err) {
  console.error(err);
})
Output
{"default":{"topics":[{"mid":"/m/0414j6","title":"Back to School","type":"1986 film"},{"mid":"/m/068pw8","title":"Back to school","type":"Topic"},{"mid":"/m/04vwgn","title":"Fight Back to School","type":"1991 film"},{"mid":"/m/05357_","title":"Tax holiday","type":"Holiday"},{"mid":"/m/02pb6kt","title":"Fight Back to School II","type":"1992 film"}]}}

Note: You can then use these results in the other API methods. For example, if you wanted interestOverTime for 'Back to School' where the type is 'Topic', you would then use: googleTrends.interestOverTime({keyword: '/m/068pw8'})

back to top

dailyTrends

Daily Search Trends highlights searches that jumped significantly in traffic among all searches over the past 24 hours and updates hourly. These search trends show the specific queries that were searched, and the absolute number of searches made. 20 daily trending search results are returned

Syntax

googleTrends.dailyTrends({ geo: string }, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

Example

Returning real time trending stories for the United States region.

Input
googleTrends.dailyTrends({
  trendDate: new Date('2019-01-10'),
  geo: 'US',
}, function(err, results) {
  if (err) {
    console.log(err);
  }else{
    console.log(results);
  }
});
Output
{
  default : [Object]{
    trendingSearchesDays : [Array]
      [0] : [Object]{
        date : String
        formattedDate: String
        trendingSearches : [Array]{
          [0] : [Object] //First trending result
        }
      [1] : [Object]{
        date : String
        formattedDate: String
        trendingSearches : [Array]{
          [0] : [Object] //first trending result
          ...
          [19] : [Object] //20th trending result
        }
      }
    }
    endDateForNextRequest : String,
    rssFeedPageUrl : String,
  }
}

back to top

interestOverTime

Search interest relative to the highest point on the chart for the given region and time (100 is the peak popularity for the term)

Syntax

googleTrends.interestOverTime({keyword: string, startTime: Date, endTime: Date, geo: string}, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

The resolution of the search changes automatically depending on the search duration. The wider the duration window, the worse the resolution (for example, a search duration with a startTime and endTime that ends years apart will return a resolution in months, while a search duration with a startTime and endTime a few hours apart will return a resolution in minutes).

Example 1

Returning the search interest over time for 'Valentines Day' (by default from 2004-01-01 to today)

Input
googleTrends.interestOverTime({keyword: 'Valentines Day'})
.then(function(results){
  console.log(results);
})
.catch(function(err){
  console.error(err);
});
Output
{"default":{"timelineData":[{"time":"1072915200","formattedTime":"Jan 2004","formattedAxisTime":"Jan 1, 2004","value":[26],"formattedValue":["26"]},{"time":"1075593600","formattedTime":"Feb 2004","formattedAxisTime":"Feb 1, 2004","value":[74],"formattedValue":["74"]},
...
{"time":"1483228800","formattedTime":"Jan 2017","formattedAxisTime":"Jan 1, 2017","value":[18],"formattedValue":["18"]},{"time":"1485907200","formattedTime":"Feb 2017","formattedAxisTime":"Feb 1, 2017","value":[72],"formattedValue":["72"]}],"averages":[]}}
Example 2

Returning the search interest over time for 'Valentines Day' from the past four hours. Note that the resolution is by minute since our query duration is shorter.

Input
googleTrends.interestOverTime({keyword: 'Valentines Day', startTime: new Date(Date.now() - (4 * 60 * 60 * 1000))}, function(err, results) {
  if (err) console.log('oh no error!', err);
  else console.log(results);
});
Output
{"default":{"timelineData":[{"time":"1487026800","formattedTime":"Feb 13, 2017 at 6:00 PM","formattedAxisTime":"6:00 PM","value":[49],"formattedValue":["49"]},{"time":"1487026860","formattedTime":"Feb 13, 2017 at 6:01 PM","formattedAxisTime":"6:01 PM","value":[50],"formattedValue":["50"]},
...
{"time":"1487040180","formattedTime":"Feb 13, 2017 at 9:43 PM","formattedAxisTime":"9:43 PM","value":[88],"formattedValue":["88"]},{"time":"1487040240","formattedTime":"Feb 13, 2017 at 9:44 PM","formattedAxisTime":"9:44 PM","value":[81],"formattedValue":["81"]}],"averages":[]}}

back to top

interestByRegion

See in which location your term was most popular during the specified time frame. Values are calculated on a scale from 0 to 100, where 100 is the location with the most popularity as a fraction of total searches in that location.

Syntax

googleTrends.interestByRegion({keyword: string, startTime: Date, endTime: Date, geo: string, resolution: string}, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

Example 1

Returning the search interest by cities around the world for 'Donald Trump' from February 01, 2017 to February 06, 2017.

Input
googleTrends.interestByRegion({keyword: 'Donald Trump', startTime: new Date('2017-02-01'), endTime: new Date('2017-02-06'), resolution: 'CITY'})
.then((res) => {
  console.log(res);
})
.catch((err) => {
  console.log(err);
})
Output
{"default":{"geoMapData":[{"coordinates":{"lat":18.594395,"lng":-72.3074326},"geoName":"Port-au-Prince","value":[100],"formattedValue":["100"],"maxValueIndex":0},{"coordinates":{"lat":43.467517,"lng":-79.6876659},"geoName":"Oakville","value":[90],"formattedValue":["90"],"maxValueIndex":0},
...
{"coordinates":{"lat":40.9312099,"lng":-73.8987469},"geoName":"Yonkers","value":[69],"formattedValue":["69"],"maxValueIndex":0}]}}
Example 2

Returning the search interest by cities in California for 'Donald Trump' from February 01, 2017 to February 06, 2017.

Input
googleTrends.interestByRegion({keyword: 'Donald Trump', startTime: new Date('2017-02-01'), endTime: new Date('2017-02-06'), geo: 'US-CA'})
.then((res) => {
  console.log(res);
})
.catch((err) => {
  console.log(err);
})
Output
{"default":{"geoMapData":[{"geoCode":"807","geoName":"San Francisco-Oakland-San Jose CA","value":[100],"formattedValue":["100"],"maxValueIndex":0},{"geoCode":"828","geoName":"Monterey-Salinas CA","value":[100],"formattedValue":["100"],"maxValueIndex":0},
...
{"geoCode":"811","geoName":"Reno NV","value":[12],"formattedValue":["12"],"maxValueIndex":0},{"geoCode":"813","geoName":"Medford-Klamath Falls OR","value":[4],"formattedValue":["4"],"maxValueIndex":0}]}}

back to top

realtimeTrends

Realtime Search Trends highlight stories that are trending across Google surfaces within the last 24 hours, and are updated in realtime. 13 real time trending stories are returned

Syntax

googleTrends.realTimeTrends({ geo: string }, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

Example

Returning real time trending stories for the United States region.

Input
googleTrends.realTimeTrends({
    geo: 'US',
    category: 'all',
}, function(err, results) {
    if (err) {
       console.log(err);
    } else {
      console.log(results);
    } 
});
Output
{
    featuredStoryIds : [Array], // Empty
    trendingStoryIds : [Array], // 300 trending story IDs
  storySummaries : [Object]
    {
      featuredStories : [Array], // Empty
    trendingStories : [Array], // 13 top trending stories
    },
    date : "Date-String",
  hideAllImages : Boolean,
}

back to top

relatedQueries

Users searching for your term also searched for these queries.

Syntax

googleTrends.relatedQueries({keyword: string, startTime: Date, endTime: Date, geo: string}, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

Example

Returning top related queries for 'Westminster Dog show' with default startTime, endTime, and geo categories

Input
googleTrends.relatedQueries({keyword: 'Westminster Dog Show'})
.then((res) => {
  console.log(res);
})
.catch((err) => {
  console.log(err);
})
Output
{"default":{"rankedList":[{"rankedKeyword":[{"query":"dog show 2016","value":100,"formattedValue":"100","link":"/"},{"query":"2016 westminster dog show","value":95,"formattedValue":"95","link":"/"},
...
{"query":"dogs","value":20,"formattedValue":"20","link":"/"}]},{"rankedKeyword":[{"query":"dog show 2016","value":836500,"formattedValue":"Breakout","link":"/"},{"query":"2016 westminster dog show","value":811550,"formattedValue":"Breakout","link":"/"},
...
{"query":"who won the westminster dog show","value":59000,"formattedValue":"Breakout","link":"/"}]}]}}

back to top

relatedTopics

Users searching for your term also searched for these topics

Syntax

googleTrends.relatedTopics({keyword: string, startTime: Date, endTime: Date, geo: string}, cbFunc)

Requires an object as the first parameter with the following keys:

Optional callback function as the second parameter (otherwise returns a promise)

Example

Returning top related topics for 'Chipotle' from January 1st, 2015 to February 10th, 2017.

Input
googleTrends.relatedTopics({keyword: 'Chipotle', startTime: new Date('2015-01-01'), endTime: new Date('2017-02-10')})
.then((res) => {
  console.log(res);
})
.catch((err) => {
  console.log(err);
})
Output
{"default":{"rankedList":[{"rankedKeyword":[{"topic":{"mid":"/m/01b566","title":"Chipotle Mexican Grill","type":"Restaurant company"},"value":100,"formattedValue":"100","link":"/"},{"topic":{"mid":"/m/02f217","title":"Chipotle","type":"Jalape\u00f1o"},"value":5,"formattedValue":"5","link":"/"},
...
{"topic":{"mid":"/m/01xg7s","title":"Chorizo","type":"Topic"},"value":0,"formattedValue":"0","link":"/"}]},{"rankedKeyword":[{"topic":{"mid":"/m/09_yl","title":"E. coli","type":"Bacteria"},"value":40700,"formattedValue":"Breakout","link":"/"},
...
{"topic":{"mid":"/m/0dqc4","title":"Caridea","type":"Animal"},"value":40,"formattedValue":"+40%","link":"/"}]}]}}

back to top

Geo help

Unfortunately support is not offered for zip codes at this time. The user must enter a country code, region (or state) code, and/or DMA (Designated Market Area) code.

Big Thanks

back to top