Get Glue: API

Glue API

The Glue API allows you to create your own applications that utilize the Objects, People, and Interactions on Glue in new and exciting ways! Got questions? Head on over to our Developer Forum

Terms of Service

By using the Glue API, you agree to abide by these terms of service.

You agree to limit the number of queries per day to 5000.
You agree to use the API in compliance with AdaptiveBlue's Privacy Policy.
You agree to abide by the terms of service of the other APIs used by the Glue API.
You agree not to copy/store/replicate/cache the API responses for more than 24 hours.
You agree not to replace AdaptiveBlue affiliate ids in the links within API responses.
You agree that AdaptiveBlue reserves the right to change the API at any time.
You agree that AdaptiveBlue may disable access to the API at any time and for any reason.
You agree that the API is provided to you "AS IS" and without any warranty or condition, implied or statutory.
You agree that AdaptiveBlue is not liable for any damages resulting from the use of the API.

Please use the API in accordance with the documentation below.

Basics

Authentication
API Paths
Object IDs

API Calls

Check-in Methods
User Methods
Object Methods
Network-wide Methods
Paging

Response

API Response Format
Interaction format

Errors

Glue API Errors
OAuth Errors

Authentication

All API calls (besides /user/login) require some form of authentication. You have two options available to you: OAuth 1.0 and AdaptiveBlue's token authentication. Calls that act on behalf of a user, such as /user/follow and /user/addCheckin, must be authorized by the user

OAuth 1.0 (recommended)

You may sign your requests to the API using OAuth. Calls that access public data need only to be signed using your developer key. Calls that act on behalf of a user require an access token as well. To obtain a developer key, please e-mail support@getglue.com with your name, company name, app name, and OAuth callback (if needed), as well as a short description of the application.

Glue's endpoint configuration is as follows:
Request Token: http://api.getglue.com/oauth/request_token
Authorization: http://getglue.com/oauth/authorize
Access Token: http://api.getglue.com/oauth/access_token

A limited number of OAuth-specific errors may be returned and are documented in the OAuth Errors documentation.

Token-based (deprecated)

AdaptiveBlue also has its own token-based authentication system. A token can be requested by calling /user/login with the user's credentials. The token returned from that call should then be passed along with every other API request as token={token}. If you are planning on only accessing public data, you may use your personal or business GetGlue.com account. Calls that act on behalf of a user use the token user as the acting user. Tokens do not expire.

API Paths

With the exception of the OAuth endpoints, all API methods are accessible under http://api.getglue.com/v2. For example, /user/profile would be accessible at http://api.getglue.com/v2/user/profile

Object IDs

When requesting information about an object on Glue, the objectId parameter can take either a Glue object key or a URL.

Object Key - A Glue object key is either in the format type/primary or type/primary/secondary, depending on the object type. type is the type of the object (books, tv_shows, movies), primary is generally the title and secondary is some secondary attribute (such as the author or director). Object keys uniquely identify objects in the system. You should not attempt to construct object keys yourself, but may use the objectKey fields returned by the API to refer to specific objects.

Object URL - If a URL is given as the objectId to an API call, the Glue API will attempt to automatically determine the object that the URL represents for use with the call.

Check-in Methods

/user/addCheckin

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
source - the source of the interaction, can be the URL of your application's homepage
app - the name of your application
comment - (optional) the twocents comment (Limit 140 characters)

Response:

The interaction that has been modified.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Checkin</action>
    <comment>This movie was great!</comment>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/addCheckin?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp&comment=This was a great movie!
http://api.getglue.com/v2/user/addCheckin?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp&comment=This was a great movie!

/object/users

The /object/users method has a checkinActivity section for object check-in data, and can be filtered to only return check-in data with action=checkedIn or action=lastCheckedIn. checkedIn returns all check-ins for the object, whereas lastCheckedIn only returns each user's most recent check-in.

Examples:
http://api.getglue.com/v2/object/users?objectId=http://www.amazon.com/dp/B001P9KR8U/&action=checkedIn
http://api.getglue.com/v2/object/users?objectId=movies/slumdog_millionaire/danny_boyle&action=checkedIn

