API Docs
Introduction

The GraphMuse API is a RESTful API that returns JSON. To protect your users' privacy, please use the secure HTTPS protocol.

Queries only support the GET method and do not require any additional Facebook permissions unless otherwise stated. With such queries, the only data that GraphMuse analyzes is the friend graph, which is a basic permission available to any site or app using Facebook Login.

To test the API queries below, you can use access tokens from Facebook's Graph API Explorer.

API Queries
1. Sorted Friends

Returns:

The user's friends, sorted by how likely the user is to invite them to a given app.

Sample query:

https://api.graphmuse.com/sortedfriends?access_token=ACCESS_TOKEN

Sample response:

{
    "friends": [
        {"id": "165492370", "name": "Tony Diepenbrock"},
        {"id": "61340477", "name": "Charles Moyes"},
        {"id": "14963279", "name": "Ryan Shea"}
    ],
    "friend_count": 648,
    "runtime": "0.563072919846"
}
view parameters
Parameter
Range
Description
access_token
Facebook access token.
limit (optional)
integer >= 1
The max number of friends to include in the response.
2. Friend Groups

Returns:

The various groups of friends in the user's life, or sets of friends in which each member is friends with a high percentage of the other members.

Each group has a "connectedness" score that is equivalent to (friendships within the group)/(possible friendships within the group). As an example, a sorority friend group in which every girl is Facebook friends with every other girl in the sorority would have a "connectedness" score of 1.0/1.0. In contrast, a friend group that represents a user's high school is likely to be less connected and may have a "connectedness" score of 0.65/1.0.

Sample query:

https://api.graphmuse.com/friendgroups?access_token=ACCESS_TOKEN

Sample response:

{
    "groups": [{
        "connectedness": "1.0",
        "members": [
            {"name": "Tony Diepenbrock", "id": "165492370"},
            {"name": "Charles Moyes", "id": "61340477"},
            {"name": "Ryan Shea", "id": "14963279"}
        ]
    }],
    "runtime": "0.71547698975"
}
view parameters
Parameter
Range
Description
access_token
Facebook access token.
3. Collective Interests

Returns:

The user's friend groups plus the pages each of those groups have liked on Facebook in highest frequency.

The "Collective Interests" query can be used to determine a given group's affinity to sites, music artists, or products. If one of the interests appears in high enough frequency (i.e. 27/50 friends in a group "like" the University of Pennsylvania), this can indicate the identity of the friend group.

Facebook Permissions:

user_likes and friends_likes

Sample request:

https://api.graphmuse.com/friendgroups?fields=likes
                                      &access_token=ACCESS_TOKEN

Sample response:

{
    "groups": [{
        "connectedness": "0.833333",
        "likes": [
            ["University of Pennsylvania", 5],
            ["Jay-Z", 4],
            ["Princeton University", 2]
        ],
        "members": [
            {"name": "Tony Diepenbrock", "id": "165492370"},
            {"name": "Charles Moyes", "id": "61340477"},
            {"name": "Ryan Shea", "id": "14963279"}
            {"name": "Justin Meltzer", "id": "69195361"},
            {"name": "Dan Shipper", "id": "62177992"},
            {"name": "Patrick Leahy", "id": "74910072"}
        ]
    }],
    "runtime": "0.71547698975"
}
view parameters
Parameter
Range
Description
access_token
Facebook access token.
4. Family

Returns:

The user's family members--even those with different last names.

While the user_relationships Facebook permission can be used to identify the family members that the user lists on Facebook, it is usually the case that few, if any, family members are listed.

Sample request:

https://api.graphmuse.com/family?access_token=ACCESS_TOKEN

Sample response:

{
    "family": [
        {"name": "John Diepenbrock", "id": "121744"},
        {"name": "Thomas Diepenbrock", "id": "3240228"},
        {"name": "Tony Diepenbrock", "id": "3410580"},
        {"name": "Tim Draeger", "id": "59906782"},
        {"name": "Mark Draeger", "id": "3320509"},
        {"name": "Greg Johnson", "id": "59232727"}
    ]
}
view parameters
Parameter
Range
Description
access_token
Facebook access token.
Errors
1
NotFoundError
2
MethodNotAllowedError
3
InvalidParametersError
4
MissingAccessTokenError
5
FacebookAPIError
6
AccessTokenPermissionsError
7
SubscriberStatusError
8
DataProcessingError
0
InternalServerError