People
概要
ユーザーのプロフィール情報及び、ユーザーの友達一覧を取得する為の API です。
People オブジェクトフィールド
API リクエスト
HTTP メソッド
- Proxy モデル
- GET - プロフィール情報の取得、友達一覧の取得、友達のプロフィール情報の取得
- Trusted モデル
- GET - プロフィール情報の取得、友達一覧の取得、友達のプロフィール情報の取得
エンドポイント URL
-
Sandbox 環境
http://sb.sp.app.mbga.jp/api/restful/v1/people/{guid}/{selector}{-prefix|/|pid} -
本番環境
http://sp.app.mbga.jp/api/restful/v1/people/{guid}/{selector}{-prefix|/|pid}
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 の値は返りません。年齢を「表示しない」に選択している場合、age は返却されず、birthday は "0000-12-31" というような西暦が 0000 の形で返却されます。
- guid に指定したユーザー が存在しない場合、レスポンスコードは 404 が返ります。
- ユーザーがそのアプリケーションをインストールしていない場合で hasApp が fields に指定されているリクエストでは レスポンスコード200 と論理値が返ります。
- isFamous がtrueのユーザーはMobageで管理された仮想ユーザーになりますのでアプリを利用することはなく、一般ユーザーとは異なる扱いとなります。
- Feature Phone本番環境ではキャッシュ経由のサムネイル画像URLとしてava-a.mbga.jpドメインのthumbnailUrl値が返されます。
- Smartphone Web本番環境ではキャッシュ経由のサムネイル画像URLとしてava-a.sp.mbga.jpドメインのthumbnailUrl値が返されます。
サンプル
viewer のプロフィール情報の取得
viewer のプロフィール情報として、id, nickname, profileUrl, thumbnailUrl フィールドを application/json 形式で取得する場合です。
リクエスト形式
GET /api/restful/v1/people/@me/@self?fields=id,nickname,profileUrl,thumbnailUrl&format=json
レスポンス形式
200 OK
Content-Type: application/json; charset=utf8
{
"startIndex" : 1,
"person" : {
"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"
},
"itemsPerPage" : 1,
"totalResults" : 1
}
個人認証が済んでいるviewer のプロフィール情報を取得したサンプルレスポンスです。※ユーザーグレードは3になります
リクエスト形式
GET /api/restful/v1/people/@me/@self?format=json
レスポンス形式
200 OK
Content-Type: application/json; charset=utf8
{
"startIndex" : 1,
"person" : {
"grade" : 3,
"hasApp" : true,
"isVerified" : true,
"bloodType" : "A",
"aboutMe" : "自己紹介文",
"id" : "sb.mbga.jp:10000",
"isFamous" : false,
"birthday" : "1990-01-02",
"displayName" : "Mobage太郎",
"gender" : "male",
"interests" : "趣味",
"thumbnailUrl" : "http://sb-sp.mbga.jp/img_u/10000/0.0.gif",
"nickname" : "Mobage太郎",
"jobType" : "職業",
"profileUrl" : "http://sb-sp.mbga.jp/_u?u=10000",
"addresses" : [
{
"formatted" : "東京都"
}
]
},
"itemsPerPage" : 1,
"totalResults" : 1
}
viewer の友達情報の取得
viewer の友達情報として、id, nickname, profileUrl, thumbnailUrl フィールドを application/json 形式で取得する場合です。
リクエスト形式
GET /api/restful/v1/people/@me/@friends?fields=id,nickname,profileUrl,thumbnailUrl,hasApp&format=json&count=10&startIndex=1
レスポンス形式
200 OK
Content-Type: application/json; charset=utf8
{
"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
}
OpenSocial RESTful Protocol Specification v0.9 - 7.1 People
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
更新履歴
- 2014/03/13
- 「guid に @me 以外を指定した場合は、guid のユーザーがそのアプリケーションをインストールしている必要があります。」という記述を削除
- 2013/1/22
- ユーザーグレード に関する記述を追加
- 2012/12/3
- Smartphone版 に関する記述を追加
- 2012/11/14
- isFamous に関する記述を追加
- 2012/08/14
- アプリインストール判定に関する記述を注意事項に追加修正
- 2012/06/28
- ニュース掲載 API 改修 の対応に関する記述を追加
- 2011/10/11
- 注意事項へ isVerified に関する記述を追加
- 2011/08/29
- isVerified フィールドを追加
- 2011/07/25
- addresses フィールドについて加筆