http://api.getglue.com/v2/object/users?objectId=http://www.amazon.com/dp/B001P9KR8U/&action=lastCheckedIn
http://api.getglue.com/v2/object/users?objectId=movies/slumdog_millionaire/danny_boyle&action=lastCheckedIn

/user/removeCheckin

This method will be performed as the user authorized by either an OAuth access token or a Glue token. Note that timestamps are required, due to the fact that multiple checkins to the same object are allowed.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
timestamp - the timestamp of the checkin you wish to remove

Response:

<success/>

Examples:
http://api.getglue.com/v2/user/removeCheckin?objectId=http://www.amazon.com/dp/B001P9KR8U/&timestamp=2009-05-19T21:47:49Z
http://api.getglue.com/v2/user/removeCheckin?objectId=movies/slumdog_millionaire/danny_boyle&timestamp=2009-05-19T21:47:49Z

User Methods

/user/login (deprecated)

Parameters:

userId - Glue username
password - Glue password
version - Glue version (currently 4.5)

Response:

This call is now deprecated in favor of OAuth. An authentication token, to be used in other API calls. If possible, the call should be made via HTTPs.

<ping>
    <userId>glueman</userId>
    <serverTime>1257207570817</serverTime>
    −
    <token>glue token</token>
</ping>

Example: https://api.getglue.com/v2/user/login?userId=glueman&password=myPass

/user/addVisit

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
source - the source of the interaction, must be a URL (can be the homepage of your application)
app - the name of your application

Response:

The interaction that has been created/modified.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Looked</action>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/addVisit?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp
http://api.getglue.com/v2/user/addVisit?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp

/user/addLike

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
source - the source of the interaction, must be a URL (can be the homepage of your application)
app - the name of your application
comment - (optional) the twocents comment (Limit 140 characters)

Response:

The interaction that has been modified.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Liked</action>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/addLike?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp
http://api.getglue.com/v2/user/addLike?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp

/user/addDislike

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
source - the source of the interaction, can be the URL of your application's homepage
app - the name of your application
comment - (optional) the twocents comment (Limit 140 characters)

Response:

The interaction that has been modified.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Disliked</action>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/addDislike?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp
http://api.getglue.com/v2/user/addDislike?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp

/user/addFavorite

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
source - the source of the interaction, can be the URL of your application's homepage
app - the name of your application
comment - (optional) the twocents comment (Limit 140 characters)

Response:

The interaction that has been modified.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Favorited</action>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/addFavorite?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp
http://api.getglue.com/v2/user/addFavorite?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp

/user/askFriends

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
source - the source of the interaction, can be the URL of your application's homepage
app - the name of your application
comment - the twocents comment (Limit 140 characters)

Response:

The interaction that has been modified.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Commented</action>
    <comment>This movie was great!</comment>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/askFriends?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp&comment=This was a great movie!
http://api.getglue.com/v2/user/askFriends?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp&comment=This was a great movie!

/user/removeInteraction

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey

Response:

<success/>

Examples:
http://api.getglue.com/v2/user/removeInteraction?objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/user/removeInteraction?objectId=movies/slumdog_millionaire/danny_boyle

/user/addReply

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
app - the name of your application
replyTo - Glue username of the person you wish to reply to
comment - the reply (Limit 140 characters)
timestamp - (optional) if replying to a Checkin, timestamp of Checkin must be passed in

Response:

The interaction that has been created.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Reply</action>
    <comment>This movie was great!</comment>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>Joe</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/addReply?objectId=http://www.amazon.com/dp/B001P9KR8U/&source=http://exampleglueapp.com/&app=ExampleApp&replyTo=mtab&comment=Yeah, it was really good!
http://api.getglue.com/v2/user/addReply?objectId=movies/slumdog_millionaire/danny_boyle&source=http://exampleglueapp.com/&app=ExampleApp&replyTo=mtab&comment=Yeah, it was really good!

/user/removeReply

