google-trends-api

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 [email protected] 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:

• keyword Target search term(s) string or array if you wish to compare search terms required
• startTime Start of time period of interest (new Date() object). If startTime is not provided, a date of January 1, 2004 is assumed (this is the oldest available google trends data)
• endTime End of time period of interest (new Date() object). If endTime is not provided, the current date is selected.
• geo Location of interest (string).
• hl Preferred language (string defaults to english)
• category Category to search within (number defaults to all categories)
• resolution Granularity of the geo search (enumerated string ['COUNTRY', 'REGION', 'CITY', 'DMA']). resolution is specific to the interestByRegion method.
• granularTimeResolution Boolean that dictates if the results should be given in a finer time resolution (if startTime and endTime is less than one day, this should be set to true)

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
• API
  • Promises
  • Callbacks
  • Examples
  • API Methods
    • autoComplete
    • interestOverTime
    • interestByRegion
    • relatedQueries
    • relatedTopics
• Geo help
• List of categories
• Big Thanks

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

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:

• autoComplete: Returns the results from the "Add a search term" input box in the google trends UI. These results (Topics) can then be used in the other API methods. Note: Search terms and Topics are measured differently, so relatedTopics will not work with comparisons that contain both Search terms and Topics.

• interestOverTime: Numbers represent search interest relative to the highest point on the chart for the given region and time. A value of 100 is the peak popularity for the term. A value of 50 means that the term is half as popular. Likewise a score of 0 means the term was less than 1% as popular as the peak. If you use multiple keywords for a comparison, the return data will also contain an average result for each keyword.

• 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, a value of 50 indicates a location which is half as popular, and a value of 0 indicates a location where the term was less than 1% as popular as the peak. Note: A higher value means a higher proportion of all queries, not a higher absolute query count. So a tiny country where 80% of the queries are for "bananas" will get twice the score of a giant country where only 40% of the queries are for "bananas".

• relatedQueries: Users searching for your term also searched for these queries. The following metrics are returned:

  • Top - The most popular search queries. Scoring is on a relative scale where a value of 100 is the most commonly searched query, 50 is a query searched half as often, and a value of 0 is a query searched for less than 1% as often as the most popular query.
  • Rising - Queries with the biggest increase in search frequency since the last time period. Results marked "Breakout" had a tremendous increase, probably because these queries are new and had few (if any) prior searches.

• relatedTopics: Users searching for your term also searched for these topics. The following metrics are returned:

  • Top - The most popular topics. Scoring is on a relative scale where a value of 100 is the most commonly searched topic, a value of 50 is a topic searched half as often, and a value of 0 is a topic searched for less than 1% as often as the most popular topic.
  • Rising - Related topics with the biggest increase in search frequency since the last time period. Results marked "Breakout" had a tremendous increase, probably because these topics are new and had few (if any) prior searches.

back to top

autoComplete

• Results from the "add a search term" input box in the google trends UI*

Syntax

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

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

• keyword - required - type string - the search term of interest
• hl - optional - type string - preferred language code for results (defaults to english)

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

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:

• keyword - required - type string or array - the search term(s) of interest
• startTime - optional - type Date object - the start of the time range of interest (defaults to new Date('2004-01-01') if not supplied)
• endTime - optional - type Date object - the end of the time range of interest (defaults to new Date(Date.now()) if not supplied)
• geo - optional - type string - geocode for a country, region, or DMA depending on the granularity required (defaults to worldwide). For example, geo: 'US-CA-800' will target the Bakersfield, California, United States or geo: 'US' will just target the US.
• hl - optional - type string - preferred language code for results (defaults to english)
• category - optional - type number - a number corresponding to a particular category to query within (defaults to all categories), see the category wiki for a complete list
• granularTimeResolution - optional - type boolean - if true, will try to return results to a finer time resolution (only relevant for startTime and endTime less than one week)

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:

• keyword - required - type string or array - the search term(s) of interest
• startTime - optional - type Date object - the start of the time range of interest (defaults to new Date('2004-01-01') if not supplied)
• endTime - optional - type Date object - the end of the time range of interest (defaults to new Date(Date.now()) if not supplied)
• geo - optional - type string - geocode for a country, region, or DMA depending on the granularity required (defaults to worldwide). For example, geo: 'US-CA-800' will target the Bakersfield, California, United States or geo: 'US' will just target the US.
• resolution - optional - type enumerated string either COUNTRY, REGION, CITY or DMA. Resolution is selected by default otherwise. Trying to select a resolution larger than a specified geo will return an error.
• hl - optional - type string - preferred language code for results (defaults to english)
• category - optional - type number - a number corresponding to a particular category to query within (defaults to all categories), see the category wiki for a complete list

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

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:

• keyword - required - type string or array - the search term(s) of interest
• startTime - optional - type Date object - the start of the time range of interest (defaults to new Date('2004-01-01') if not supplied)
• endTime - optional - type Date object - the end of the time range of interest (defaults to new Date(Date.now()) if not supplied)
• geo - optional - type string - geocode for a country, region, or DMA depending on the granularity required (defaults to worldwide). For example, geo: 'US-CA-800' will target the Bakersfield, California, United States or geo: 'US' will just target the US.
• hl - optional - type string - preferred language code for results (defaults to english)
• category - optional - type number - a number corresponding to a particular category to query within (defaults to all categories), see the category wiki for a complete list

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:

• keyword - required - type string or array - the search term(s) of interest
• startTime - optional - type Date object - the start of the time range of interest (defaults to new Date('2004-01-01') if not supplied)
• endTime - optional - type Date object - the end of the time range of interest (defaults to new Date(Date.now()) if not supplied)
• geo - optional - type string - geocode for a country, region, or DMA depending on the granularity required (defaults to worldwide). For example, geo: 'US-CA-800' will target the Bakersfield, California, United States or geo: 'US' will just target the US.
• hl - optional - type string - preferred language code for results (defaults to english)
• category - optional - type number - a number corresponding to a particular category to query within (defaults to all categories), see the category wiki for a complete list

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.

• A list of country codes can be found here: country code list
• A list of DMAs can be found here: DMA list
• A list of available languages can be found here: language codes

Big Thanks

• To dreyco676 for the heads up on the deprecated routes and new end points. Checkout the python google trends

back to top