Services API

Overview

The Services API provides public access to sharing destination metadata and icons from our Services Registry in a variety of formats common to the web: JSON, JSONP, and XML. Armed with this data, the oExchange sharing endpoints, and the personalization information provided by the User Data API, you now have all the same tools as the official AddThis menu. We're very excited to see what sort of innovative sharing tools and cool mashups the AddThis community will dream up!

The Services API is divided into two groups: metadata and icons, each with multiple response formats best suited for different uses. For this early release, we focused on HTML/JS and Flash as the two dominant technologies driving the web.

Please remember this API is an Alpha Preview. Things are subject to change, and there might be a few rough edges.

Most importantly, though, is feedback: your comments and ideas are greatly appreciated. We're eager to listen, and your early feedback will have a strong impact on the shape of this API moving forward.

Back to Top

Service Metadata API

The Metadata APIs provide access to information about the sharing destinations in our Services Registry. This information is available in JSON, JSONP, and XML.

Making a request is simple. Just choose the format you want back:

• JSON: http://cache.addthiscdn.com/services/v0/sharing.en.json
• JSONP: http://cache.addthiscdn.com/services/v0/sharing.en.jsonp#jsonpcallback=callback_fn_name
• XML: http://cache.addthiscdn.com/services/v0/sharing.en.xml

The response depends on the format you ask for, but the data has a similar structure in each. Here are a few examples:

JSON and JSONP Sample Response

{
    "version": "0.1.0",
    "update": "http://cache.addthiscdn.com/services/v0/sharing.en.json",
    "data": {
        "facebook": {
            "code": "facebook",
            "name": "Facebook",
            "icon": "http://cache.addthiscdn.com/icons/v0/thumbs/facebook.gif"
        },
        ...
    }
}

The JSONP response is the same, but it'll be wrapped in JavaScript to find your callback and hand off the data.

XML Sample Response

<?xml version="1.0"?>
<sharing>
    <version>0.1.0</version>
    <update>http://cache.addthiscdn.com/services/v0/sharing.en.json</update>
    <data>
        <services>
            <service code="facebook">
                <code>facebook</code>
                <name>Facebook</name>
                <icon>http://cache.addthiscdn.com/icons/v0/thumbs/facebook.gif</icon>
            </service>
            ...
        </services>
    </data>
</sharing>

Pretty simple, eh?

From here, you can check out the demos or dive into more detail with the more technical documentation for the API endpoints and their reponses.

Request Structure

You might have noticed a pattern in those endpoint URLs. The request has a simple structure:

• http://cache.addthiscdn.com/services/v<major>/sharing.<lang>.<format>

Those tokens in the URL are parameters that let you customize the response, but for now, most of them only support one value.

• <major>: API Compatibility Branch. A given major version is guaranteed to be API-stable for all updates. In this case, the structure of the response won't change without the major version changing. The current (and only) major version is 0 — don't forget the v!
• <lang>: Localization Language. Currently, the only supported localization is English (en). For public release, we will provide all of the same languages as available here, however the only localizable strings in the API response are the "generic services" like email and print).
• <format>: Response Format. Currently supported values are json, jsonp, and xml.

Response Structure

The format-independent structure an API response consists in a standard wrapper containing metadata about the API request itself and a collection of service metadata entries under the key data.

Response Wrapper

Field Name	Type	Description
update	String	URL that generated this response.
version	String	Full release version of this reponse.
data	Object	Mapping from service code to Service Metadata Entry.

Response Data

The data field of the standard wrapper is a list of Service Metadata Entries. Each entry has the following structure:

Field Name	Type	Description
code	String	Service short-code.
name	String	Presentation name.
icon	String	URL to 16x16 GIF thumbnail icon.

Formatted responses bear out this structure. The API currently supports three response formats: JSON, JSONP, and XML.

JSON and JSONP Sample Response

The JSON and JSONP responses have the same structure; the JSONP response will be wrapped in JavaScript whcih finds your callback and hands the data back to you.

{
    "version": "0.1.0",
    "update": "http://cache.addthiscdn.com/services/v0/sharing.en.json",
    "data": {
        "facebook": {
            "code": "facebook",
            "name": "Facebook",
            "icon": "http://cache.addthiscdn.com/icons/v0/thumbs/facebook.gif"
        },
        ...
    }
}

