Social Graph API

Social Graph API Documentation

The Google Social Graph API lets you access the public relations declared on the Internet, from formats such as XFN and FOAF.

Audience
Usage policy
Introduction
URL format
Request Parameters
Response Structure

Audience

This document is intended for programmers who want to access the global, public social graph either from a webpage or from a server. It provides an introduction to using the API and reference material on the available parameters.

Usage Policy

Use of the Social Graph API is subject to a query limit of 50,000 queries per user per day. If you go over this 24-hour limit, the Social Graph API may stop working for you temporarily. If you continue to exceed this limit, your access to the Social Graph API may be blocked. Please contact us (see the FAQ) if you would like this limit raised for your application.

Introduction

The Google Social Graph API returns a JSON data stucture in response to a URL. You may optionally request a JSONP callback, to use the data inside a client-side JavaScript application. Otherwise, JSON parsers are available for most languages. Depending on a series of options, you may request different types of information from the social graph.

URL format

Google Social Graph API URLs must be in the following format:

http://socialgraph.apis.google.com/lookup?<parameter 1>&<parameter 2>&<parameter n>

Parameters

The follow is a summary of the available parameters:

Parameter	Type	Short Description
`q`	Comma-separated list of URIs.	Which node(s) in the social graph to query. More...
`edo`	boolean	Return edges out from returned nodes. More...
`edi`	boolean	Return edges in to returned nodes. More...
`fme`	boolean	Follow me links, also returning reachable nodes. More...
`pretty`	boolean	Pretty-print returned JSON. More...
`callback`	String matching `/^[\w\.]+$/`	JSONP callback function. More...
`sgn`	boolean	Return internal representation of nodes. More...

Pretty-printing the output

To get started, the boolean pretty parameter enables pretty-printing of the JSON response. It will keep you sane while you're experimenting with the API.

Try opening this URL:

http://socialgraph.apis.google.com/lookup?pretty=1

What you'll see is the basic structure of all responses:

{
 "canonical_mapping": {
 },
 "nodes": {
 }
}

The first dictionary, canonical_mapping is a mapping of the things you asked for (in this case, nothing) to their canonical versions. The canonical version is important, as it's the key into the second dictionary, nodes. The nodes dictionary contains objects (dictionaries) for each node that was loaded. In this case, however, no data was requested so it is empty.

Specifying a callback function

If you intend to use this API from JavaScript inside a browser, you'll need to use the callback parameter, specifying a callback function to run with the response object.

Example:

http://socialgraph.apis.google.com/lookup?pretty=1&callback=foo

Which results in:

foo({
 "canonical_mapping": {
 },
 "nodes": {
 }
});

Querying Node(s)

The q parameter is a comma-separated list of nodes you'd like to load.

Example Value	Meaning
`http://example.com/`	Look up the node `http://example.com/`
`example.COM`	Look up the node `http://example.com/`
`mailto:daveman692@example.com`	Look up the node representing the email address node in the graph. Note that not much email address data is available via this API, because there aren't that many public email addresses on the web.
`daveman692@example.com`	(same)
`foo.com,bar.com`	Look up both the nodes `http://foo.com/` and `http://bar.com/`. The limit is currently 50 nodes, but may change in the future. You'll know when you hit the limit because the key in the `canonical_mapping` result data structure won't contain all the nodes you requested.
`sgn://example.com/?ident=bob`	You may also query using not just `mailto` and `http` URLs, but also the Social Graph API's internal, canonicalized representation of `sgn` URLs for known sites. While you can treat these identifiers as opaque, the google-sgnodemapper project is an Open Source library to convert to and from these canonicalized URLs if you're interested.

Following me links

If you set the boolean fme parameter to 1 (or true), you signal that you're interested in loading not just the nodes represented in your q parameter, but also any nodes declared as "me" from the nodes you did request, recursively.

For example, imagine the following graph:

A ---> B ---> C
   me    me

... and your q parameter were A, and you set fme to true, all of A, B, and C will be returned.

Note, however, that nodes B and C will not show up in the response's canonical_mapping structure, as that's only for your q parameters. To find the keys in the response structure for B and C, you need to look at the value of A's claimed_nodes, which is an array of all nodes which are reachable by following only the directed me edges. In this case, you would see a response of:

