People
概要
ユーザーのプロフィール情報及び、ユーザーの友達一覧を取得する為のAPIです。
People オブジェクトフィールド
People API に GET リクエストを行うと、People オブジェクトが返却されます。URI Template パラメータの fields パラメータで指定したフィールドのみ取得可能です。
| 値 | 説明 | 型 | 補足 |
|---|---|---|---|
| id | ユーザー ID | xs:string | – |
| nickname | ニックネーム | xs:string | – |
| displayName | nickname と同義 | xs:string | – |
| aboutMe | 自己紹介 | xs:string | – |
| birthday | 誕生日 | xs:date | – |
| interests | 趣味 | xs:string | ユーザーによる任意入力テキスト |
| profileUrl | プロフィール情報のある URL | xs:string | – |
| thumbnailUrl | サムネイル画像のある URL | xs:string | – |
| gender | 性別 | xs:string | "male" or "female" or "undisclosed" |
| addresses | 地域 | tns:Address | プロフィールにある都道府県 |
| jobType | 職業 | xs:string | ユーザーによる任意入力テキスト |
| bloodType | 血液型 | xs:string | "A" |
| hasApp | アプリケーションをインストール済みかどうか | xs:boolean | – |
| isVerified | 個人認証が済んでいるかどうか | xs:boolean | – |
| isFamous | 仮想ユーザや有名人ユーザであるかどうか | xs:boolean | – |
| grade | ユーザーグレード | xs:int | "1":かんたん会員 |
エンドポイントURL
Sandbox 環境
https://sb-app.mobage.jp/social/api/restful/v2/people/{guid}/{selector}{-prefix|/|pid}
本番環境
https://app.mobage.jp/social/api/restful/v2/people/{guid}/{selector}{-prefix|/|pid}
APIリクエスト
HTTP メソッド
- Authorization Code Grant
- GET - プロフィール情報の取得、友達一覧の取得、友達のプロフィール情報の取得
- Client Credentials Grant
- GET - プロフィール情報の取得、友達一覧の取得、友達のプロフィール情報の取得
URI Template パラメータ
guid
guidパラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @me | viewer の guid | 必須 |
| {guid} | ユーザー ID | 必須 |
guidにユーザー IDを指定する場合、そのアプリケーションをユーザーがインストールしている必要があります。
selector
selectorパラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @self | guid パラメータで指定したユーザー自身のプロフィール情報に対するエントリリソース | 必須 |
| @friends | guid パラメータで指定したユーザーの友達のコレクションリソース | 必須 |
| @all | @friends と同義 | 必須 |
pid
pidパラメータはselectorが @friends または @all の時に指定出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| {guid} | 有効な実際のユーザー ID | 任意 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
fields
取得したいプロフィール属性情報を指定する事が出来ます。指定可能な フィールド名 についてはPeopleオブジェクトフィールドを参照して下さい。
複数指定する場合はスペース無しのカンマ (,) 区切りで指定します。
fieldsパラメータを省略した場合、下記の属性情報全てを取得します。
パフォーマンス向上の為に、必要な属性のみを取得するようにして下さい。
count
コレクションリソースとしてレスポンスを取得する際に、最大何件のエントリリソースを取得するかを指定出来ます。selectorに@friends, @allを指定した場合に指定出来ます。
デフォルト値は50件で、最大1000件まで指定出来ます。
startIndex
コレクションリソースの開始値を指定します。省略時は1が指定されます。例えば、全体で100件ある友達情報のページ送りで1ページ辺り8件表示し、2ページ目の情報を取得したい場合、count値に 8を指定し、startIndex値に9を指定します。
filterBy
filterByはselectorが @friends または @all の時に用いる事が出来ます。
filterByを指定すると、レスポンスとして返って来るpersonオブジェクトのコレクションに対して検索条件を加える事が出来ます。filterBy値は検索条件のキーとなるフィールドを指定します。
現在指定可能なfilterBy値は以下の表になります。
| filterBy | 説明 |
|---|---|
| hasApp | アプリケーションをインストールしているかどうか |
filterByを指定する場合、filterOp, filterValueも指定されている必要があります。
filterOp
filterOpはselectorが @friends または @all の時に用いる事が出来ます。
filterOpを指定すると、レスポンスとして返って来るpersonオブジェクトのコレクションに対して検索条件を加える事が出来ます。filterOp値は検索条件のキーと値に対してどのような評価を行うかを指定します。
現在指定可能な filterOp値は以下の表になります。
| filterOp | 説明 |
|---|---|
| equals | filterByで指定したフィールドがfilterValueで指定した値と一致するかどうか |
filterOpを指定する場合、filterBy, filterValueも指定されている必要があります。
filterValue
filterValueはselectorが @friends または @all の時に用いる事が出来ます。
filterValueを指定すると、レスポンスとして返って来るpersonオブジェクトのコレクションに対して検索条件を加える事が出来ます。filterValue値は検索条件のキーに対して、どのような値と評価するかを指定する事ができます。
現在指定可能なfilterValue値は以下の表になります。
| filterValue | 説明 |
|---|---|
| true | 真値 |
| false | 偽値 |
filterValueを指定する場合、filterBy, filterOpも指定されている必要があります。
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | 正常にデータ取得が完了しました |
| GET | 400 | Bad Request | リクエストデータが不正です |
| GET | 401 | Unauthorized | OAuth による認可が失敗しています |
| GET | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| GET | 404 | Not Found | 存在しないリソースです |
| GET | 405 | Method Not Allowed | メソッドが許可されていません |
| GET | 500 | Internal Server Error | API 側の問題による失敗です |
注意事項
- selector に @friend, @all を指定した場合の友達一覧取得ですが、負荷対策の為に最大10分ほど友達一覧の変更が反映されない場合がございます。
- isVerified は個人認証が済んでいるユーザーでも審査部門により不正なユーザーと認定されている場合は、個人認証が済んでいないと判定されます。
- ユーザーが aboutMe / jobType / bloodType などを設定していない場合、値を null として返します。
- ユーザーがmobageプロフィール設定にて誕生日を「表示しない」に選択している場合、birthdayの値は返らず。年齢を「表示しない」に選択している場合、西暦が "0000-12-31" の形式となります。
- guid に指定したユーザー が存在しない場合、レスポンスコードは 404 が返ります。
- ユーザーがそのアプリケーションをインストールしていない場合で hasApp が fields に指定されているリクエストでは レスポンスコード200 と論理値が返ります。
- isFamous がtrueのユーザーはMobageで管理された仮想ユーザーになりますのでアプリを利用することはなく、一般ユーザーとは異なる扱いとなります。
サンプル
viewer のプロフィール情報の取得
viewer のプロフィール情報として、id, nickname, profileUrl, thumbnailUrl フィールドを application/json 形式で取得する場合です。
リクエスト形式
GET /api/restful/v2/people/@me/@self?fields=id,nickname,profileUrl,thumbnailUrl&format=json
レスポンス形式
200 OK
{
"nickname" : "Mobage太郎",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10000/0.0.gif",
"id" : "sb.mbga.jp:10000",
"hasApp" : true,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10000"
}
viewer のプロフィール情報をフィールド指定せずに取得したサンプルレスポンスです。
リクエスト形式
GET /api/restful/v2/people/@me/@self?format=json
レスポンス形式
200 OK
{
"nickname" : "Mobage太郎",
"id" : "sb.mbga.jp:10000"
}
viewer の友達情報の取得
viewer の友達情報として、id, nickname, profileUrl, thumbnailUrl フィールドを application/json 形式で取得する場合です。
リクエスト形式
GET /api/restful/v2/people/@me/@friends?fields=id,nickname,profileUrl,thumbnailUrl,hasApp&format=json&count=10&startIndex=1
レスポンス形式
200 OK
{
"entry" : [
{
"nickname" : "友達A",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10001/0.0.gif",
"id" : "sb.mbga.jp:10001",
"hasApp": true,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10001"
},
{
"nickname" : "友達B",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10002/0.0.gif",
"id" : "sb.mbga.jp:10002",
"hasApp": false,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10002"
},
{
"nickname" : "友達C",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10003/0.0.gif",
"id" : "sb.mbga.jp:10003",
"hasApp" : true,
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10003"
}
],
"startIndex" : 1,
"itemsPerPage" : 10,
"totalResults" : 3
}
更新履歴
- 2015/12/02
- Client Credentials Grant に対応したので、その旨追記しました。
- 2014/11/27
- サンプルにあるレスポンス形式を修正しました