mixi Developer Center (ミクシィ デベロッパーセンター)

mixi Connect

mixi Connect » mixi Graph API » 技術仕様 » People API

People API

ソーシャル化をする上で最も重要な情報、それはソーシャルグラフです。あるユーザの情報と、そのユーザが誰とつながっているのか、その情報を取得することができるAPIが、People APIです。クライアントプログラムは、People APIにより取得した友人一覧を元にして、ソーシャルアプリケーションを開発することができます。多くのサービスにおいて、このAPIの利用は必須となることでしょう。

ここでは、ユーザのプロフィール情報および友人の一覧を取得するためのPeople APIについて、その使用方法を説明します。

利用のポイント

People APIでは、いくつかご利用にあたり知っておくべきポイントがあります。まずはこれらのポイントを把握し、ガイドラインに沿った効果的なアプリケーションの開発を行っていただければ幸いです。

ユーザのプロフィール画像について

ユーザのプロフィール情報を取得するために利用可能なPeople APIですが、取得可能な情報には、ユーザが設定しているプロフィール画像のURLが含まれます。具体的には、thumbnailUrlがそれに該当します。このプロフィール画像は、実は以下の2種類が存在します。thumbnailUrlにて取得されるプロフィール画像のURLは、下記の種別のどちらかとなります。

種別説明
友人向け画像 友人が見ることができるプロフィール画像
全体公開向け画像 友人以外の全てのmixiユーザが見ることができるプロフィール画像

People APIにて取得可能なユーザは、認可ユーザ自身もしくは認可ユーザの友人です。このいずれの場合にも、thumbnailPrivacyパラメータを指定せずにPeople APIにアクセスした結果は「友人向け画像のURL」が得られます。特に友人の場合は、必ず友人向け画像のURLが結果として得られることになります。

mixi.jpサイト内では、友人向けプロフィール画像は第3者に見られることがない画像として機能設計がされています。この制約に関してmixi Graph APIを使ったアプリケーションにおいても適用していただくために、以下のガイドラインを設けさせていただいております。

友人向けのプロフィール画像は本人の承諾があっても第三者への公開はできません。
http://developer.mixi.co.jp/connect/term/guideline_of_mixi_connect

一方、認可ユーザ自身のプロフィール画像については、thumbnailPrivacyパラメータにeveryone値を指定することで、全体公開向けプロフィール画像をthumbnailUrlにて取得できるようになっています。この全体公開向け画像の扱いについては、ガイドラインにて以下のように規定させていただいております。

本人の承諾を得た上であれば、本人のニックネームとプロフィール画像を第三者が閲覧できるようにすることを認めます。
http://developer.mixi.co.jp/connect/term/guideline_of_mixi_connect

上記の方針およびガイドラインを遵守した上で、People APIをご利用ください。

プロフィールページのURLについて

People APIで扱われるユーザの範囲は「認可ユーザ本人もしくはその友人」に限定されており、これを反映した設計として、People APIにて取得されるプロフィールページのURL(profileUrl)については、ログインユーザとそのURLのユーザが友人関係である場合にのみ閲覧可能となっていました。しかしmixiのサービスを通じて同じ興味を持った方々と新しいつながりを持ってもらいたいという方針になりprofileUrlについても友人以外のユーザでも閲覧可能となるURLを取得できるよう変更されました。

また、取得したデータについてはガイドラインにおいて、以下のような規定をさせていただいており、それに沿ったアプリケーションにおいてAPIで取得した第三者の情報を扱うことは、ユーザの同意なく行うことは禁止となっております。

取得したデータの利用、取り扱いについての補足事項
http://developer.mixi.co.jp/connect/term/guideline_of_mixi_connect/codicil_of_term_1

また、取得されるURLはPC用のものとなります。モバイル用のプロフィールページについてはドメインを"http://m.mixi.jp/"に変更したURLにアクセスしてください。

事前に必要なもの

People APIを利用するためには、以下の情報をすでに入手している必要があります。

  • "r_profile"スコープについて認可されたアクセストークン

上記以外のスコープで認可されたアクセストークンを使用して、People APIにアクセスすることはできません。アクセストークンの入手方法については、認証認可手順のページをご覧ください。

友人一覧の取得

ユーザが登録している友人の一覧を取得するために、クライアントプログラムは"https://api.mixi-platform.com/2/people"にアクセスします。このURIは、以下の仕様となります。