This method will be performed as the user authorized by either an OAuth access token or a Glue token. Note that timestamps are required, due to the fact that multiple replies on the same object are allowed.

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
userId - Glue username of the person the reply is to
timestamp - the timestamp of the reply

Response:

<success/>

Examples:
http://api.getglue.com/v2/user/removeReply?objectId=http://www.amazon.com/dp/B001P9KR8U/&timestamp=2009-05-19T21:47:49Z
http://api.getglue.com/v2/user/removeReply?objectId=movies/slumdog_millionaire/danny_boyle&timestamp=2009-05-19T21:47:49Z

/user/profile

Parameters:

userId - Glue username

Response:

The user's profile (display name, interaction counts, description, stats, stickers, services [other networks, blogs]). All values will be returned, even if empty or 0, with the exception of service ids which will only be returned if set.

<profile>
    <private>false</private>
    <hideVisits>false</hideVisits>
    <displayName>Glue Man</displayName>
    <description>A man made of glue</description>
    <friends>89</friends>
    <followers>90</followers>
    <stats>
            <visitedProfiles>44</visitedProfiles>
            <nonFriendProfiles>44</nonFriendProfiles>
            <visited>29</visited>
            <liked>10</liked>
            <commented>1</commented>
            <disliked>3</disliked>
            <guru>5</guru>
    </stats>
    <favorites>
            <books>1</books>
            <electronics>0</electronics>
            <movie_stars>2</movie_stars>
            <movies>5</movies>
            <music>3</music>
            <recording_artists>0</recording_artists>
            <restaurants>0</restaurants>
            <tv_shows>0</tv_shows>
            <topics>0</topics>
            <video_games>0</video_games>
            <wines>0</wines>
    </favorites>
    <postToTwitter>false</postToTwitter>
    <postToFacebook>true</postToFacebook>
    <username>glueman</username>
    <stickers>
            <sticker>
                    <name>Bootcamp</name>
            </sticker>
            <sticker>
                    <name>Curious George</name>
                    <level>10</level>
                    <count>44</count>
            </sticker>
    </stickers>
    <unlockedStream>true</unlockedStream>
</profile>

Example: http://api.getglue.com/v2/user/profile?userId=mtab

/user/friends

Parameters:

userId - Glue username

Response:

The user's friends. Note that usernames are case sensitive.

<friends>
    <userId>Joe</userId>
    <userId>Jack</userId>
    <userId>jill</userId>
    <userId>Mike</userId>
    <userId>tom</userId>
    <userId>Bob</userId>
    ...
</friends>

Example: http://api.getglue.com/v2/user/friends?userId=mtab

/user/followers

Parameters:

userId - Glue username

Response:

The user's followers. Note that usernames are case sensitive.

<followers>
    <userId>Joe</userId>
    <userId>Jack</userId>
    <userId>jill</userId>
    <userId>Mike</userId>
    <userId>tom</userId>
    <userId>Bob</userId>
    ...
</followers>

Example: http://api.getglue.com/v2/user/followers?userId=mtab

/user/isFriend

Parameters:

userId - Glue username friendUserId - Glue username

Response:

true if userId is friends with friendUserId, otherwise false. If the user is protected and friend request is still pending, "pending" will be returned.

Example: http://api.getglue.com/v2/user/isFriend?userId=mtab&friendUserId=netpro2k

/user/follow

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

followUserId - Glue username of the person to follow

Response:

On success:

<success/>

If awaiting protected user's approval:

<pending/>

Example: http://api.getglue.com/v2/user/follow?followUserId=mtab

/user/unfollow

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

unfollowUserId - Glue username of the person to unfollow

Response:

<success/>

Example: http://api.getglue.com/v2/user/unfollow?unfollowUserId=mtab

/user/objects

Parameters:

userId - Glue username
category - One of the categories supported by Glue or all.

Response:

The most recent interactions of a user within the given category. (See paging for details on how to request additional items)

<interactions>
    <interaction>
        <title>Home Alone</title>
        <userId>mtab</userId>
        <displayName>Mark Tabry</displayName>
        <action>Liked</action>
        <objectKey>movies/home_alone/chris_columbus</objectKey>
        <source>http://www.imdb.com/title/tt0099785</source>
        <timestamp>2009-04-20T19:29:05Z</timestamp>
    </interaction>
    ...
