">mixi Developer Center (mDC)

mixi Connect

mixi Connect (English) » mixi Graph API » Technical Specification » People API

People API

The most important information in socialization is a social graph. People API enables you to obtain information on a user and who the user is connected to. A client program can develop social applications based on a list of friends obtained with the People API. Using this API will be essential for many services.

This section describes how to use the People API to obtain the profile information and a list of friends of the user.

Tips to using People API

There are a few items you need to keep in mind when using People API. We would appreciate if you could keep this in mind and develop applications according to the guidelines provided below.

Profile Picture

People API allows you to extract information from a user's profile. One of the types of information you can extract is the URL for the user's profile picture, specifically the thumbnailUrl. There are two types of profile pictures. The two types are explained in the following chart.

Type  Details
Pictures for friends Pictures that only friends can see
Public photos Public pictures that all users will have access to

The approved user or friends of the approved user are the only people that can extract information from People API. Also in this case the URL of "the pictures in which only friends can see" can be extracted from People API without setting the thumbnailPrivacy parameter. Especially for friends, the "pictures in which only friends can see" can always be extracted. Mixi internal systems have settings and controls in place to prohibit unauthorized 3rd party access to confidential photos. These strict guidelines will apply to applications providers that use the Mixi Graph API, therefore please read and agree to the following.

"pictures in which only friends can see" can never reach the hands of a unauthorized 3rd party even if the user grants approval to do so.
http://developer.mixi.co.jp/connect/term/guideline_of_mixi_connect

On the other hand, if the authorized user changes the thumbnailPrivacy parameter to "everyone" for "pictures that have the option of being shared to the general public", the picture can be extracted using the thumbnailURL. For details regarding the "pictures that have the option of being shared to the general public", please refer to the following guideline.

"Pictures that have the option of being shared to the general public" can be viewed by unauthorized third parties if the user approves.
http://developer.mixi.co.jp/connect/term/guideline_of_mixi_connect

Please use the People API after accepting the guideline terms and conditions above.

Profile page URL

The People API was designed so that only the authorized users or the user's friends can be managed. For the same reasons, the URL for the profile page as provided by the People API was previously only viewable if the logged-in user and the target user were friends. However, in order to support creating new friendships with people who have same interests, Mixi now allows accessing the profileUrl by users even if not friends.

Please follow the guidelines provided below when handling retrieved data. According to the guidelines it is prohibited to use a 3rd party user's information extracted without the user's consent.

Supplemental items on handing and using information extracted.
http://developer.mixi.co.jp/connect/term/guideline_of_mixi_connect/codicil_of_term_1

Note that the provided URL is for PC. When accessing with mobile devices (feature phones) change the URL to "http://m.mixi.jp/".

Items required in advance

To use People API, please have these items prepared beforehand.

  • "r_profile" scope approved access token.

? You cannot access the People API using any other scope approved access token. For instructions on how to get the access token, please refer to the corresponding pages in the authorization manual.

Extracting the list of friends

To extract a list of friends belonging to a certain user, please access the client program "https://api.mixi-platform.com/2/people." The URL will resemble the following.

GET https://api.mixi-platform.com/2/people/[User-ID]/[Group-ID]
Parameter name Value to specify
User-ID ID of the target user or @me
Group-ID ID of the target group, @self, or @friends

A list of friends is private information of a user. Therefore, in User-ID, you can specify only @me or the ID of the user that authorized the access token. In Group-ID, you must specify the ID to identify a group of the target users. You can specify the following IDs. You can obtain a group ID using the Groups API.

ID Description
@self Profile information of the user themselves identified with User-ID
@friends List of profile information of the users who are registered as friends by the user identified with User-ID
Group ID List of profile information of the users who belong to a group registered by the user identified with User-ID

The People API supports the following query parameters.

