<< Back to Twitter API Documentation

friendships/show

Returns detailed information about the relationship between two users.

method status | report a bug

URL:

http://api.twitter.com/1/friendships/show.format

Formats: 

xml, json

HTTP Method(s):

GET

Requires Authentication (about authentication):

false (see usage notes)

API rate limited (about rate limiting):

true

Parameters:

One of the following is required if the request is unauthenticated:

• source_id. The user_id of the subject user.
  • Example: http://api.twitter.com/1/friendships/show.xml?source_id=123
• source_screen_name. The screen_name of the subject user.
  • Example:http://api.twitter.com/1/friendships/show.xml?source_screen_name=bob

One of the following is required:

• target_id. The user_id of the target user.
  • Example: http://api.twitter.com/1/friendships/show.xml?target_id=456
• target_screen_name. The screen_name of the target user.
  • Example: http://api.twitter.com/1/friendships/show.xml?target_screen_name=jack

Usage Notes:

• If this method is invoked as an authenticated request, the method will use the authenticated user as the source user implicitly. However, a source explicitly specified with parameters will override an authenticated user as the source of the relationship query.
• If the source is not specified for an unauthenticated request, the method will return an HTTP 403.
• If a source or target is specified but does not exist, the method will return an HTTP 404.
• <notifications_enabled> details whether the source user is receiving device notifications regarding status updates of the target user. Due to its private nature, the <notifications_enabled> element will only be populated for an authenticated source user within the <source> element. For unauthenticated source users and target users, the <notifications_enabled> element will be empty.
• <blocking> details whether the source user is blocking the target user.  Due to its private nature, the <blocking> element will only be populated for an authenticated source user within the <source> element.  For unauthenticated source users and target users, the <blocking> element will be empty.
• This method returns redundant data, in that the bi-directional relationship of the source and target can be determined by looking at the <following> and <followed_by> element within either the <source> or <target> nodes. We deliver this data twice in denormalized form for convenience and increased readability.

Response (about return values): 

          XML example:

<?xml version="1.0" encoding="UTF-8"?>

<relationship>

<source>

<id>123</id>

<screen_name>bob</screen_name>

<following>true</following>

<followed_by>false</followed_by>

<notifications_enabled>false</notifications_enabled>

</source>

<target>

<id>456</id>

<screen_name>jack</screen_name>

<following>false</following>

<followed_by>true</followed_by>

<notifications_enabled></notifications_enabled>

</target>

</relationship>

          JSON example:

{"relationship": {

"source": {

"id": 123,

"screen_name": "bob",

"following": true,

"followed_by": false,

"notifications_enabled": false },

"target": {

"id": 456,

"screen_name": "jack",

"following": false,

"followed_by": true,

"notifications_enabled": null }

}

}

Usage examples: 

cURL (about cURL):

curl -u user:password http://api.twitter.com/1/friendships/show.xml?target_id=456

          Do you have an example to share in the language of your choice? Please share!

<< Back to Twitter API Documentation