</interactions>

Example: http://api.getglue.com/v2/user/objects?userId=mtab&category=movies

/user/object

Parameters:

userId - Glue username
objectId - either the URL of a recognized page or Glue objectKey

Response:

The interaction for the specific userId/objectId combination.

<interaction>
    <title>Home Alone</title>
    <userId>mtab</userId>
    <displayName>Mark Tabry</displayName>
    <action>Liked</action>
    <objectKey>movies/home_alone/chris_columbus</objectKey>
    <source>http://www.imdb.com/title/tt0099785x</source>
    <timestamp>2009-04-20T19:29:05Z</timestamp>
</interaction>

Examples:
http://api.getglue.com/v2/user/object?userId=mtab&objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/user/object?userId=mtab&objectId=movies/slumdog_millionaire/danny_boyle

/user/stream

This method will be performed as the user authorized by either an OAuth access token or a Glue token.

Parameters:

streamType -(optional, default is all) single letter stream type, one of the following: s (suggestions), f (friends), r (replies), p (popular)
category - One of the categories supported by Glue or all. Defaults to all.

Response:

The last 20 items from the user's stream, filtered by streamType and category (See paging for details on how to request aditional items)

<interactions>
    <interaction>
        <title>Home Alone</title>
        <userId>mtab</userId>
        <displayName>Mark Tabry</displayName>
        <action>Liked</action>
        <objectKey>movies/home_alone/chris_columbus</objectKey>
        <source>http://www.imdb.com/title/tt0099785</source>
        <timestamp>2009-04-20T19:29:05Z</timestamp>
    </interaction>
    <interaction>
        <title>12 Angry Men</title>
        <userId>mtab</userId>
        <displayName>Mark Tabry</displayName>
        <action>Reply</action>
        <comment>
            Yes. It rocked for me, not sure if it will be the same
            in translation. Cultural references and slang were big.
        </comment>
        <objectKey>movies/12_angry_men/sidney_lumet</objectKey>
        <source>http://getglue.com/users/alex</source>
        <timestamp>2009-03-22T03:40:28Z</timestamp>
    </interaction>
    ...
</interactions>

Examples:
http://api.getglue.com/v2/user/stream?category=all (gets last 20 items in stream)
http://api.getglue.com/v2/user/stream?category=movies&streamType=s (gets last 20 movie suggestions)

/user/guru

Parameters:

userId - Glue username

Response:

The last 20 items that this user became the Guru of (See paging for details on how to request aditional items)

<interactions>
    <interaction>
        <title>Home Alone</title>
        <userId>mtab</userId>
        <displayName>Mark Tabry</displayName>
        <action>LikedComment</action>
        <comment>Ahhhhhh!</comment>
        <objectKey>movies/home_alone/chris_columbus</objectKey>
        <source>http://www.imdb.com/title/tt0099785</source>
        <timestamp>2009-04-20T19:29:05Z</timestamp>
        <funny>3</funny>
    </interaction>
    ...
</interactions>

Example: http://api.getglue.com/v2/user/guru?userId=mtab

/user/thingsInCommon

Parameters:

otherUserId - Glue username

Response:

The things the authenticated user and otherUserId have in common.

<objects count="7">
    <music count="3">
            <album>
                    <modelName>music</modelName>
                    <key>music/21st_century_breakdown/green_day</key>
                    <title>21st Century Breakdown</title>
            </album>
            <album>
                    <modelName>music</modelName>
                    <key>music/black_holes_revelations/muse</key>
                    <title>Black Holes and Revelations</title>
            </album>
            <album>
                    <modelName>music</modelName>
                    <key>music/day_age/the_killers</key>
                    <title>Day &amp; Age</title>
            </album>
    </music>
    <topics count="1">
            <topic>
                    <modelName>topics</modelName>
                    <key>topics/p/paris</key>
                    <title>Paris</title>
            </topic>
    </topics>
    <tv_shows count="2">
            <show>
                    <modelName>tv_shows</modelName>
                    <key>tv_shows/weeds</key>
                    <title>Weeds</title>
            </show>
            <show>
                    <modelName>tv_shows</modelName>
                    <key>tv_shows/futurama_benders_game</key>
                    <title>Futurama: Bender's Game</title>
            </show>
    </tv_shows>
    <books count="1">
            <book>
                    <modelName>books</modelName>
                    <key>books/easy_latin_crossword_puzzles/wallace</key>
                    <title>Easy Latin Crossword Puzzles</title>
            </book>
    </books>
