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

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

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

利用のポイント

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

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

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

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"のみ指定することができます。ただし、mixiアプリからは本人以外のユーザを指定することもできます。詳細は「mixiアプリで「友人・友人の友人」以外のユーザ情報を取得する際の注意点」をご参照ください。

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

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

正常に取得できた場合は、以下のような結果を得ることができます。下記の例は、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"
    },
    ・・・
  ],
  ・・・
};

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

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

クライアントプログラムは、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"属性の内容は以下のとおりです。

最新ステータスがない場合は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"属性の内容は以下のとおりです。

ユーザの詳細情報の取得

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

また、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":"音楽"
                }
            ],
        },
        ...
    ]
    ...
}

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

各項目の文字数制限等は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アプリの利用状態を得ることができます。
以下のようにクエリパラメータを指定してください。

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

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アプリをインストールしている友人のみに絞って取得することができます。
以下のようにクエリパラメータを指定してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

SMS認証状態の取得

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

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

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

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形式のみとなります。