GET https://api.mixi-platform.com/2/people/[User-ID]/[Group-ID]
パラメータ名指定する値
User-ID 取得したいユーザのID、または"@me"
Group-ID 取得したいグループのID、または"@self"、"@friends"

友人一覧はユーザのプライベートな情報となるため、User-IDはアクセストークンを認可したユーザ本人のIDまたは"@me"のみ指定することができます。ただし、mixiアプリからは本人以外のユーザを指定することもできます。詳細は「mixiアプリで「友人・友人の友人」以外のユーザ情報を取得する際の注意点」をご参照ください。

Group-IDは、取得したいユーザの集合を特定するためのIDを指定します。指定可能なIDは、以下となります。グループのIDは、Groups APIにて取得することができます。

ID説明
@self User-IDで特定されるユーザ自身のプロフィール情報
@friends User-IDで特定されるユーザの友人として登録されたユーザのプロフィール情報一覧
グループID User-IDで特定されるユーザが登録している、あるグループに所属するユーザのプロフィール情報一覧

People APIでは、以下のクエリパラメータをサポートしています。

パラメータ名説明
sortBy パラメータ値として"displayName"を指定することで、取得結果をニックネームによる並び順とすることができます。
パラメータ値として"affinity"を指定した場合は取得結果を親密度による並び順とすることができます。
パラメータ値として"lastLogin"を指定した場合は取得結果をログイン時間による並び順とすることができます。
このパラメータを省略した場合は、ユーザのID順となります。
※親密度とは友人との親密さを表す指標です。頻繁にコメントやイイネをやりとりするとこの値が大きくなります。
sortOrder このパラメータ値として"ascending"を指定した場合は昇順、"descending"を指定した場合は降順に取得結果が並び替えされます。このパラメータを省略した場合は、昇順となります。
thumbnailPrivacy パラメータ値として"everyone"を指定した場合は、レスポンスに含まれるthumbnailUrlが全体向けに設定したイメージのURLとなり、"friends"を指定した場合は、友人向けに設定したイメージのURLとなります。
このパラメータを省略した場合は、thumbnailUrlは友人向けに設定したイメージのURLとなります。
尚、このパラメータは、User-IDにアクセストークンを認可したユーザ本人のIDまたは"@me"を指定し、且つGroup-IDに@selfを指定した場合にのみ有効となります。
thumbnailUrlScheme レスポンスに含まれるthumbnailUrlのschemeをパラメータ値として指定します。指定可能な値は "http" または "https" のいずれかになります。
このパラメータを省略した場合は API 呼び出しに使用したものと同じ scheme が thumbnailUrl に使用されます。http で呼び出した場合は http となり、https で呼び出した場合は https となります。
filterBy "r_profile_birthday"スコープについて認可されたアクセストークンを持っている場合、パラメータ値に"birthDateWithin"を指定することによって、現在日からfilterValueパラメータに指定した値の日数以内に誕生日を迎えるユーザを取得できます。 日数の計算は日付単位で行います。
尚、ユーザの公開範囲設定によっては指定した日数以内に誕生日を迎えるユーザでも取得できない場合があります。
"mixi_apps2"スコープについて認可されたアクセストークンを持っている場合、パラメータ値に"hasApp"を指定することによって、クライアントのmixiアプリをインストールしているユーザを取得できます。詳細は、「mixiアプリを利用している友人一覧の取得」をご参照ください。
パラメータ値に"birthDateWithin"を指定した際にはfilterValueパラメータに日数の指定が必須となります。
filterValue filterByパラメータに"birthDateWithin"を指定している場合、パラメータ値として日数を設定します。

正常に取得できた場合は、以下のような結果を得ることができます。下記の例は、JSON形式の結果です。

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

個々のエントリに含まれる情報は、以下となります。

属性名説明
id ユーザのID
displayName ユーザのニックネーム
thumbnailUrl ユーザがプロフィール画像として設定しているイメージのURL
thumbnailDetails ユーザのプロフィール画像の各サイズ(large, small, mini)の配列
※ fieldsで指定された場合のみ返されます
profileUrl このユーザのプロフィルページのURL

thumbnailDetailsは配列になっています。各アイテムに以下の属性情報があります。