</objects>

Example: http://api.getglue.com/v2/user/thingsInCommon?otherUserId=mtab

Object Methods

/object/get

Parameters:

objectId - either the URL of a recognized page or Glue objectKey

Response:

An object's full details.

<show>
    <itemName>show</itemName>
    <title>Weeds</title>
    <visited>38</visited>
    <liked>14</liked>
    <commented>2</commented>
    <link>http://www.netflix.com/Movie/Weeds_Season_4</link>
    <image>http://cdn-7.nflximg.com/us/boxshots/large.jpg</image>
    <url>http://www.netflix.com/Movie/Weeds_Season_4</url>
    <sdb>Netflix</sdb>
    <rank>20</rank>
    <rankChange>12</rankChange>
    <preview>http://www.youtube.com/v/tUZcdiflm_c</preview>
    <shortDescription>{short description}</shortDescription>
    <description>{full description}</description>
    <year>2008</year>
    <starring>
        <starring_item>Mary-Louise Parker</starring_item>
        <starring_item>Elizabeth Perkins</starring_item>
        <starring_item>Albert Brooks</starring_item>
    </starring>
    <similar>
        <similar_item>tv_shows/mad_men</similar_item>
        <similar_item>tv_shows/dead_like_me</similar_item>
        <similar_item>tv_shows/niptuck</similar_item>
    </similar>
    <type>tv_shows</type>
    <objectKey>tv_shows/weeds</objectKey>
</show>

Examples:
http://api.getglue.com/v2/object/get?objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/object/get?objectId=movies/slumdog_millionaire/danny_boyle

/object/users

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
action - (optional) return only one section. Options are: lastCheckedIn, checkedIn, commented, liked, visited
total,page,numItems - (optional) if pagingInfo section is available within an action, these variables can be passed in (should specify action as well)

Response:

Guru record and interactions associated with the object, grouped by type (checkin, comment, like, visit)

<totalActivity>
    <stats>
        <friends>
            <visited>0</visited>
            <liked>0</liked>
        </friends>
        <all>
            <visited>6176</visited>
            <liked>3900</liked>
        </all>
    </stats>
    <guru>
        <interaction>
            <userId>brianandnicole_noriega</userId>
            <displayName>Nicole Brian Davis Noriega</displayName>
            <action>Favorited</action>
            <comment>BEST show in TV HiSToRy!!!!!!!!!!!</comment>
            <source>iPhone</source>
            <timestamp>2010-07-02T13:27:10Z</timestamp>
            <numReplies>3</numReplies>
            <objectKey>tv_shows/weeds</objectKey>
            <fan>2010-07-02T01:47:43Z</fan>
            <superfan>2010-06-27T13:14:00Z</superfan>
            <useful>2</useful>
            <agree>10</agree>
            <numReplies>3</numReplies>
        </interaction>
    </guru>
    <checkinActivity total="10">
        <interaction>
            <userId>yogabbagaby</userId>
            <displayName>Gaby</displayName>
            <action>Checkin</action>
            <source>iPhone</source>
            <timestamp>2010-07-09T18:19:40Z</timestamp>
            <objectKey>tv_shows/weeds</objectKey>
            <numReplies>1</numReplies>
        </interaction>
        ...
    </checkinActivity>
    <commentActivity total="154">
        <pagingInfo>
            <total>10</total>
            <numItems>10</numItems>
            <page>2</page>
        </pagingInfo>
        <interaction>
            <userId>shelbirae</userId>
            <action>Unwanted</action>
            <comment>Weeds is awesome!</comment>
            <source>iPhone</source>
            <timestamp>2010-07-09T15:07:45Z</timestamp>
            <numReplies>1</numReplies>
            <objectKey>tv_shows/weeds</objectKey>
            <numReplies>2</numReplies>
        </interaction>
        ...
    </commentActivity>
    <likeActivity total="3758">
        <interaction>
            <userId>joshua_tauzin</userId>
            <displayName>Joshua Tauzin</displayName>
            <action>Liked</action>
            <source>iPhone</source>
            <timestamp>2010-07-09T17:55:14Z</timestamp>
            <objectKey>tv_shows/weeds</objectKey>
        </interaction>
        ...
    </likeActivity>
    <visitActivity total="1759">
        <interaction>
            <userId>ducktastic</userId>
            <displayName>Derrick Sanskrit KC</displayName>
            <action>Looked</action>
            <source>http://getglue.com/tv_shows/weeds?source=search</source>
            <timestamp>2010-07-09T17:18:07Z</timestamp>
            <objectKey>tv_shows/weeds</objectKey>
        </interaction>
        ...
    </visitActivity>
