AddThis Data API

Last Updated: Oct 18, 2013 03:31PM EDT

Overview

The AddThis Data API helps you leverage on- and off-domain data to optimize your site at run time, including:

  • Social engagement - how much does this user use Facebook, Twitter and hundreds of other networks?
  • Traffic Source - where did the current page view come from? Search? A social site?
  • Geolocation - estimated country, lat/lon, ZIP code, etc.
  • Site activity - are they a new or returning user?

It's in a public beta right now, so please do let us know what you think.

 


Use Cases

There are many ways to personalize your site using the API. For example:

  • Increase the conversion of new followers by inviting the user to follow you on their preferred social network
  • Increase the likelihood that visitors register for your site by showing third-party login buttons (Facebook, Twitter, etc) that they actually use
  • Reach out to new visitors driven by paid media
  • Show promos to your most loyal users
  • Customize your site's content based on the user's geolocation or ZIP code
 


API

The API exposes raw data in JSON format; you're welcome to use it directly. However, if you'd rather be able to write code that reads like business logic, we've implemented a robust library on top of the API itself to make data processing easy.


Setup

Because the library depends on data stored on the AddThis.com domain, it must be initialized before use. After initialization, all methods are available.

1. Include the regular AddThis code

<script type="text/javascript" src="http://s7.addthis.com/js/250/addthis_widget.js#username=your-username"></script>

2. Register a callback

addthis.user.ready(function (data){
    // This function gets called once the API is initialized.
    // Within this callback, you can use our data object directly,
    // or call our library methods.
    // The latter are described first below, in User Data Queries.
    // For working with the data object directly, see Raw Data Access.
});
 

User Data Queries

A number of common yes/no questions are answerable out of the box. For ease of readability, all examples assume the presence of jQuery.

user.isUserOf([service(s)])

Check if the user uses a particular service. Returns true if the user has recently shared a link to that service, clicked a link from that service, or registered it as a preferred service.

Example: show Facebook promo to Facebook users
if (addthis.user.isUserOf('facebook')) {
    $('#facebook-banner').show();
}
Example: show a social promo to users of popular social networks
if (addthis.user.isUserOf('google_plus, pinterest, facebook, twitter')) {
    $('#social-promo').show();
}

user.isLocatedIn([location])

True if the user is located in the specified location, which could be a ZIP code, state, country, or continent (using ISO-3166-1 two-character codes).

Example
// If the user's in North or South America, show a special banner

if (addthis.user.isLocatedIn('na, sa')) {
    $('#americas-rule-banner').show();
} else if (addthis.user.isLocatedIn('fr')) {
    $('#france-rules-banner').show();
}
 

user.isOptedOut()

True if the user is opted out of tracking (either through AddThis or Do Not Track, if available).

 

user.isReturning()

True if the user has been to this site before.

 


Traffic Source Queries

session.isSearch([term(s)])

True if the current session arrived from a search referrer, optionally with the specified terms.

Example
// If the session originated on a search for motorboats or smuggling...
if (addthis.session.isSearch("motorboats, smuggling")) {
    callFBI();
}
 

session.isSocial([site(s)])

True if the current session arrived from a social referrer, optionally only counting the provided sites.

Example
// If the user arrived from Facebook or Twitter, show a message
if (addthis.session.source.isSocial("facebook, twitter")) {
    $("#fb-twitter-follow").show();
}
 



Collections

For more complex use cases, we wrap all our major data points in collections with special methods for slicing and dicing.

user.services()

Returns ordered collection of objects representing services the user has shared to or visited from.

Example
[{name: 'facebook', score: addthis.MED},
{name: 'twitter', score: addthis.LOW}]
 

This collection has the following methods available:

keys([sortDirection])

Pulls out the service names in rank order, by default from most relevant to least, in an array.

Example
var svcs = addthis.user.services().keys();
// = ['facebook', 'twitter']
var svcs = addthis.user.services().keys(addthis.ASC);
// = ['facebook', 'twitter']
var svcs = addthis.user.services().keys(addthis.DESC);
// = ['twitter', 'Facebook']
 
toMap()

Transforms the collection into a dictionary keyed by name.

Example
var serviceMap = addthis.user.services().toMap();
// = {'facebook': {'name':'facebook', ...}, ....}
if (serviceMap.facebook) {
    // do something about Facebook.
}
if (serviceMap.facebook.score > serviceMap.twitter.score) {
    // you must not live in the Bay Area
}
 
top([topN])

Return the user's top N most preferred services -- defaults to the topmost service (N=1).

Example
var topService = addthis.user.services().top(); // 'facebook'
var topServices = addthis.user.services().top(2); // ['facebook','twitter']
 
filter(criteria)

Returns a collection matching only the specified criteria.

Example
// matches only highly preferred services
var topServices = addthis.user.services().filter({score: addthis.HIGH});
 
 

user.location()

Returns a dictionary describing the user's geolocation.

Example
var geo = addthis.user.location();
// geo.zip = 11201
// geo.state = 'ny'
// geo.country = 'us'
// geo.continent = 'na'
user.location().contains()

Convenience method, equivalent to addthis.user.isLocatedIn().

 
 

session.source()

Returns a dictionary describing the origin of this session: on-domain, off-domain, search or social.

var source = addthis.session.source(); // dictionary
// source.type = social|search|internal|referred|direct
// source.service = 'facebook'; // social referer
// source.domain = 'google.com'; // search referrer
// source.terms = ['speedboats','smuggling']; // any search terms used
 


Raw Data

If the thought of using convenience methods boils your hacker blood, we also expose the full user data object in the addthis.user.ready() callback.

Sample object:

{
    services:  [
        {name: "twitter", score: addthis.HIGH},
        {name: "facebook", score: addthis.LOW}
    ],
    activity: {
        social: addthis.MED,
        view: addthis.HIGH
    },
    location: {
        continent: "NA",
        country: "US",
        region: "NY",
        zip: "11201"
    },
    source: {
        type: "social",
        service: "facebook"
    },
    tags: [
    ]
}
 


Reference

Services

The services field lists social networks and other services used by the user, in rank order. A full list of service codes can be found at addthis.com/services/list.

Geographic Data Accuracy

Geographic information is determined by IP address lookup, based on data provided by our global CDN providers. Data is generally accurate within a metropolitan area for most users, though it can vary for users on mobile or VPN connections.

Performance

Retrieving user data requires cross domain communication which incurs a slight delay. Average callback time is 100ms, based on page layout, browser speed and browser cache.

Back to Top

Still need help?


General Topics

 

Developers