属性名説明
size サムネール画像のサイズ種類
"l" (large、最大180px), "s" (small、最大76px), "m" (mini、最大40px)のいずれか
url サムネール画像のURL
width サムネール画像の横幅(ピクセル)
height サムネール画像の縦幅(ピクセル)
isDefault 取得できるプロフィール画像がない場合のみ、trueに設定されます。この場合はデフォルト画像の情報が返されています。

クライアントプログラムは、fieldsパラメータを使用することで、取得する情報の項目を制限することができます。fieldsパラメータを省略した場合は、上記全ての項目が結果に含まれます。fieldsパラメータは、上記の属性名をカンマ区切りで列挙したものをクエリパラメータに指定します。例えば以下のようになります。

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

fieldsパラメータを指定した場合にも、idおよびdisplayNameは結果に必ず含まれます。

最新ステータスの取得

"r_profile_status"スコープについて認可されたアクセストークンを持っている場合、fieldsパラメータに"status"を追加することによって、ユーザの最新ステータスを取得できます。

例えば以下のようなリクエストを発行します。

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

これにより以下のようなレスポンスが得られます。

{
    "entry":[
        {
            "status":{
                "postedTime":"2011-02-02T12:21:37+09:00",
                "text":"原宿なう"
            },
            "id":"fq7qstgzss9dd",
            "displayName":"アヤコ"
        },
        {
            "status": null,
            "id":"ipuj6819m8biz",
            "displayName":"mike"
        },
        ...
    ]
    ...
}

各エントリ内に"status"という属性が含まれます。"status"属性の内容は以下のとおりです。

属性名説明
status.text 最新ステータスを表す文字列
status.postedTime ステータスの更新時刻

最新ステータスがない場合はnull値が返されます。

ログイン状況の取得

"r_profile_last_login"スコープについて認可されたアクセストークンを持っている場合、fieldsパラメータに"lastLogin"を追加することによって、ユーザのログイン状況を取得できます。

例えば以下のようなリクエストを発行します。

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

これにより以下のようなレスポンスが得られます。

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

各エントリ内に"lastLogin"という属性が含まれます。"lastLogin"属性の内容は以下のとおりです。

属性名説明
lastLogin 対象ユーザのログイン時間を示します。この値として、「n時間以内」のn値に60をかけた数値が返却されます。
1時間以内の場合は、5分区切りで数値を返します(3分前の場合は5を返し、23分前の場合は25を返します)。
1時間以上、1日以内の場合は、1時間区切りで数値を返します(1時間半前の場合は120を返します)。
1日以上、3日以内の場合は、1日区切りで数値を返します(2.5日前の場合は4320を返します)。
3日を超えてログインしていないユーザーに関しては「4 * 24 * 60」で5760を返します。

ユーザの詳細情報の取得

下記のスコープについて許可されたアクセストークンを持っており、
加えて対応するfieldsパラメータを追加することによって、ユーザの詳細なプロフィール情報を取得することが可能です。

スコープ名説明対応するfieldsの値
r_profile_name ユーザの氏名 name
r_profile_gender ユーザの性別 gender
r_profile_birthday ユーザの生年月日 birthday
r_profile_blood_type ユーザの血液型 bloodType
r_profile_location ユーザの現住所 location
r_profile_hometown ユーザの出身地 hometown
r_profile_about_me ユーザの自己紹介 aboutMe
r_profile_occupation ユーザの職業 occupation
r_profile_interests ユーザの趣味 interests
r_profile_favorite_things ユーザの好きなもの情報 favoriteThings
r_profile_organizations ユーザの所属 organizations

また、fieldsに"@all"を指定する事により、
現在所持しているアクセストークンで取得可能な全てのユーザ情報を取得することが可能です。

正常にユーザの詳細情報を取得できた場合は、以下のような結果を得ることができます。
(下記の例は、People APIに関する全てのスコープについて許可されたアクセストークンを持っており、fieldsに@allを指定した場合の例です。)