</totalActivity>

Examples:
http://api.getglue.com/v2/object/users?objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/object/users?objectId=movies/slumdog_millionaire/danny_boyle

/object/links

Parameters:

objectId - either the URL of a recognized page or Glue objectKey

Response:

A list of links associated with the object.

<links>
    <link>http://movies.yahoo.com/movie/1809956055/info</link>
    <link>http://www.amazon.com/Slumdog-Millionaire/dp/B001UEBHYS</link>
    <link>http://www.blockbuster.com/catalog/movieDetails/370506</link>
    <link>http://www.rottentomatoes.com/m/1198041</link>
    ...
</links>

Examples:
http://api.getglue.com/v2/object/links?objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/object/links?objectId=movies/slumdog_millionaire/danny_boyle

/object/replies

Parameters:

objectId - either the URL of a recognized page or Glue objectKey
userId - Glue username of the user who started the reply thread

Response:

Replys (as interactions) to the given user's interaction on the given object

<interactions>
    <interaction>
        <objectKey>movies/iron_man/jon_favreau</objectKey>
        <title>Iron Man</title>
        <userId>miwitza</userId>
        <displayName>Sandra Kravitz</displayName>
        <action>Reply</action>
        <comment>hope that sequel will be great, too. would Jeff be in that one, too? :)</comment>
        <source>ClemmRusty</source>
        <timestamp>2010-02-16T17:07:40Z</timestamp>
        <useful>2</useful>
    </interaction>
    ...
</interactions>

Examples:
http://api.getglue.com/v2/object/replies?userId=mtab&objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/object/replies?userId=mtab&objectId=movies/slumdog_millionaire/danny_boyle

/object/similar

Parameters:

objectId - either the URL of a recognized page or Glue objectKey

Response:

A list of similar objects

<similar>
    <glue>
        <items>
            <item>
            <key>movies/harry_potter_order_of_phoenix/david_yates</key>
            <url>http://www.netflix.com/Movie/70058027</url>
            <title>Harry Potter and the Order of the Phoenix</title>
            <image>http://cdn-7.nflximg.com/us/boxshots/large/70058027.jpg</image>
            <modelName>movies</modelName>
            </item>
            ...
        </items>
    </glue>
</similar>

Examples:
http://api.getglue.com/v2/object/similar?objectId=http://www.amazon.com/dp/B001P9KR8U/
http://api.getglue.com/v2/object/similar?objectId=movies/slumdog_millionaire/danny_boyle

Network-wide Methods

/glue/categories

Response:

Alphabetized list of all supported categories with human-readable name and record types.

<categories>
	<category>
		<name>Books</name>
		<modelName>books</modelName>
	</category>
	<category>
		<name>Electronics</name>
		<modelName>electronics</modelName>
	</category>
	<category>
		<name>Movie Stars</name>
		<modelName>movie_stars</modelName>
	</category>
	...
</categories>

