mixi Connect » mixi Graph API » 技術仕様 » People lookup API
People lookup API
近年では、gmailやその他多くのメールサービスが登場し、友人や知人の一覧が各サービスのコンタクトリストに登録されています。また、スマートフォンの普及により、友人や知人の電話帳はますますリッチな内容になっていくことでしょう。それらのコンタクトリストには電子メールアドレスが含まれていることが多く、このメールアドレスとmixi上のプロフィールを関連づけることで、コンタクトリストをソーシャル化することができるようになります。
ここでは、メールアドレスからユーザのプロフィール情報を取得するためのPeople lookup APIについて、その使用方法を説明します。
事前に必要なもの
People lookup APIを利用するためには、以下の情報をすでに入手している必要があります。
- “r_profile”スコープについて認可されたアクセストークン
上記以外のスコープで認可されたアクセストークンを使用して、People lookup APIにアクセスすることはできません。アクセストークンの入手方法については、認証認可手順のページをご覧ください。
メールアドレスからプロフィール情報の取得
メールアドレスからユーザのプロフィール情報を取得するために、クライアントプログラムは”https://api.mixi-platform.com/2/search/people”にアクセスします。このURIは、以下の仕様となります。
GET https://api.mixi-platform.com/2/search/people/[Group-ID]?q=[Emails]
| パラメータ名 | 指定する値 |
|---|---|
| Group-ID | 検索対象グループのID。友人のみから検索する場合は “@friends”、友人以外も検索対象に含める場合は “@all” を指定します。省略された場合は友人のみになります |
| Emails | 検索したいメールアドレスをカンマ区切りで指定します |
取得結果は指定されたメールアドレスを登録しているユーザに関して、
- アクセストークンを認可したユーザの友人の場合は、そのユーザのプロフィール情報が返却されます。
- 友人以外の場合は、要求時に指定したEmailsパラメータに含まれていたメールアドレスのみが返却されます。
- ユーザが見つからない、あるいは設定により検索不可になっている場合は取得結果に含まれません。
正常に取得できた場合は、以下のような結果を得ることができます。下記の例は、JSON形式の結果です。
{
"entry" : [
{
"id" : "qgjw87yg3djw",
"displayName" : "bert",
"thumbnailUrl" : "http://img.mixi.net/img/basic/common/noimage_member180.gif",
"profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx",
"emails" : [
"foo@example.com",
・・・
]
},
・・・
],
・・・
};
個々のエントリに含まれる情報は、以下となります。
| 属性名 | 説明 |
|---|---|
| id | ユーザのID |
| displayName | ユーザのニックネーム |
| thumbnailUrl | ユーザがプロフィール画像として設定しているイメージのURL |
| profileUrl | このユーザのプロフィルページのURL |
| emails | メールアドレスの一覧 |
検索結果のユーザがアクセストークンを認可したユーザの友人以外の場合、個々のエントリに含まれる情報は、emailsプロパティのみになります。
emailsプロパティには、要求時に指定したEmailsパラメータに含まれていたメールアドレスのみが記載されます。また、要求時に指定した複数のメールアドレスが同じ一人のユーザにより登録されたものである場合は、emailsプロパティには複数のメールアドレスが記載されることになります。
クライアントプログラムは、fieldsパラメータを使用することで、取得する情報の項目を制限することができます。fieldsパラメータを省略した場合は、上記全ての項目が結果に含まれます。fieldsパラメータは、上記の属性名をカンマ区切りで列挙したものをクエリパラメータに指定します。例えば以下のようになります。
GET https://api.mixi-platform.com/2/search/people?q=[Emails]&fields=thumbnailUrl%2CprofileUrl
fieldsパラメータを指定した場合にも、idおよびdisplayNameは結果に必ず含まれます。
ページング、表現形式
People lookup APIは、ページングをサポートします。サポートされる表現形式は、JSON形式のみとなります。