Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

26top related #34

Merged
merged 8 commits into from
Oct 23, 2016
Merged

26top related #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e96b4d6
switching RISING_QUERIES with TOP_QUERIES and making category optional
pat310 Oct 22, 2016
73c43d6
adding risingSearches method
pat310 Oct 22, 2016
edbcef0
adding tests for rising searches
pat310 Oct 22, 2016
13af843
adding timePeriod object to risingSearches and topRelated
pat310 Oct 22, 2016
5b6cd40
adding additional topRelated tests
pat310 Oct 22, 2016
cf0996b
adding to change log
pat310 Oct 23, 2016
33acb87
correcting bugs in README and CHANGES
pat310 Oct 23, 2016
417b54a
update will actually be major since 'topRelated' is breaking backward…
pat310 Oct 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
## [v3.0.0]
> Oct 22, 2016

- `topRelated` now correctly using `TOP_QUERIES` rather than `RISING_QUERIES` ([#34])
- `topRelated` now accepts an optional `timePeriod` object that will return trend data based on a provided time period ([#34])
- Added `risingSearches` method which accepts `category`, `timePeriod` and `geo` ([#34])

[#34]: https://github.com/pat310/google-trends-api/pull/34

## [v2.1.0]
> Oct 22, 2016

- `trendData` now accepts an optional `timePeriod` object that will return trend data based on a provided time period ([#33])

[v2.1.0]: https://github.com/pat310/google-trends-api/compare/v2.0.0...v2.1.0
[#33]: https://github.com/pat310/google-trends-api/pull/33

## [v2.0.0]
Expand All @@ -12,5 +20,4 @@
- `trendData` now returns [IETF-compliant RFC 2822 timestamps](https://tools.ietf.org/html/rfc2822#page-14) ([#32])
- Adding New Zealand to list of country codes

[v2.0.0]: https://github.com/pat310/google-trends-api/compare/v1.3.0...v2.0.0
[#32]: https://github.com/pat310/google-trends-api/pull/32
140 changes: 95 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Simple to use:
var googleTrends = require('google-trends-api');

var options = {
geo: 'country name',
geo: 'country code or name',
date: 'yyyymm',
keywords: ['some', 'list', 'of', 'keywords'],
category: 'some category',
Expand Down Expand Up @@ -44,6 +44,7 @@ googleTrends.apiMethod(options)
* [API Methods](#api-methods)
* [trendData](#trenddata)
* [topRelated](#toprelated)
* [risingSearches](#risingsearches)
* [hotTrends](#hottrends)
* [hotTrendsDetail](#hottrendsdetail)
* [top30in30](#top30in30)
Expand Down Expand Up @@ -77,57 +78,60 @@ You will now be able to access methods on `googleTrends`. See the [API Methods
### Promises
By default, all the API's return a promise for the results. Example:
```js
googleTrends.topRelated({keywords: 'dog house'})
googleTrends.topRelated('dog house')
.then(function(results){
console.log("Here are the results!", results);
console.log(results);
})
.catch(function(err){
console.error('We have an error!', err);
})
console.error(err);
});
```

Would console.log:
```js
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%' } ];
[ { 'the dog house': '100',
'the house': '100',
'house of dog': '50',
'dog house plans': '15',
'dog training': '15',
'dog house training': '15',
'house train dog': '15',
'build dog house': '10',
'best house dog': '10',
'dog houses': '10' } ]
```

### Callbacks
All API methods can also take a callback function as the last input parameter. For example:
```js
googleTrends.topRelated({keywords: 'dog dreams'}, function(err, results){
googleTrends.topRelated('dog house', function(err, results){
if(err) console.error('there was an error!', err);
else console.log('results', results);
else console.log(results);
})
```

Would console.log:
```js
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 dog house': '100',
'the house': '100',
'house of dog': '50',
'dog house plans': '15',
'dog training': '15',
'dog house training': '15',
'house train dog': '15',
'build dog house': '10',
'best house dog': '10',
'dog houses': '10' } ]
```

### Examples
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](/examples.js) need to be uncommented.
There are examples available for each API method that can be run by changing into the home `google-trends` directory and running `node examples.js`. **Note:** Each example in [examples.js](/examples.js) need to be uncommented.

### API Methods
The following API methods are available:
* [trendData](#trenddata): returns the historical trend data to a provided keyword or an array of keywords - optionally accepts a `timePeriod` object
* [topRelated](#toprelated): returns the top related keywords to a provided keyword or an array of keywords along with it's percentage of correlation.
* [topRelated](#toprelated): returns terms that are most frequently searched with the term(s) you entered in the same search session, within the chosen category (optional) and country (optional). If you didn't enter a search term, top searches overall are shown.
* [risingSearches](#risingsearches): returns terms that were searched for with the term you entered (or overall, if no keyword was entered), which had the most significant growth in volume in the requested time period. For each rising search term, you’ll see a percentage of the term’s growth compared to the previous time period. If you see “Breakout” instead of a percentage, it means that the search term grew by more than 5000%.
* [hotTrends](#hottrends): returns the current top 20 trending searches for a given location.
* [hotTrendsDetail](#hottrendsdetail): same as the [hotTrends](#hottrends) results except with more detail such as links, publication date, approximate traffic, etc.
* [top30in30](#top30in30): returns the top 30 searches in the past 30 days
Expand All @@ -140,6 +144,7 @@ For each of the API methods, rather than providing the parameters to the functio
* `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'
* `timePeriod`: an object with keys `type` and `value` where `type`'s value is an enumerated string (either 'hour', 'day', 'month', or 'year') and `value`'s value is a number

[back to top](#introduction)

Expand All @@ -152,7 +157,8 @@ For each of the API methods, rather than providing the parameters to the functio
`googleTrends.trendData(['keywords'], {type: 'string', value: number})`

* `['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**.
* `{type: 'string', value: number}` - the `timePeriod` object that must be formatted with keys `type` (which is an enumerated string of either 'hour', 'day', 'month', or 'year') and `value` (which is a number). Entering a `timePeriod` is optional. If no `timePeriod` object is provided, by default `trendData` will return all past trend data available.

* `{type: 'string', value: number}` - the `timePeriod` object that must be formatted with keys `type` (which is an enumerated string of either 'hour', 'day', 'month', or 'year') and `value` (which is a number). Entering a `timePeriod` is optional. If no `timePeriod` object is provided, by default all past trend data will be returned, otherwise trend data for the given time period will be returned.

#####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'})`.
Expand Down Expand Up @@ -253,7 +259,6 @@ googleTrends.trendData({keywords: 'Oj Simpson', timePeriod: {type: 'day', value:
```

######Output
**Note: Query was conducted on 10/22 so 5 days back leads to results starting at 10/17**
```js
[ { query: 'oj simpson',
values:
Expand Down Expand Up @@ -294,17 +299,19 @@ googleTrends.trendData({keywords: 'Oj Simpson', timePeriod: {type: 'day', value:
<hr>

#### topRelated()
*Returns the top related keywords for a provided keyword or an array of keywords*
*Returns terms that are most frequently searched with the term you entered in the same search session, within the chosen category (optional) and country (optional). If you didn't enter a search term, top searches overall are shown*

#####Syntax
`googleTrends.topRelated(['keywords'], 'country')`
`googleTrends.topRelated(['keywords'], {type: 'string', value: number}, '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**.
* `['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. If no keyword is entered, top searches overall are shown

* `{type: 'string', value: number}` - the `timePeriod` object that must be formatted with keys `type` (which is an enumerated string of either 'hour', 'day', 'month', or 'year') and `value` (which is a number). Entering a `timePeriod` is optional. If no `timePeriod` object is provided, by default all past data will be used

* `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.
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.

######Input
```js
Expand All @@ -319,16 +326,59 @@ googleTrends.topRelated('dog house', 'US')

######Output
```js
[ { 'dog house grill': 'Breakout',
'best house dog': '+170%',
'the dog house': '+140%',
'the house': '+130%',
'house of dog': '+100%',
[ { 'the dog house': '100',
'the house': '100',
'house of dog': '50',
'dog house plans': '15',
'dog training': '15',
'dog house training': '15',
'house train dog': '15',
'build dog house': '10',
'best house dog': '10',
'dog houses': '10' } ]
```

[back to top](#introduction)

<hr>

#### risingSearches()
*Returns terms that were searched for with the term you entered (or overall, if no keyword was entered), which had the most significant growth in volume in the requested time period. For each rising search term, you’ll see a percentage of the term’s growth compared to the previous time period. If you see “Breakout” instead of a percentage, it means that the search term grew by more than 5000%.*

#####Syntax
`googleTrends.risingSearches(['keywords'], {type: 'string', value: number}, '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. If no keyword is entered, top searches overall are shown

* `{type: 'string', value: number}` - the `timePeriod` object that must be formatted with keys `type` (which is an enumerated string of either 'hour', 'day', 'month', or 'year') and `value` (which is a number). Entering a `timePeriod` is optional. If no `timePeriod` object is provided, by default all past data will be used

* `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.risingSearches({keywords: 'dog house', geo: 'US'})`. Order of the keys does not matter.

######Input
```js
googleTrends.risingSearches('dog house', 'US')
.then(function(results){
console.log(results);
})
.catch(function(err){
console.error(err);
});
```

######Output
```js
[ { 'little dog house': '+250%',
'dog house grill': '+140%',
'large dog house': '+90%',
'house train dog': '+80%',
'small dog house': '+80%',
'animal house': '+70%',
'big dog house': '+70%' } ];
'best house dog': '+80%',
'hot dog house': '+70%',
'the dog house': '+70%',
'the house': '+70%',
'house of dog': '+50%',
'house train dog': '+40%' } ]
```

[back to top](#introduction)
Expand Down Expand Up @@ -386,7 +436,7 @@ googleTrends.hotTrends('US')
<hr>

#### hotTrendsDetail()
*Returns the current top 20 trending searches for a given location*
*Returns the current top 20 trending searches for a given location with more detail than the `hotTrends()` method*

#####Syntax
`googleTrends.hotTrendsDetail('country')`
Expand Down Expand Up @@ -570,7 +620,7 @@ googleTrends.top30in30()
* `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.
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.

######Input
```js
Expand Down Expand Up @@ -650,7 +700,7 @@ googleTrends.allTopCharts('201601', 'US')
* `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.
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.

######Input
```js
Expand Down
37 changes: 36 additions & 1 deletion examples.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ var util = require('util');

/* ~=~=~=~=~=~=~=~=~=~= EXAMPLE 2 =~=~=~=~=~=~=~=~=~=~ */
/* ~=~=~=~=~=~=~=~=~=~= topRelated =~=~=~=~=~=~=~=~=~=~ */
// // Parameters: array of key words (required), country as a string (optional, 'US' is default)
// // Parameters: array of key words (optional), country as a string (optional, 'US' is default)
// // optionally as the first argument pass an object: {keywords: ['dog'], geo: 'US'}
// googleTrends.topRelated({keywords: 'dog house'})
// .then(function(topRelated){
Expand All @@ -51,6 +51,16 @@ var util = require('util');
// return err;
// });

// // topRelated example with timePeriod object
// googleTrends.topRelated({keywords: 'dog house', timePeriod: {type: 'hour', value: 5}})
// .then(function(topRelated){
// console.log("here are the topRelated", topRelated);
// })
// .catch(function(err){
// console.log("there was an error", err);
// return err;
// });



/* ~=~=~=~=~=~=~=~=~=~= EXAMPLE 3 =~=~=~=~=~=~=~=~=~=~ */
Expand Down Expand Up @@ -116,4 +126,29 @@ var util = require('util');
// })
// .catch(function(err){
// console.log('there was an error', err);
// });



/* ~=~=~=~=~=~=~=~=~=~= EXAMPLE 8 =~=~=~=~=~=~=~=~=~=~ */
/* ~=~=~=~=~=~=~=~=~=~= risingSearches =~=~=~=~=~=~=~=~=~=~ */
// // Parameters: array of key words (optional), country as a string (optional, 'US' is default)
// // optionally as the first argument pass an object: {keywords: ['dog'], geo: 'US'}
// googleTrends.risingSearches({keywords: 'dog house'})
// .then(function(risingSearches){
// console.log("here are the risingSearches", risingSearches);
// })
// .catch(function(err){
// console.log("there was an error", err);
// return err;
// });

// // risingSearches example with timePeriod object
// googleTrends.risingSearches({keywords: 'dog house', timePeriod: {type: 'hour', value: 5}})
// .then(function(risingSearches){
// console.log("here are the risingSearches", risingSearches);
// })
// .catch(function(err){
// console.log("there was an error", err);
// return err;
// });
3 changes: 2 additions & 1 deletion src/utils/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,6 @@ module.exports = {
hotTrendsDetail: require(__dirname + '/hotTrendsDetail.js'),
top30in30: require(__dirname + '/top30in30.js'),
allTopCharts: require(__dirname + '/allTopCharts.js'),
categoryTopCharts: require(__dirname + '/categoryTopCharts.js')
categoryTopCharts: require(__dirname + '/categoryTopCharts.js'),
risingSearches: require(__dirname + '/risingSearches.js'),
};
31 changes: 31 additions & 0 deletions src/utils/risingSearches.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
'use strict';

var rp = require('request-promise');
var createObj = require(__dirname + '/../resources/callbacks.js');
var checkErrors = require(__dirname + '/../resources/errorHandling.js');
var parseHtml = require(__dirname + '/../resources/htmlParser.js').parseHtml;

module.exports = function request(keywords, timePeriod, geo, cbFunc){
var obj = createObj(arguments, request);
if(!obj.keywords) delete obj.keywords;

var error = checkErrors(obj);
if(error instanceof Error) return Promise.reject(obj.cbFunc(error));

return Promise.all(promiseArr(obj.keywords || [''], obj.timePeriod, obj.geo))
.then(function(results){
return obj.cbFunc(null, results);
})
.catch(function(err){
return Promise.reject(obj.cbFunc(err));
});
};

function promiseArr(keywords, timePeriod, country){
return keywords.map(function(keyword){
return rp(`http://www.google.com/trends/fetchComponent?hl=en-US&q=${keyword}&geo=${country}&cid=RISING_QUERIES_0_0&${timePeriod}`)
.then(function(htmlStrings){
return parseHtml(htmlStrings);
});
});
}
Loading