#google-trends-api
##Introduction This library provides an API layer to google trends data. It is constantly being expanded and improved so please check back frequently. Also, please feel free to contribute to make the library even better! 🐶
Simple to use:
var googleTrends = require('google-trends-api');
var options = {
geo: 'country name',
date: 'yyyymm',
keywords: ['some', 'list', 'of', 'keywords'],
category: 'some category'
}
googleTrends.apiMethod(options)
.then(function(results){
console.log("Here are your google trend results!", results);
})
.catch(function(err){
console.log("there was an error :(", err);
});##Table of contens
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:
var 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.topRelated({keywords: 'dog house'})
.then(function(results){
console.log("Here are the results!", results);
})
.catch(function(err){
console.error('We have an error!', err);
})Would console.log:
Here are the results! [ { 'dog house grill': 'Breakout',
'best house dog': '+170%',
'the dog house': '+140%',
'the house': '+130%',
'house of dog': '+100%',
'large dog house': '+90%',
'house train dog': '+80%',
'small dog house': '+80%',
'animal house': '+70%',
'big dog house': '+70%' } ];All API methods can also take a callback function as the last input parameter. For example:
googleTrends.topRelated({keywords: 'dog dreams'}, function(err, results){
if(err) console.error('there was an error!', err);
else console.log('results', results);
})Would console.log:
results [ { 'do dog dreams': 'Breakout',
'dog dream meaning': 'Breakout',
'dog dreams meaning': 'Breakout',
'dog in dreams': 'Breakout',
'dreams about dog': 'Breakout',
'dreams of dogs': 'Breakout',
'my dog dreams': 'Breakout',
'pet dreams': 'Breakout' } ]The examples shown for each API method can be run by changing into the home google-trends directory and running node examples.js. Note: Each example in examples.js need to be uncommented.
The following API methods are available:
- trendData: returns the historical trend data to a provided keyword or an array of keywords.
- topRelated: returns the top related keywords to a provided keyword or an array of keywords along with it's percentage of correlation.
- hotTrends: returns the current top 20 trending searches for a given location.
- hotTrendsDetail: same as the hotTrends results except with more detail such as links, publication date, approximate traffic, etc.
- top30in30: returns the top 30 searches in the past 30 days
- allTopCharts: returns the top trending charts for a given date and location. Charts contain information such as title, description, source, a jumpFactory, etc.
- categoryTopCharts: returns the top trending charts for a given category, date, and location.
For each of the API methods, rather than providing the parameters to the function in a specific order such as googleTrends.topRelated('keyword', 'country'), you can provide the function with an "options" object. Keys that are not required for the method are simply ignored. The available keys of the options object are as follows:
geo: 'country code provided as a string',date: 'date provided in format yyyymm as a string where January starts at 01,category: 'a string for a specific category',keywords: 'either an array of keywords as strings or a singular keyword as a string'
Returns the historical trend data to a provided keyword or an array of keywords.
#####Syntax
googleTrends.trendData(['keywords'])
['keywords']- either an array of keywords as strings or a string with one keyword. If keywords is an array, the results will be returned in an array of the same order as the input. Entering a keyword is required.
#####Example
The following example provides the historical trend data for 'OJ Simpson'. Optionally, the input could have been provided as googleTrends.trendData({keywords: 'OJ Simpson'}). Any other keys provided in the object will be ignore.
######Input
googleTrends.trendData('OJ Simpson')
.then(function(results){
console.log(results);
})
.catch(function(err){
console.error(err);
});######Output
[
{
"query": "oj simpson",
"values": [{
"date": "Thu, 01 Jan 2004 06:00:00 GMT",
"value": 4
}, {
"date": "Sun, 01 Feb 2004 06:00:00 GMT",
"value": 3
}, {
"date": "Mon, 01 Mar 2004 06:00:00 GMT",
"value": 3
}, {
"date": "Thu, 01 Apr 2004 06:00:00 GMT",
"value": 3
}, {
"date": "Sat, 01 May 2004 05:00:00 GMT",
"value": 4
}, {
"date": "Tue, 01 Jun 2004 05:00:00 GMT",
"value": 7
}, {
"date": "Thu, 01 Jul 2004 05:00:00 GMT",
"value": 2
}, {
"date": "Sun, 01 Aug 2004 05:00:00 GMT",
"value": 2
},
...
}, {
"date": "Mon, 01 Aug 2016 05:00:00 GMT",
"value": 9
}
}
]######Input
googleTrends.trendData(['swimming', 'olympics'])
.then(function(results){
console.log(results);
})
.catch(function(err){
console.error(err);
});######Output
[
{
"query": "swimming",
"values": [{
"date": "Thu, 01 Jan 2004 06:00:00 GMT",
"value": 5
}, {
"date": "Sun, 01 Feb 2004 06:00:00 GMT",
"value": 5
}, {
"date": "Mon, 01 Mar 2004 06:00:00 GMT",
"value": 5
}, {
"date": "Thu, 01 Apr 2004 06:00:00 GMT",
"value": 5
}, {
...
}, {
"date": "Mon, 01 Aug 2016 05:00:00 GMT",
"value": 10
}]
},
{
"query": "olympics",
"values": [{
"date": "Thu, 01 Jan 2004 06:00:00 GMT",
"value": 2
}, {
"date": "Sun, 01 Feb 2004 06:00:00 GMT",
"value": 3
}, {
"date": "Mon, 01 Mar 2004 06:00:00 GMT",
"value": 3
}, {
"date": "Thu, 01 Apr 2004 06:00:00 GMT",
"value": 3
}, {
...
}, {
"date": "Mon, 01 Aug 2016 05:00:00 GMT",
"value": 100
}]
}
]Returns the top related keywords for a provided keyword or an array of keywords
#####Syntax
googleTrends.topRelated(['keywords'], 'country')
-
['keywords']- either an array of keywords as strings or a string with one keyword. If keywords is an array, the results will be returned in an array of the same order as the input. Entering a keyword is required. -
country- an optional string for the country. Although the library can figure out the country from a formal name, it is preferred that the country is provided as a country code, for example, 'united states' should be provided as 'US', 'japan' should be provided as 'JP', etc. If no country code is provided, 'US' is assumed by default
#####Example
The following example provides the top related keywords to 'dog house' in the 'US'. Optionally, the input could have been provided as googleTrends.topRelated({keywords: 'dog house', geo: 'US'}). Order of the keys does not matter and any other keys provided in the object will be ignore.
######Input
googleTrends.topRelated('dog house', 'US')
.then(function(results){
console.log(results);
})
.catch(function(err){
console.error(err);
});######Output
[ { 'dog house grill': 'Breakout',
'best house dog': '+170%',
'the dog house': '+140%',
'the house': '+130%',
'house of dog': '+100%',
'large dog house': '+90%',
'house train dog': '+80%',
'small dog house': '+80%',
'animal house': '+70%',
'big dog house': '+70%' } ];Returns the current top 20 trending searches for a given location
#####Syntax
googleTrends.hotTrends('country')
country- an optional string for the country. Although the library can figure out the country from a formal name, it is preferred that the country is provided as a country code, for example, 'united states' should be provided as 'US', 'japan' should be provided as 'JP', etc. If no country code is provided, 'US' is assumed by default.
#####Example
The following example provides the top 20 trending searches in the 'US'. Optionally, the input could have been provided as googleTrends.hotTrends({geo: 'US'}). Any other keys provided in the object will be ignore.
######Input
googleTrends.hotTrends('US')
.then(function(results){
console.log(results);
})
.catch(function(err){
console.log(err);
});######Output
[ 'Donald Drumpf',
'Mark Ruffalo',
'Ashley Graham',
'Raspberry Pi 3',
'Oscars 2016',
'Why is there a leap day',
'Brie Larson',
'Alicia Vikander',
'Mark Rylance',
'Room',
'Stacey Dash',
'Mad Max Fury Road',
'merkin',
'Alejandro González Iñárritu',
'Sam Smith',
'The Big Short',
'The Hateful Eight',
'Jennifer Lawrence',
'Why Does Leap Year Have 366 Days',
'Inside Out' ];Returns the current top 20 trending searches for a given location
#####Syntax
googleTrends.hotTrendsDetail('country')
country- an optional string for the country. Although the library can figure out the country from a formal name, it is preferred that the country is provided as a country code, for example, 'united states' should be provided as 'US', 'japan' should be provided as 'JP', etc. If no country code is provided, 'US' is assumed by default.
#####Example
The following example provides the top 20 trending searches in the 'US'. Optionally, the input could have been provided as googleTrends.hotTrendsDetail({geo: 'US'}). Any other keys provided in the object will be ignore.
######Input
googleTrends.hotTrendsDetail('US')
.then(function(results){
console.log(results);
})
.catch(function(err){
console.log(err);
});######Output Note: Only showing some returned data for brevity
{ rss:
{ '$':
{ version: '2.0',
'xmlns:ht': 'http://www.google.com/trends/hottrends',
'xmlns:atom': 'http://www.w3.org/2005/Atom' },
channel:
[ { title: [ 'Hot Trends' ],
link: [ 'http://www.google.us/trends/hottrends?pn=p1' ],
'atom:link':
[ { '$':
{ href: 'http://www.google.us/trends/hottrends/atom/feed?pn=p1',
rel: 'self',
type: 'application/rss+xml' } } ],
description: [ 'Recent hot searches' ],
item:
[ { title: [ 'Melania Trump' ],
description: [ '' ],
link: [ 'http://www.google.us/trends/hottrends?pn=p1#a=20160301-Melania+Trump' ],
pubDate: [ 'Tue, 01 Mar 2016 01:00:00 -0800' ],
'ht:picture': [ '//t2.gstatic.com/images?q=tbn:ANd9GcT9MS12TcSh5cRqw6CGr7FXqTELrlqBPY-f6Nnpksa_Duy753wXe8jq1Q_fl9DVFRYqEHFW3BLA' ],
'ht:picture_source': [ 'Politico (blog)' ],
'ht:approx_traffic': [ '100,000+' ],
'ht:news_item':
[ { 'ht:news_item_title': [ '<b>Melania Trump</b> goes on the attack' ],
'ht:news_item_snippet': [ '<b>Melania Trump</b> said Marco Rubio's campaign has taken a “desperate tone” toward Donald Trump, but the Republican front-runner's wife is unbothered. Rubio finally engaged Donald Trump at last Thursday's Republican debate and hasn't let up since, ...' ],
'ht:news_item_url': [ 'http://www.politico.com/blogs/2016-gop-primary-live-updates-and-results/2016/03/melania-trump-marco-rubio-220015' ],
'ht:news_item_source': [ 'Politico (blog)' ] },
{ 'ht:news_item_title': [ '<b>Melania Trump</b>: 'Donald will change tone if he becomes president'' ],
'ht:news_item_snippet': [ 'Her comments came during a CNN interview with Anderson Cooper in which the host brought up the frequent insults fired between the Republican presidential candidates and the criticism Donald <b>Trump</b> has received for his tone on the campaign trail.' ],
'ht:news_item_url': [ 'http://www.independent.co.uk/news/people/melania-trump-donald-will-change-tone-if-he-becomes-president-a6904786.html' ],
'ht:news_item_source': [ 'The Independent' ] } ] },
...Returns the top 30 searches in the past 30 days
#####Syntax
googleTrends.top30in30()
top30in30does not take in parameters
#####Example The following example returns the top 30 searches in the past 30 days.
######Input
googleTrends.top30in30()
.then(function(results){
console.log(results);
})
.catch(function(err){
console.log(err);
});######Output Note: Only showing some returned data for brevity
{
"summaryMessage": "Showing top 30 searches in past 30 days",
"dataUpdateTime": 1456776000,
"weekDaysList": [
{
"title": "Sun"
},
{
"title": "Mon"
},
{
"title": "Tue"
},
{
"title": "Wed"
},
{
"title": "Thu"
},
{
"title": "Fri"
},
{
"title": "Sat"
}
],
"monthsList": [
{
"title": "January",
"height": 1
},
{
"title": "February",
"height": 4
}
],
"weeksList": [
{
"daysList": [
{
"date": "20160131",
"formattedDate": "31",
"longFormattedDate": "January 31",
"data": {
"numOfAdditionalTrends": 19,
"trend": {
"title": "Frederick Douglass",
"titleLinkUrl": "/search?q=frederick+douglass",
"relatedSearchesList": [],
"formattedTraffic": "10,000,000+",
"trafficBucketLowerBound": 10000000,
"hotnessLevel": 5,
"hotnessColor": "#d04108",
"imgUrl": "//t0.gstatic.com/images?q=tbn:ANd9GcRCCrM-fy25_79vt3P5YBXG_nZyhK4zya6kP5oMDSyts5WRMMlhxdUBtTKKVnFLgu2C0qXL6iU",
"imgSource": "CNN International",
"imgLinkUrl": "http://www.cnn.com/2016/02/01/living/frederick-douglass-google-doodle-black-history-month-feat/index.html",
"newsArticlesList": [
{
"title": "Who's <b>Frederick Douglass</b>? Learn more about civil rights leader and movement",
"link": "http://www.cnn.com/2016/02/01/living/frederick-douglass-google-doodle-black-history-month-feat/index.html",
"source": "CNN International",
"snippet": "His autobiography "Narrative of the Life of <b>Frederick Douglass</b>, An American" is a good place to start. "Ain't I a Woman?" Former slave Sojourner Truth told of the horror as an African-American woman in slavery in "Ain't I a Woman?" the speech she gave <b>...</b>"
},
{
"title": "<b>Frederick Douglass</b>: America's great abolitionist",
"link": "http://www.csmonitor.com/USA/Society/2016/0201/Frederick-Douglass-America-s-great-abolitionist",
"source": "Christian Science Monitor",
"snippet": "<b>Frederick</b> Augustus Washington Bailey was born into slavery in Maryland early in the 19th century. After beginning his life on a plantation, <b>Douglass</b> was sent to Baltimore, where he was first exposed to the alphabet and literacy. Allowing slaves to <b>...</b>"
}
],
"startTime": 1454302800,
"shareUrl": "https://www.google.com/trends/hottrends?stt=Frederick+Douglass&std=20160131&pn=p1#a=20160131-Frederick+Douglass",
"date": "20160131",
"exploreUrl": "/trends/explore#q=frederick+douglass&date=today+1-m&geo=US"
}
}
},
...Returns the top trending charts for a given date and location
#####Syntax
googleTrends.allTopCharts('date', 'country')
-
date- an optional string provided as 'yyyymm'. January === 01, December === 12. Note that google does not aggregate the data for the current month, so the date provided must always be at least one month behind. If no date is provided, the most recent date available is assumed. -
country- an optional string for the country. Although the library can figure out the country from a formal name, it is preferred that the country is provided as a country code, for example, 'united states' should be provided as 'US', 'japan' should be provided as 'JP', etc. If no country code is provided, 'US' is assumed by default.
#####Example
The following example provides the top charts in January 2016 in the 'US'. Optionally, the input could have been provided as googleTrends.allTopCharts({geo: 'US', date: '201601'}). Order of the keys does not matter and any other keys provided in the object will be ignore.
######Input
googleTrends.allTopCharts('201601', 'US')
.then(function(results){
console.log(results);
})
.catch(function(err){
console.log(err);
});######Output Note: Only showing some returned data for brevity
{
"summaryMessage": "Showing all charts",
"prevTimePeriod": "201512",
"nextTimePeriod": "",
"isMonthlyTimePeriod": true,
"data": {
"chartList": [
{
"trendingChart": {
"entityList": [
{
"title": "David Bowie",
"titleLength": 11,
"description": {
"description": "David Robert Jones, known as David Bowie, was an English singer, songwriter and musician, who also worked as an actor and record producer...",
"source": "Wikipedia",
"sourceUrl": "http://en.wikipedia.org/wiki/David_Bowie"
},
"shareUrl": "http://www.google.com/trends/topcharts?vm=trendingchart&cid=actors&date=201601&geo=US&cat&mid=/m/01vsy7t",
"twitterShareUrlTitle": "David Bowie #1 in Google Trends Actors trending chart",
"idForTracking": "David Bowie",
"exploreUrl": "/trends/explore#cmpt=q&q=/m/01vsy7t&date=1/2016+1m&geo=US",
"jumpFactorSummary": "+3,700%",
"topChartRank": 1,
"titleLinkUrl": "/search?q=David+Bowie"
},
{
"title": "Alan Rickman",
"titleLength": 12,
"description": {
"description": "Alan Sidney Patrick Rickman, was an English actor and director, known for playing a variety of roles on stage and screen...",
"source": "Wikipedia",
"sourceUrl": "http://en.wikipedia.org/wiki/Alan_Rickman"
},
"shareUrl": "http://www.google.com/trends/topcharts?vm=trendingchart&cid=actors&date=201601&geo=US&cat&mid=/m/09y20",
"twitterShareUrlTitle": "Alan Rickman #2 in Google Trends Actors trending chart",
"idForTracking": "Alan Rickman",
"exploreUrl": "/trends/explore#cmpt=q&q=/m/09y20&date=1/2016+1m&geo=US",
"jumpFactorSummary": "+7,500%",
"topChartRank": 2,
"titleLinkUrl": "/search?q=Alan+Rickman"
},
...Returns the top trending charts for a given category, date and location
#####Syntax
googleTrends.categoryTopCharts('category', 'date', 'country')
-
category- a specific category provided as a string that you wish to search for.categoryis a required parameter. -
date- an optional string provided as 'yyyymm'. January === 01, December === 12. Note that google does not aggregate the data for the current month, so the date provided must always be at least one month behind. If no date is provided, the most recent date available is assumed. -
country- an optional string for the country. Although the library can figure out the country from a formal name, it is preferred that the country is provided as a country code, for example, 'united states' should be provided as 'US', 'japan' should be provided as 'JP', etc. If no country code is provided, 'US' is assumed by default.
#####Example
The following example provides the top charts for actors in January 2016 in the 'US'. Optionally, the input could have been provided as googleTrends.categoryTopCharts({category: 'actors', geo: 'US', date: '201601'}). Order of the keys does not matter and any other keys provided in the object will be ignore.
######Input
googleTrends.categoryTopCharts('actors', '201601', 'US'})
.then(function(results){
console.log(results);
})
.catch(function(err){
console.log(err);
});######Output Note: Only showing some returned data for brevity
{
"data": {
"entityList": [
{
"title": "David Bowie",
"titleLength": 11,
"description": {
"description": "David Robert Jones, known as David Bowie, was an English singer, songwriter and musician, who also worked as an actor and record producer...",
"source": "Wikipedia",
"sourceUrl": "http://en.wikipedia.org/wiki/David_Bowie"
},
"shareUrl": "http://www.google.com/trends/topcharts?vm=trendingchart&cid=actors&date=201601&geo=US&cat&mid=/m/01vsy7t",
"twitterShareUrlTitle": "David Bowie #1 in Google Trends Actors trending chart",
"idForTracking": "David Bowie",
"exploreUrl": "/trends/explore#cmpt=q&q=/m/01vsy7t&date=1/2016+1m&geo=US",
"jumpFactorSummary": "+3,700%",
"topChartRank": 1,
"titleLinkUrl": "/search?q=David+Bowie"
},
{
"title": "Alan Rickman",
"titleLength": 12,
"description": {
"description": "Alan Sidney Patrick Rickman, was an English actor and director, known for playing a variety of roles on stage and screen...",
"source": "Wikipedia",
"sourceUrl": "http://en.wikipedia.org/wiki/Alan_Rickman"
},
"shareUrl": "http://www.google.com/trends/topcharts?vm=trendingchart&cid=actors&date=201601&geo=US&cat&mid=/m/09y20",
"twitterShareUrlTitle": "Alan Rickman #2 in Google Trends Actors trending chart",
"idForTracking": "Alan Rickman",
"exploreUrl": "/trends/explore#cmpt=q&q=/m/09y20&date=1/2016+1m&geo=US",
"jumpFactorSummary": "+7,500%",
"topChartRank": 2,
"titleLinkUrl": "/search?q=Alan+Rickman"
},
...##Potential errors
- Entering an incorrect or invalid country code will result in the following error:
'Could not locate country' - Entering an invalid date will result in the following error:
'Date is invalid' - If a required field is not provided, the following error will be returned:
FIELD must be provided - Exceeding the quota limits from google will result in the following error:
'Quota limit exceeded, try again later'