SocDir (Social Directory Web Service) - EOL date is March 2nd, 2020
What is the Social Directory API and what does it currently provide?
The Social Directory API provides profile (identity) 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 and photo. The Social Directory API contains URIs to obtain different sets of data from a user's profile.
Request:
GET https://social.yahooapis.com/v1/user/abcdef123/profile?format=json
Authorization: Bearer <Bearer Token>
Response:
{
profile: {
guid: "DKZCPIB7ZJZTWRC5A3W4Y5N3M4",
addresses: [
{
city: "",
country: "US",
current: true,
id: 1,
postalCode: "",
state: "",
street: "",
type: "HOME"
},
{
city: "",
country: "US",
current: true,
id: 2,
postalCode: "",
state: "",
street: "",
type: "WORK"
}
],
ageCategory: "A",
birthYear: "XXXX",
birthdate: "XX/XX",
created: "2019-04-30T20:48:14Z",
displayAge: "XX",
emails: [
{
handle: "jasonsmith@gmail.com",
id: 10,
type: "HOME"
},
{
handle: "jasonsmith@yahoo.com",
id: 1,
primary: true,
type: "HOME"
}
],
familyName: "Smith",
gender: "M",
givenName: "Jason",
image: {
height: 192,
imageUrl: "https://ct.yimg.com/cy/1768/39361574426_98028a_192sq.jpg",
size: "192x192",
width: 192
},
intl: "us",
jurisdiction: "us",
lang: "en-US",
memberSince: "2014-12-18T04:36:14Z",
migrationSource: 1,
nickname: "Jason",
notStored: true,
nux: "0",
phones: [
{
id: 10,
number: "1-610XXXXXXX",
type: "MOBILE",
verified: true
}
],
profileMode: "PUBLIC",
profileStatus: "ACTIVE",
profileUrl: "http://profile.yahoo.com/DKZCPIB7ZJZTWRC5A3W4Y5N3M4",
timeZone: "America/Los_Angeles",
isConnected: false,
profileHidden: false,
profilePermission: "PRIVATE",
uri: "https://social.yahooapis.com/v1/user/DKZCPIB7ZJZTWRC5A3W4Y5N3M4/profile",
cache: true
}
}
This Legacy Profile API supported both OAUTH 1.0 and OAUTH2.0 Tokens. It also had both JSON and XML mode.
What is this new service you speak of?
UserInfo Endpoint: https://api.login.yahoo.com/openid/v1/userinfo
The new service is the UserInfo Endpoint which is OAuth 2.0 protected. To obtain profile information about the user, you can use the access token (which your application receives via the OAuth2.0 authentication).
To determine the scope of information the client must include the “openid profile scope” in your authentication request.
Different scopes supported:
- 1) sdps-r (basic profile read)
- 2) sdpp-r (extended profile read)
- 3) profile
Request:
GET https://api.login.yahoo.com/openid/v1/userinfo
Authorization: Bearer <Bearer Token>
Response:
{
sub: "JEF4XR2CT55JPVEBVD7ZVT6A3A",
name: "Jasmine Smith",
given_name: "Jasmine",
family_name: "Smith",
locale: "en-US",
email: "yqa_functest_15572415322065371@yahoo.com",
email_verified: true,
birthdate: "1972",
profile_images: {
image32: "https://ct.yimg.com/cy/1768/39361574426_98028a_32sq.jpg",
image64: "https://ct.yimg.com/cy/1768/39361574426_98028a_64sq.jpg",
image128: "https://ct.yimg.com/cy/1768/39361574426_98028a_128sq.jpg",
image192: "https://ct.yimg.com/cy/1768/39361574426_98028a_192sq.jpg"
},
preferred_username: "yqa_functest_15572415322065371@yahoo.com",
phone_number: "+18663395023",
nickname: "Jasmine",
picture: "https://ct.yimg.com/cy/1768/39361574426_98028a_192sq.jpg"
}
This new OpenId Connect UserInfo API supports only OAUTH2.0 Tokens. This API is not backward compatible to the legacy API. It supports only JSON format in response.
Different Profile Attributes returned for different scopes:
Scope |
Attribute |
Attribute Details |
sdps-r (basic profile read)
|
sub |
SubjectId (User’s Unique Identifier) |
name |
User’s full name |
|
given_name |
User’s first name |
|
family_name |
User’s family name |
|
locale |
User’s language |
|
sdpp-r (extended profile read) |
sub |
SubjectId (User’s Unique Identifier) |
name |
User’s full name |
|
given_name |
User’s first name |
|
family_name |
User’s family name |
|
locale |
User’s language |
|
|
User’s preferred email |
|
email_verified |
Is the User’s email verified by user |
|
birthdate |
Birth Year of User |
|
profile_images |
Contains URIs for the profile images of the user. ( image32*32, image64*64, image128*128, image192*192) |
|
picture |
Contains URI for the profile image of user (192*192) |
|
preferred_username |
Preferred username of the User |
|
phone_number |
User’s Phone number |
|
nickname |
User’s nickname |
|
profile |
sub |
SubjectId (User’s Unique Identifier) |
name |
User’s full name |
|
given_name |
User’s first name |
|
family_name |
User’s family name |
|
locale |
User’s language |
|
nickname |
User’s nickname |
|
gender |
User’s gender |
|
middle_name |
User’s middle name |
|
profile_images |
Contains URIs for the profile images of the user. ( image32*32, image64*64, image128*128, image192*192) |
|
|
|
User’s preferred email |
email_verified |
Is the User’s email verified by user |
Compatibility between previous Social Directory profile api attributes and new User Info attributes?
Social Directory Profile Attribute |
New User Info Attribute |
Attribute Description |
guid |
sub |
User’s Unique Identifier |
givenName |
given_name |
User’s first name |
familyName |
family_name |
User’s family name |
lang |
locale |
User’s language |
emails (Array of user’s emails) |
|
User’s preferred email. (An array of emails is replaced with one preferred email of the user) |
birthYear |
birthdate |
Birth Year of User |
image |
profile_images |
New attribute contains the image32, image64, image128, image192 profile image url. |
picture |
Contains URI for the profile image of user (192*192) |
|
nickname |
nickname |
User’s nickname |
phones |
phone_number |
User’s phone number. (An array of phones is replaced with one preferred phone number of the user) |
gender |
gender |
User’s gender |
List Of Attributes Deprecated in Social Directory Profile Api
- 1) addresses
- 2) ageCategory
- 3) birthdate
- 4) cache
- 5) displayAge
- 6) intl
- 7) isConnected
- 8) jurisdiction
- 9) memberSince
- 10) notStored
- 11) nux
- 12) profileUrl
- 13) profileMode
- 14) profileStatus
- 15) profileHidden
- 16) profilePermission
- 17) timeZone
- 18) uri
NOTE: Profile Info response in XML format is deprecated.
List Of Attributes added to New User Info Endpoint
- 1) name
- 2) email_verified
- 3) preferred_username
Where can I get all of the documentation?
How to create an app?
https://developer.yahoo.com/apps/create/
Yahoo Oauth 2.0 Documentation:
https://developer.yahoo.com/oauth2/guide/
Yahoo OpenId Connect Documentation:
https://developer.yahoo.com/oauth2/guide/openid_connect/
The OpenId discovery document:
https://api. login.yahoo.com /.well-known/openid-configuration