{
    "entry":[
        {
            "id":"qgjw87yg3djw",
            "displayName":" アヤコ",
            "profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx",
            "thumbnailUrl":"http://mixi.jp/photo/user/rdqz7s6ew176q_2105834213.jpg",
            "name":{
                "givenName":"彩子",
                "familyName":"佐藤"
            },
            "gender":"female",
            "birthday":"1980-04-10",
            "organizations":[
                {
                    "name":"株式会社ミクシィ"
                }
            ],
            "occupation":"事務系",
            "aboutMe":"あやこです。 宜しくお願いします。",
            "bloodType":"A",
            "interests":[
                "映画鑑賞","料理","グルメ","ショッピング"," 旅行","語学","マンガ","美容・ダイエット"
            ],
            "addresses":[
                {
                    "region":"京都府",
                    "type":"hometown",
                    "locality":"宇治市"
                },
                {
                    "region":"東京都",
                    "type":"location",
                    "locality":"渋谷区"
                }
            ],
            "favoriteThings":[
                {
                    "order":"1",
                    "value":"テニス",
                    "type":"スポーツ"
                },
                {
                    "order":"2",
                    "value":"英会話",
                    "type":"習いごと"
                },
                {
                    "order":"3",
                    "value":"ジャズ",
                    "type":"音楽"
                }
            ],
        },
        ...
    ]
    ...
}

個々のエントリに含まれる情報は、以下となります。

属性名説明
name.givenName ユーザの名前 (※認可ユーザー以外は全体に公開の場合のみ取得可能)
name.firstName ユーザの名字 (※認可ユーザー以外は全体に公開の場合のみ取得可能)
gender ユーザの性別
birthday ユーザの生年月日。日時の書式は「yyyy-mm-dd」となります。yyyy/mm/ddでそれぞれ取得できなかった情報は0にマスクされます。
(※認可ユーザー以外は全体に公開の場合のみ取得可能)
organizations.name ユーザの所属
occupation ユーザの職業
aboutMe ユーザの自己紹介
bloodType ユーザの血液型
interests ユーザの趣味
addresses.region ユーザに関する住所情報(都道府県情報)
addresses.locality ユーザに関する住所情報(市町村情報) (※認可ユーザー以外は全体に公開の場合のみ取得可能)
addresses.type 住所情報の種別。hometown(出身地)、またはlocation(現住所)となります。
favoriteThings.type ユーザの好きなもの情報(種別)
favoriteThings.value ユーザの好きなもの情報(説明文)
favoriteThings.order ユーザの好きなもの情報(表示順)

各項目の文字数制限等はmixi上の制限に準じます。

※ユーザの公開範囲設定、サービス利用状況によっては、各情報が取得ができないことがございます。あらかじめご了承下さい。

ユーザハッシュについて

mixi アプリで、"mixi_apps2"スコープについて認可されたアクセストークンを持っている場合、fieldsパラメータに"userHash"を指定することで、ユーザハッシュという識別子を得ることができます。
ユーザハッシュとは、「"mixiにユーザ登録した際に使用した携帯電話端末の情報"と"mixiアプリID"を元に生成した文字列」です。つまり、あるユーザがmixiに入退会を繰り返したとしても、同じ携帯端末を使って入退会した場合には、ユーザIDが変わったとしても、ユーザハッシュは同じ文字列となります。

ユーザハッシュを使うことで、入退会を繰り返すことで異なるユーザIDを取得しながらmixiアプリを利用しているユーザを検出することが可能となります。具体的には、以下の手順で検出を行うことができます。

  1. People APIにて、ユーザIDとユーザハッシュを取得し、それらを組み合わせて記録しておく
  2. そのユーザが入退会を行うことで別のユーザIDを取得し、同じmixiアプリが利用される
  3. People APIにて、そのユーザIDのユーザハッシュを取得する
  4. 記録していたユーザハッシュを検索し、既に同じユーザハッシュが存在した場合は、記録していたユーザIDと新しいユーザIDは、同一のユーザと見なすことができる

これによって、例えば入退会を繰り返すことで、mixiアプリの招待機能を繰り返し利用し不正にインセンティブを得る、といった行為をある程度抑止することができるようになります。

ユーザハッシュを取得するには、例えば以下のようなリクエストを発行します。

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

これにより以下のようなレスポンスが得られます。

{
    "entry":{
        "id":"fq7qstgzss9dd",
        "displayName":"アヤコ",
        "userHash":"9g012dfnwrt6qxbctt9fw86utfg0k7yco6guzox5"
    },
    ...
}

エントリ内に含まれる"userHash"がユーザハッシュとなります。

mixiアプリ利用状態の取得

mixiアプリで、"mixi_apps2"スコープについて認可されたアクセストークンを持っている場合、fieldsパラメータに"hasApp"を指定することで、クライアントのmixiアプリの利用状態を得ることができます。
以下のようにクエリパラメータを指定してください。

