google-trends-api
Advanced tools
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.
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:
const googleTrends = require('google-trends-api');
googleTrends.apiMethod(optionsObject, [callback])
optionsObject An object with the following options keys:
string or array if you wish to compare search terms requirednew Date() object). If startTime is not provided, a date of January 1, 2004 is assumed (this is the oldest available google trends data)new Date() object). If endTime is not provided, the current date is selected.string or array if you wish to provide separate locations for each keyword).string defaults to english)number defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))number defaults to all categories)string ['images', 'news', 'youtube' or 'froogle'] where froogle is Google Shopping results)string ['COUNTRY', 'REGION', 'CITY', 'DMA']). resolution is specific to the interestByRegion method.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.
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.
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);
});
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);
})
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);
});
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);
});
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.
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.
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.You can search retroactively for up to 15 days in the past.
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".
realTimeTrends: Realtime Search Trends highlight stories that are trending across Google surfaces within the last 24 hours, and are updated in realtime. These stories are a collection of Knowledge Graph topics, Search interest, trending YouTube videos, and/or Google News articles detected by Google's algorithms. 13 real time trending stories are returned.
relatedQueries: Users searching for your term also searched for these queries. The following metrics are returned:
relatedTopics: Users searching for your term also searched for these topics. The following metrics are returned:
googleTrends.autoComplete({keyword: string}, cbFunc)
Requires an object as the first parameter with the following keys:
keyword - required - type string - the search term of interesthl - optional - type string - preferred language code for results (defaults to english)Optional callback function as the second parameter (otherwise returns a promise)
Returning the auto-complete results for 'Back to School'
googleTrends.autoComplete({keyword: 'Back to School'})
.then(function(results) {
console.log(results);
})
.catch(function(err) {
console.error(err);
})
{"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'})
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
googleTrends.dailyTrends({ geo: string }, cbFunc)
Requires an object as the first parameter with the following keys:
geo - required - type string - geocode for a country. For example, geo: 'US' will target United States or geo: 'FR' will target France.hl - optional - type string - preferred language code for results (defaults to english).timezone - optional - type number - preferred timezone (defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))trendDate - optional - type Date object - the date you are interesting in retrieving trends information for (defaults to the current date). Note that querying for a date more than 15 days in the past will result in an error.Optional callback function as the second parameter (otherwise returns a promise)
Returning real time trending stories for the United States region.
googleTrends.dailyTrends({
trendDate: new Date('2019-01-10'),
geo: 'US',
}, function(err, results) {
if (err) {
console.log(err);
}else{
console.log(results);
}
});
{
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,
}
}
Search interest relative to the highest point on the chart for the given region and time (100 is the peak popularity for the term)
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 intereststartTime - 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 or array - geocode(s) 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. Passing geo: ['US-CA, US-VA'], keyword: ['wine', 'peanuts'] will search for wine in California and peanuts in Virginia.hl - optional - type string - preferred language code for results (defaults to english)timezone - optional - type number - preferred timezone (defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))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 listgranularTimeResolution - 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).
Returning the search interest over time for 'Valentines Day' (by default from 2004-01-01 to today)
googleTrends.interestOverTime({keyword: 'Valentines Day'})
.then(function(results){
console.log(results);
})
.catch(function(err){
console.error(err);
});
{"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":[]}}
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.
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);
});
{"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":[]}}
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.
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 intereststartTime - 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 or array - geocode(s) 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. Passing geo: ['US-CA, US-VA'], keyword: ['wine', 'peanuts'] will search for wine in California and peanuts in Virginia.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)
for results (defaults to english)timezone - optional - type number - preferred timezone (defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))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 listOptional callback function as the second parameter (otherwise returns a promise)
Returning the search interest by cities around the world for 'Donald Trump' from February 01, 2017 to February 06, 2017.
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);
})
{"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}]}}
Returning the search interest by cities in California for 'Donald Trump' from February 01, 2017 to February 06, 2017.
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);
})
{"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}]}}
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
googleTrends.realTimeTrends({ geo: string }, cbFunc)
Requires an object as the first parameter with the following keys:
geo - required - type string - geocode for a country. For example, geo: 'US' will target United States or geo: 'FR' will target France.hl - optional - type string - preferred language code for results (defaults to english)
for results (defaults to english)timezone - optional - type number - preferred timezone (defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))category - optional - type string - a string corresponding to a particular category to query within (defaults to all categories):
All : 'all'
Entertainment: 'e'
Business : 'b'
Science/Tech : 't'
Health : 'm'
Sports : 's'
Top Stories : 'h'Optional callback function as the second parameter (otherwise returns a promise)
Returning real time trending stories for the United States region.
googleTrends.realTimeTrends({
geo: 'US',
category: 'all',
}, function(err, results) {
if (err) {
console.log(err);
} else {
console.log(results);
}
});
{
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,
}
Users searching for your term also searched for these queries.
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 intereststartTime - 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 or array - geocode(s) 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. Passing geo: ['US-CA, US-VA'], keyword: ['wine', 'peanuts'] will search for wine in California and peanuts in Virginia.hl - optional - type string - preferred language code for results (defaults to english)
for results (defaults to english)timezone - optional - type number - preferred timezone (defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))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 listOptional callback function as the second parameter (otherwise returns a promise)
Returning top related queries for 'Westminster Dog show' with default startTime, endTime, and geo categories
googleTrends.relatedQueries({keyword: 'Westminster Dog Show'})
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
})
{"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":"/"}]}]}}
Users searching for your term also searched for these topics
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 intereststartTime - 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 or array - geocode(s) 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. Passing geo: ['US-CA, US-VA'], keyword: ['wine', 'peanuts'] will search for wine in California and peanuts in Virginia.hl - optional - type string - preferred language code for results (defaults to english)
for results (defaults to english)timezone - optional - type number - preferred timezone (defaults to the time zone difference, in minutes, from UTC to current locale (host system settings))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 listOptional callback function as the second parameter (otherwise returns a promise)
Returning top related topics for 'Chipotle' from January 1st, 2015 to February 10th, 2017.
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);
})
{"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":"/"}]}]}}
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.
FAQs
an API layer on top of google trends
The npm package google-trends-api receives a total of 4,073 weekly downloads. As such, google-trends-api popularity was classified as popular.
We found that google-trends-api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.