{
 "canonical_mapping": {
  "A": "a"
 },
 "nodes": {
  "a": {
   "attributes": {},
   "claimed_nodes": [ "b", "c" ]
  },
  "b": {
   "attributes": {},
   "claimed_nodes": [ "c" ]
  },
  "c": {
   "attributes": {},
   "claimed_nodes": []
  }
 }
}

Requesting Edges

The boolean edo parameter requests directed edges "out" (or originating) from each returned node and causes the nodes_referenced dictionary to be returned. For instance, for edges of type friend, these would be all the people who the node(s) declares as a public friend.

The boolean edi parameter requests directed edges "in" (arriving at) each returned node, and causes the nodes_referenced_by dictionary to be returned. For instance, for edges of type friend, these would be all the people who declare the node(s) as a public friend (often called "followers" or "fans").

Of course, all edges aren't of type friend. See the documentation on edge types for more information.

To demonstrate the edo and edi parameters, imagine the following graph:

A --------> B ---------> C
   friend     sibling 
              co-resident

If you did a query of q=A,B,C&edo=1&edi=1&pretty=1, you'd receive the following response:

{
 "canonical_mapping": {
  "A": "a"
  "B": "b"
  "C": "c"
 },
 "nodes": {
  "a": {
   "attributes": {},
   "nodes_referenced": {
    "b": {
     "types": [ "friend" ]
    }
   },
   "nodes_referenced_by": {
   },
  },
  "b": {
   "attributes": {},
   "nodes_referenced": {
    "c": {
     "types": [ "co-resident", "sibling" ]
    }
   },
   "nodes_referenced_by": {
    "a": {
     "types": [ "friend" ]
    }
   },
  },
  "c": {
   "attributes": {},
   "nodes_referenced": {
   },
   "nodes_referenced_by": {
    "b": {
     "types": [ "co-resident", "sibling" ]
    }
   },
  }
 }
}

Notice how the b node has populated dictionaries for both outgoing and incoming edges. From this response, you can learn the following:

A declares B as a friend, but it's not reciprocal. You could say A is a "fan" of B, or A "follows" B, but not "A and B are friends"
Likewise, B declares that C is his/her sibling and co-resident, but it's not reciprocal.

Response Structure

The JSON response format, ignoring the optional callback, is structurally as follows:

JSON Response dictionary, containing properties:
- canonical_mapping: an dictionary (Object) mapping explicitly requested nodes (from the q parameter) to canonicalized URLs which also serve as the necessary lookup key into the response's nodes dictionary.
- nodes: a dictionary from canonical URL to node objects. Note that this dictionary will contain both nodes requested explicitly with the query parameter, as well as nodes loaded implicitly as a result of following me edges when requested with the fme parameter. The implicitly loaded nodes are also keyed by their canonical URL, but you won't know their canonical URLs until you look at the explicitly requested nodes. Each returned node may have the following properties:
  - attributes: a dictionary of node attributes.
  - claimed_nodes: an array of URLs that this node claims to own, recursively. This is the set of nodes reachable via me edges, starting with this node. See the description of the fme parameter above. Note that this list of claimed URLs does not represent a strongly connected graph. If you need to compute the strongly connected subset, you need to look at all the claimed nodes' claimed_nodes properties as well. This property is only returned when fme is set.
  - unverified_claiming_nodes: an array of URLs that claim this node, but which are not in claimed_nodes. That is, it's the set of URLs with an inbound me edge, minus the set of URLs in claimed_nodes. You should lend no confidence to the information in this field. These people may be spammers, imposters, etc. This field is only returned as a convenience in hopes that a human might recognize one of their own accounts which they just haven't linked into their real graph. This field is only returned when all three of edo, edi, and fme are set.
  - nodes_referenced: when edo is set, this returns the nodes which node links to. The value is another object, keyed on canonicalized URL:
    - types: an array of edge types for this outbound edge
  - nodes_referenced_by: when edi is set, this returns the nodes which links to this node. The value is another object, keyed on canonicalized URL:
    - types: an array of edge types for this inbound edge

You might find it helpful to explore the example apps at left, especially the Parameter Playground to help you see the responses in action.