パラメータ名説明
fields "hasApp"。取得したユーザのエントリに、mixiアプリの利用状態を表す"hasApp"を取得したい場合に指定します。
ユーザーがアプリをインストールしている場合、 true が得られます。
ユーザーがアプリをインストールしていない場合、 false が得られます。

例えば、以下のようなリクエストを発行します。

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

これにより、以下のようなレスポンスが得られます。

{
    "entry":{
        "id":"fq7qstgzss9dd",
        "displayName":"アヤコ",
        "hasApp": true
    },
    ...
}

mixiアプリを利用している友人一覧の取得

mixiアプリで、"mixi_apps2"スコープについて認可されたアクセストークンを持っている場合、filterByパラメータに"hasApp"を指定することで、クライアントのmixiアプリをインストールしている友人のみに絞って取得することができます。
以下のようにクエリパラメータを指定してください。

パラメータ名説明
filterBy "hasApp"。mixiアプリをインストールしているユーザのみのデータを取得したい場合に指定します。

例えば、以下のようなリクエストを発行します。

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

これにより、mixiアプリをインストールしている友人のみのデータが得られます。

mixiアプリのサポートコミュニティ、サポートページ利用状態の取得

mixiアプリで、"mixi_apps2"スコープについて認可されたアクセストークンを持っている場合、fieldsパラメータに"joinedForum"を指定することで、クライアントのmixiアプリに登録されているサポートコミュニティ、サポートページのユーザの利用状況を得ることができます。
以下のようにクエリパラメータを指定してください。

パラメータ名説明
fields "joinedForum"。mixiアプリに登録されているサポートコミュニティ、サポートページの利用状態を表す"joinedForum"を取得したい場合に指定します。
ユーザーがサポートコミュニティ、サポートページを利用しているかどうかの情報がそれぞれについてtrueまたはfalseで得られます。
"joinedForum"フィールドは認可ユーザ自身の情報のみ取得できます。

例えば、以下のようなリクエストを発行します。

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

これにより、以下のようなレスポンスが得られます。

{
    "entry":{
        "id":"fq7qstgzss9dd",
        "displayName":"アヤコ",
        "joinedForum":{
            "community":true,
            "page":false
        }
    },
    ...
}

"joinedForum"フィールドの内容は以下のとおりです。

属性名説明
joinedForum.community アプリのサポートコミュニティに参加している場合はtrue、していない場合はfalse。
joinedForum.page アプリのサポートページをフォローしている場合はtrue、していない場合はfalse。

アプリにサポートコミュニティ、サポートページが登録されていない場合は、登録されていないもののフィールドはレスポンスに含まれません。

例えば、サポートページのみ登録済みで、サポートコミュニティが登録されていないアプリではレスポンスは以下のような形式になります。

{
    "entry":{
        "id":"fq7qstgzss9dd",
        "displayName":"アヤコ",
        "joinedForum":{
            "page":false
        }
    },
    ...
}

SMS認証状態の取得

※このパラメータはSMS認証の非必須化リリース後、有効となります。

mixiアプリで、"mixi_apps2"スコープについて認可されたアクセストークンを持っている場合、fieldsパラメータに"isVerified"を指定することで、クライアントのSMS認証状態を得ることができます。
以下のようにクエリパラメータを指定してください。

パラメータ名説明
fields "isVerified"。取得したユーザのエントリに、SMS認証状態を表す"isVerified"を取得したい場合に指定します。
SMS認証済ユーザーの場合、 true が得られます。
SMS認証が済んでいないユーザの場合、 false が得られます。

例えば、以下のようなリクエストを発行します。

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

これにより、以下のようなレスポンスが得られます。

{
    "entry":{
        "id":"fq7qstgzss9dd",
        "displayName":"アヤコ",
        "isVerified": true
    },
    ...
}

mixiアプリで「友人・友人の友人」以外のユーザ情報を取得する際の注意点

mixiアプリからの利用で同じアプリを利用しているユーザの場合には、User-IDに「友人・友人の友人」以外のユーザを指定することができます。このときGroup-IDに指定できるのは"@self"のみとなります。

ただし、アクセストークンを認可したユーザ本人または取得対象のユーザが18歳未満の場合には、「友人・友人の友人」以外のユーザ情報を取得することができません。

ページング、表現形式

People APIは、ページングをサポートします。サポートされる表現形式は、JSON形式のみとなります。

このページの上部へ