gator-score v1.0.1
gator-score is a realtime API to get a user's fraud score, geolocation, device, demographic, search and technology data based on an IP address, user agent and referrer.
A fraud score is a number from 0-1000 which indicates the likelyhood that the user is a bot. The lower the score, the more likely the user is a bot. A score less than 100 means it is very likely the user is a bot.
We use various methods to determine the fraud score, see our methodology.
In addition, the API returns all the detectable information on the user, like the device, geolocation, etc. This data is aggregated and available for reporting for account holders.
The API uses a REST interface, so it can be used from any platform.
Free version
There is a free version available that is rate-limited, so it should not be used for realtime access. No access token is required for the free version.
Usage
Server side scoring in Node.js
var gator = require('gator-score');
// Example - within an express route
app.get('/test', function (req, res) {
var options = {
accessToken: '',
ip: req.ip,
ua: req.headers['user-agent'],
referrer: req.headers['referer'],
url: req.hostname
};
gator.score(options, function(err, result) {
if (!err && result && result.score < 100) // a score less the 100 is very likely a bot
res.render('botContent');
else
res.render('humanContent');
});
});See full documentation.
Installation
$ npm install gator-scoreMethods
score(options, callback)
Scores the user and returns the result in the callback.
Arguments
optionsAn object containing the scoring parameters:accessTokenThe access token for the call that you can get from a gator.io account. Leave this blank for the free version, which is rate limited.ipThe IP address of the user.uaThe user agent of the user.referrerThe user's referrer.urlThe url of your site the user is ontimeoutThe timeout in milliseconds to wait for a response. Set this to a low value for a production website.
callback(err, result)errThe error object has the following format:codean HTTP status code from the REST call.messagethe associated error message.
resultThe user score object.
Example result
{
"score": 520, // a score less than 100 indicates a very high likelyhood of a bot or an invalid user
"offense": null, // this identifies the primary reason a user has a low score (colocation, collusion, etc.)
"organization": "Acme, Inc.", // the company, ISP, school or governmental agency of the user
"searchInfo": { // we detect over 200 search engines
"group": "Bing",
"name": "Bing",
"keys": "bicycles"
},
"campaign": "BingAds", // the pay version aggregates on dozens of attributes, including campaign, source, publisher id,
// medium, channel, etc.
"deviceType": "Mobile", // can also be desktop/laptop, tablet, console, TV and handheld.
"platformVersion": "iOS 9.2",
"platform": "iOS",
"isUniversity": false, // whether the user is within a university's netblock
"geolocation": { // I.P. based geolocation for web users - this is 100% accurate to the country and
// roughly 85% accurate to the postal code level.
"countryCode": "US",
"countryName": "United States",
"region": "CA",
"city": "Laguna Niguel",
"postalCode": "92677",
"latitude": 33.5351,
"longitude": -117.7052,
"dmaCode": 803, // a Designated Market Area (DMA) is a group of counties in the United States that are
// covered by a specific group of television stations.
"areaCode": 949,
"continentCode": "NA",
"regionName": "California"
},
"demographics": { // these are demographics for the postal code the user is in
"medianHouseholdIncome": 112620,
"averageHomeValue": 798918,
"percentWhite": 77.56,
"percentBlack": 1.44,
"percentHispanic": 15.81,
"percentAsian": 10.24,
"percentFemale": 51.35,
"percent0_14": 21.4,
"percent15_24": 12.1,
"percent25_34": 10,
"percent35_44": 15.3,
"percent45_54": 18.3,
"percent55_64": 12.7,
"percent65Over": 10.1
},
"browserVersion": "Safari",
"browser": "Safari",
"status": "This result was delayed intentionally as part of the free version. Create an account at www.gator.io for full speed access."
}Endpoints
We are creating global endpoints for this API. The API is extremely fast, however we cannot control latency on the internet. To address this, we support colocation or replication to your cloud provider's site. Please contact us to set this up.
Sample use cases
AdsDo not display ads to invalid users. Keep your reputation as a publisher intact.Content OptimizationTailor your content based on a user's geo, demo or device type.OffersBase offers on search terms, or user's demographic.Publisher NetworksSee which publishers have the best and worst traffic.Save bandwidthWhy stream videos to bots?
License
The MIT License (MIT) Copyright (c) 2016 Phil Vizzaccaro
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.