Parameter name Description
sortBy You can sort the results by nickname by specifying "displayName" as the parameter value.
You can sort the results by log in status by specifying "lastLogin" as the parameter value.
If you omit this parameter, the results are sorted by member_id of the users.
sortOrder The results are sorted in ascending or descending order when you specify "ascending" or "descending" as this parameter value, respectively. If you omit this parameter, the results are sorted in ascending order.
thumbnailPrivacy If the parameter "everyone" is selected then the thumbnailUrl will be a URL for everyone. If "friends" is selected, then the thumbnailURL will be for friends. If this parameter is omitted then the thumbnailUrl will automatically be for friends. Also, this parameter will only function if the User-ID is a user ID approved by the access token or set as "@me" and if the Group-ID is set to "@self".
thumbnailUrlScheme If the parameter is "https", the thumbnailUrl's URL scheme will be https. And, the thumbnailUrl's URL scheme will be http when it's "http".
When you omit this parameter and you request a URL that is http scheme, the thumbnailUrl will be http. On the other hand, if it's https request, it will be https.

When the information is successfully obtained, it is passed as the response parameter in the values argument of the onComplete method in the callback. You can obtain the following result in the JSON format by referencing it with values.getString("response").

{
  "entry" : [
    {
      "id" : "qgjw87yg3djw",
      "displayName" : "bert",
      "thumbnailUrl" : "http://img.mixi.net/img/basic/common/noimage_member180.gif",
      "thumbnailDetails" : [
        {
          "url" : "http://profile.img.mixi.net/photo/member/67/89/123456789_1234567890.jpg",
          "width" : "180",
          "height" : "180",
          "size" : "l"
        },
        {
          "url" : "http://profile.img.mixi.net/photo/member/67/89/123456789_1234567890m.jpg",
          "width" : "76",
          "height" : "76",
          "size" : "s"
        },
        {
          "url" : "http://profile.img.mixi.net/photo/member/67/89/123456789_1234567890s.jpg",
          "width" : "40",
          "height" : "40",
          "size" : "m"
        }
      ],
      "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
    },
    ・・・
  ],
  ・・・
};

The following is a list of each entry

Attribute name details
id User ID
displayName User nickname
thumbnailUrl URL of the user's profile picture
thumbnailDetails Array of the user's profile picture details in 3 sizes (large, small, mini)
* Only returned when specified in “fields”
profileUrl URL of the user's profile page

The thumbnailDetails field is an array containing the following attributes.

Attribute name Details
size The size type of the thumbnail image
Either "l" (large, up to 180px), "s" (small, up to 76px), or "m" (mini, up to 40px)
url URL of the profile picture thumbnail
width Thumbnail width (in pixels)
height Thumbnail height (in pixels)
isDefault When no profile picture is available, true is returned. In this case the returned thumbnail is a default image.

For the client program, the fields parameter allows a developer to control what information category is extracted. If the fields parameter is omitted then all of the categories are included in the results. When categories are separated by a comma in the field parameter, the items need to be set in a query parameter as shown below.

GET https://api.mixi-platform.com/2/people/@me/@friends?fields=thumbnailUrl%2CprofileUrl

The id and displayName will always be included in the results even if the fields parameter is set.

Extracting a status update

If you have an access token for the "r_profile_status" scope, input "status" in the fields parameter to get a status update on the user.

For example the following type of request will be returned.

GET https://api.mixi-platform.com/2/people/@me/@friends?fields=status

Consequently, the following response will be returned.

{
    "entry":[
        {
            "status":{
                "postedTime":"2011-02-02T12:21:37+09:00",
                "text":"I am in Harajuku now"
            },
            "id":"fq7qstgzss9dd",
            "displayName":"Ayako"
        },
        {
            "status": null,
            "id":"ipuj6819m8biz",
            "displayName":"mike"
        },
        ...
    ]
    ...
}

There will be a "status" attribute for each entry. The contents of the "status" attributes are the following

Attribute name Details
status.text Text to show updated status
status.postedTime Time status updated occurred

If there is no status update, then "null" will be returned.

Extracting Log in status updates

If you have an access token for the "r_profile_last_login" scope, input "lastLogin" in the fields parameter to get a status update on the user.

For example the following type of request will be returned.

GET https://api.mixi-platform.com/2/people/@me/@friends?fields=lastLogin

Consequently, the following response will be returned.