Example: http://api.getglue.com/v2/glue/categories

/glue/popular

Parameters:

category - One of the categories supported by Glue, or all.

Response:

The 100 most popular objects in the given category. (See paging for details on how to request additional items)

<interactions>
    <interaction>
        <rank>1</rank>
        <rankChange>3</rankChange>
        <title>Raiders of the Lost Ark</title>
        <image>http://images.barnesandnoble.com/images/26280000/26281568.JPG</image>
        <objectKey>movies/raiders_of_lost_ark/steven_spielberg</objectKey>
        <link>http://video.barnesandnoble.com/DVD/97361328249/?cds2Pid=16639</link>
        <activity>34</activity>
    </interaction>
    <interaction>
        <rank>2</rank>
        <rankChange>-1</rankChange>
        <title>The Dark Knight</title>
        <image>http://cdn-3.nflximg.com/us/boxshots/large/70079583.jpg</image>
        <objectKey>movies/dark_knight/christopher_nolan</objectKey>
        <link>http://www.netflix.com/Movie/The_Dark_Knight/70079583</link>
        <activity>9</activity>
    </interaction>
	...
</interactions>

Example: http://api.getglue.com/v2/glue/popular?category=books

/glue/topUsers

Parameters:

category - One of the categories supported by Glue, or all.

Response:

The 50 most active users in the given category.

<users>
    <user>
        <rank>1</rank>
        <userId>Joe</userId>
        <activity>34</activity>
    </user>
    <user>
        <rank>2</rank>
        <userId>Bill</userId>
        <activity>27</activity>
    </user>
    ...
<users>

Example: http://api.getglue.com/v2/glue/topUsers?category=books

/glue/findObjects

Parameters:

q - search query

Response:

Objects that matched your search query

<matches count="9">
    <books count="4">
        <book>
            <key>books/batman_dark_knight_returns/frank_miller</key>
            <title>Batman: The Dark Knight Returns</title>
        </book>
        ...
    </books>
    <movies count="4">
        <movie>
            <key>movies/batman_tales_of_dark_knight/boy_kirklan</key>
            <title>Batman: Tales of the Dark Knight</title>
        </movie>
        ...
    </movies>
    <music count="1">
        <album>
            <key>music/dark_knight/hans_zimmer</key>
            <title>The Dark Knight</title>
        </album>
    </music>
</matches>

Example: http://api.getglue.com/v2/glue/findObjects?q=dark knight

/glue/findUsers

Parameters:

userId - partial username or email to search for

Response:

The usernames that match your search query

<users>
    <user>
        <userId>Joe</userId>
    </user>
    <user>
        <userId>Bill</userId>
    </user>
    ...
<users>

Example: http://api.getglue.com/v2/glue/findUsers?userId=joe

Paging

All methods that return interactions can be paged through.

To enable paging, pass page=1 and numItems={pageSize} with your first request. Along with the rest of your response you will also recieve paging information that can be used in subsequent requests:

<pagingInfo>
    <nextToken>2009-10-16T02:46:37Z</nextToken>
    <total>175</total>
    <numItems>20</numItems>
    <page>2</page>
</pagingInfo>

To request the next page, pass page=2 and numItems={pageSize} and nextToken={nextToken from pagingInfo}. Continue this way until numItems * page is >= total which indicates you have reached the last page. Requesting further pages will return an empty set of interactions.

API Response Format

The full XML response format is as follows:

<adaptiveblue>
    <request>
        <method>/user/profile</method>
        <params>
            <paramName1>paramValue1</paramName1>
            <paramName2>paramValue2</paramName2>
            ...
        </params>
    </request>
    <response>
        (Response XML)
        <timestamp>yyyy-mm-ddThh:mm:ssZ</timestamp>
    </response>
</adaptiveblue>

All responses in the following documentation are substituted for (Response XML). Timestamps are returned in UTC and are ISO 8601 formatted.

In the case of an expected error, <response> is replaced by:

<error>
    <code>###</code>
    <name>ShortName</name>
    <message>Human readable message</message>
</error>

For example:

<error>
    <code>101</code>
    <name>MissingParameter</name>
    <message>userId is missing</message>
</error>

Additionally, the applicable HTTP status code will be sent with each error document. In the case of an unexpected internal error, an HTTP 500 status code will be sent with a blank document. For a complete list of expected errors and return codes, please see the error documentation.

Interaction Format

The commonly returned fields of an interaction include the title, action, userId, displayName, objectKey, interaction source, and timestamp

title - The title of the object
action - One of the following: Checkin, Comment, LikedComment, Liked, Favorited, Disliked, Saved, Unwanted, Looked, or Reply
userId - The userId associated with the interaction
displayName - The display name of the userId associated with the interaction
objectKey - The unique identifier of the object. Can be used as a value for objectId parameters
source - URL (or userId, in the case of replies) of the source
timestamp - The timestamp when the interaction occurred

<interaction>
	<title>(Object Title)</title>
	<image>(Object Image URL)</image>
	<action>(Interaction)</action>
	<userId>(User ID)</userId>
	<displayName>(Display Name)</displayName>
	<objectKey>(Object Identifier)</objectKey>
	<source>(Interaction Source URL/User)</source>
	<timestamp>(Interaction Timestamp)</timestamp>
</interaction>

Optional additional fields include stats on replies and votes

numReplies - Number of replies to the interaction
agree - Number of "agree" votes
useful - Number of "useful" votes
funny - Number of "funny" votes

Glue API Errors

In the case that the Glue API encounters one of a list of expected errors, it will set the applicable HTTP status code and return an error document. In the case that an unexpected error occurs, an HTTP 500 will be sent with a blank document.

Error documents are in the following form:

<adaptiveblue>
	<request>
    	<method>methodName</method>
    	<params>
        	<paramName1>paramValue1</paramName1>
        	<paramName2>paramValue2</paramName2>
        	...
    	</params>
	</request>
	<error>
		<code>###</code>
		<name>ShortName</name>
		<message>Human-readable message</message>
	</error>
</adaptiveblue>

Missing Input

MissingParameter

A parameter required by the method was left unset or blank.

Code - 101
HTTP Status - 400 (Bad Request)

Authentication

AuthenticationFailed

The user's authentication credentials are incorrect.

Code - 201
HTTP Status - 401 (Unauthorized)

PermissionError

The authenticated user does not have permission to access the requested resource (i.e. a protected user's interactions).

Code - 202
HTTP Status - 401 (Unauthorized)

Invalid Input

InvalidURL

The URL provided as an objectId is invalid.

Code - 301
HTTP Status - 400 (Bad Request)

InvalidObject

The objectKey provided as an objectId is invalid or could not be found.

Code - 302
HTTP Status - 400 (Bad Request)

InvalidInteraction

The interaction requested could not be found.

Code - 303
HTTP Status - 400 (Bad Request)

InvalidUser

The userId provided is invalid.

Code - 304
HTTP Status - 400 (Bad Request)

OAuth Errors

The following errors may be returned when using OAuth to access the API. They will be returned in the standard format for OAuth. Note that this is different than the Glue API error format. These errors are only used to indicate a problem with the OAuth transaction. Any other errors will be returned in the API format.

consumer_key_unknown - The developer key used in the request is unknown.
parameter_absent - A required OAuth parameter for the request (such as oauth_token) is missing.
permission_denied - The request token has been denied permission by the user.
permission_unknown - The request token has not been allowed or denied by the user.
token_rejected - The request or access token is unknown or invalid.


	Glue works with Firefox or Internet Explorer Download Firefox Download Internet Explorer

Glue API

Terms of Service

Table of Contents

Authentication

OAuth 1.0 (recommended)

Token-based (deprecated)

API Paths

Object IDs

Check-in Methods

User Methods

/user/login (deprecated)

Object Methods

Network-wide Methods

Paging

API Response Format

Interaction Format

Glue API Errors

Missing Input

MissingParameter

Authentication

AuthenticationFailed

PermissionError

Invalid Input

InvalidURL

InvalidObject

InvalidInteraction

InvalidUser

OAuth Errors