XML Sample Response

<?xml version="1.0"?>
<sharing>
    <version>0.1.0</version>
    <update>http://cache.addthiscdn.com/services/v0/sharing.en.json</update>
    <data>
        <services>
            <service code="facebook">
                <code>facebook</code>
                <name>Facebook</name>
                <icon>http://cache.addthiscdn.com/icons/v0/thumbs/facebook.gif</icon>
            </service>
            ...
        </services>
    </data>
</sharing>

Back to Top

Service Icon API

The Service Icon API provides access to sharing destination thumbnail images.

Usage is straight forward:

• HTML: If you're building a webpage or webapp to use the icons, you add a CSS class to the elements that are to become icons, and then load our CSS file.
• Flash: Working in Flash, you load the desired icons using the Loader class. Position to taste. That's it!

We've prepared a "Quick Start" guide for use in a webpage, as well as working on demos for both HTML and Flash.

Service Icon Sprites

• Endpoint: http://cache.addthiscdn.com/icons/v0/sprites/services.css

The Service Icon Sprite-Sheet provides CSS classes for creating on-page service icons without loading the AddThis menu. The style sheet only loads one image, a highly optimized sprite of all icons. It provides CSS classes as the API to render a service icon. The Sprite Sheet is the fastest, smallest way to make use of service icons, and we strongly recommend it for building web apps with service icons.

Displaying an icon is a two-step process, but you can perform those steps in any order.

Include the Sprite Sheet

Include the sprite style-sheet in your page's <head> tag:

<link rel="stylesheet" href="http://cache.addthiscdn.com/icons/v0/sprites/services.css" type="text/css"/>

If you're worried a the stylesheet slowing down pageload, you can instead attach it with JavaScript once the DOM is ready.

Apply Icon Classes

For each service icon you want to display, create a <span> tag and give it two CSS classes:

addthis_service_icon icon_<service-code>

This will set the size of the tag to match the icon, attach the sprite as the background, and finally adjust it to display the icon you chose.

For example, to add the Facebook icon, add this element:

<span class="addthis_service_icon icon_facebook"></span>

If you're using the Service Metadata API, the response has a code for every service. If you want to choose your own services, the codes are available in the Service Directory; simply replace <service-code> in the class with the value for that desitination.

For a fully working example, check out the HTML Demo.

Service Icon Thumbs

• Endpoint: http://cache.addthiscdn.com/icons/v0/thumbs/<service-code>.gif
• Example: http://cache.addthiscdn.com/icons/v0/thumbs/facebook.gif

In cases where CSS styling is not available, such as Flash, we also provide individual 16x16 icons in GIF format.

If you're using the Service Metadata API, the response has an icon URL for every service. If you want to choose services without calling the API, the codes are available in the Service Directory; simply replace <service-code> in the endpoint URL with the value for that desitination.

Back to Top

API Demos

To get you started—and eat our own dog food—we've built two working demos using the Services API, one in HTML/JS/CSS, and one in Flash.

These demos are pretty basic, but don't let that limit your imagination! Our goal was nothing more than simple, easy to understand code useing both the APIs.

HTML Demo

View the Demo

This demo uses HTML, CSS, and JavaScript to display all the available service metadata, along with an icon for each service. It first calls the JSONP Service Metadata endpoint, and then uses the Service Icon Sprite-Sheet to add icons.

Try it: http://cache.addthiscdn.com/downloads/demo/api/services/html/
Source: Use "view source" in your browser, or right click this link and choose "Save As".

Flash Demo

View the Demo

This demo uses Flash to display a grid of the available services as icons; further information is shown on click. It first calls the XML Service Metadata endpoint, and then loads the Service Icon Thumb for each destination.

This example ended up being a little more complex than I wanted in order to keep certain browsers from dying. Apparently IE doesn't like it when you make several hundred simultaneous image requests.

Try it: http://cache.addthiscdn.com/downloads/demo/api/services/flash/

Source:

• ActionScript: http://cache.addthiscdn.com/downloads/demo/api/services/flash/ServiceAPIExample.as
• HTML: Use "view source" in your browser, or right click this link and choose "Save As".
• All Files: .zip | .tar.gz