{
    "entry":[
        {
            "id":"fq7qstgzss9dd",
            "displayName":"Ayko",
            "lastLogin":"10080"
        },
        {
            "id":"ipuj6819m8biz",
            "displayName":"mike",
            "lastLogin":"2880"
        },
        ...
    ]
    ...
}

There will be a "lastLogin" attribute for each entry. The contents of the "lastLogin" attributes are the following.

Attribute name details
lastLogin Will show the log in status of the target user. The value returned will be "logged in n minutes ago" multiplied by 5.

For example, if a friend logged in 3 minutes ago, 5 will be returned.
If a friend logged in 1.5 hours ago, 120 will be returned.
If a friend logged in 2.5 days ago, 4320 will be returned.
The maximum number that will be returned will be the value equivalent to a log in for a week ago (4*24*60). Last logins that surpass 3 days will always return this maximum value.

Extracting profile information

If you have an access token which allows access to the following scope and add a fields parameter, profile information can be extracted.

Scope name details Applicable field values
r_profile_name User name name
r_profile_gender User gender gender
r_profile_birthday User date of birth birthday
r_profile_blood_type User blook type bloodType
r_profile_location User address location
r_profile_hometown User home town hometown
r_profile_about_me User introduction aboutMe
r_profile_occupation User field of work occupation
r_profile_interests User interest interests
r_profile_favorite_things User favorite things favoriteThings
r_profile_organizations User organization organizations

If you specify “@all“in the field, all the information that can be extracted with the access token you own will be returned.

You will receive the following result if user information is extracted properly.
((The following result is returned when an access token that has all privileges in People API is used and when the field is populated with the “@all“ command.))

{
    "entry":[
        {
            "id":"qgjw87yg3djw",
            "displayName":" Ayako",
            "profileUrl":"http://mixi.jp/show_friend.pl?uid=rdqz7s6ew176q",
            "thumbnailUrl":"http://mixi.jp/photo/user/rdqz7s6ew176q_2105834213.jpg",
            "name":{
                "givenName":"Ayako",
                "familyName":"Sato"
            },
            "gender":"female",
            "birthday":"1980-04-10",
            "organizations":[
                {
                    "name":"Mixi, Inc."
                }
            ],
            "occupation":"Back Office",
            "aboutMe":"My name is Ayako.",
            "bloodType":"A",
            "interests":[
                "Watching movies","Cooking","Eating out","Shopping"," Travel", "Learning languages","Manga","Relaxing activities"
            ],
            "addresses":[
                {
                    "region":"Kyoto",
                    "type":"hometown",
                    "locality":"Uji-shi"
                },
                {
                    "region":"Tokyo",
                    "type":"location",
                    "locality":"Shibuya-ku"
                }
            ],
            "favoriteThings":[
                {
                    "order":"1",
                    "value":"Tennis",
                    "type":"Sports"
                },
                {
                    "order":"2",
                    "value":"Learning English",
                    "type":"Learning"
                },
                {
                    "order":"3",
                    "value":"Jazz",
                    "type":"Music"
                }
            ],
        },
        ...
    ]
    ...
}

An explanation of the entries is provided below.

Attribution name details
name.givenName User name (* non-approved user needs the status of "global publication")
name.firstName User name (Japanese Characters) (* non-approved user needs the status of "global publication")
gender User gender
birthday User date of birth. The date of birth will be shown as yyyy-mm-dd. Data that could not be extracted will return the value 0.
(* non-approved user needs the status of "global publication")
organizations.name User organization
occupation User occupation
aboutMe User introduction
bloodType User blood type
interests User interest
addresses.region User address (prefecture level information)
addresses.locality User address (city level information) (* non-approved user needs the status of "global publication")
addresses.type Address type. Either hometown or currently residence
favoriteThings.type User favorite things (category)
favoriteThings.value User favorite things (details)
favoriteThings.order User favorite things (order in list)

The word count for each category is managed by mixi.

※Please understand that the information that can be extracted will be dependent on the user's privacy settings and service use situations.

Paging, format

People API supports paging which is supported in JSON format.

TOP OF THIS PAGE