Chapter 2. Social Directory API

Introduction to Social Directory API

The Social Directory API provides profile (identity) and connection (relationship) information about Yahoo users. A profile is a collection of user provided information that is descriptive of the user, such as the user's name, gender, location, photo, and relationship status. The connections of a user identify other users who might be friends and business associates. To form a connection, both users must confirm the relationship. For example, if Joe wants to add Jane to his list of connections, he asks that she be added and she has to approve. The benefits of connecting include more information sharing between users on Yahoo properties as well as on 3rd-party sites and applications.


Certain information will be displayed only if certain permissions have been met in the form of a documented relationship between the viewer and the profile owner. In addition, the profile owner decides what user information will be made publicly available, shared to connections and 3rd party applications, or shared only to connections.

The Social Directory API contains URIs to obtain different sets of data from a user's profile. The following types of cards are distinguished by the packages of data exposed.


Tinyusercards contain only minimal profile data. Use the Tinyusercard Profile URI to get a profile owner's Tinyusercard profile.


Usercards contain the user's Core Profile information. Use the Usercard Profile URI to get a profile owner's Usercard profile.

Extended User Cards

Extended Usercards are Core Usercards that pull in Profile data or contain permissioned information that requires a relationship lookup. Use the Profile URI to get a profile owner's profile.


A user's connections are a subset of their contacts. Connections are two-way, signifying that both users have confirmed their desire to be mutually connected in order to share a potentially higher degree of information between each other. Although the Connections API provides access to these confirmed associations, connections can only be created by Yahoo users.

Getting access to your connections is key to effectively using the Social Platform APIs. In particular, the Connections API provides you with the endpoints to find your connections' usercards or tinyusercards. This in turn provides you with their GUID and URI, information which you can subsequently use to develop a rich social network.


The Connections API is being deprecated. To access connections, use the Relationships API, which provides access ti one-way (contacts) and two-way (connections) relationships. For more information, see Relationships.

Matrix Parameters for the Social Directory API

Matrix parameters enable the application to retrieve part of a collection when calling an HTTP GET operation. A matrix parameter can follow any collection path segment in a URI. For more details about how to use the matrix parameters, refer to Paging a Collection.

The table below lists the matrix parameters with their corresponding data types.

Table 2.1. 

Parameter Data Description
start integer The first item in the collection to be returned by GET. The default is 0.
count integer The number of items in the collection to be returned by GET. The default is 10.

The example below uses the matrix parameters start and count to return the first twenty connections of a user. Note that a matrix parameter is preceded by a semicolon.;start=0;count=20

In the Social Directory API, you can also assign the matrix parameter count with the value of the constant max. The constant max is the largest possible number of elements from a collection that can be returned by the specified Social Directory API.

This example returns the maximum number of connections possible from the Connections API.;count=max

Table of Contents