People

概要

ユーザーのプロフィール情報及び、ユーザーの友達一覧を取得する為の API です。


People オブジェクトフィールド

説明

名前空間

補足

id

ユーザー ID

xs:string

http://ns.opensocial.org/2008/opensocial

nickname

ニックネーム

xs:string

http://ns.opensocial.org/2008/opensocial

displayName

nickname と同義

xs:string

http://ns.opensocial.org/2008/opensocial

aboutMe

自己紹介

xs:string

http://ns.opensocial.org/2008/opensocial

birthday

誕生日

xs:date

http://ns.opensocial.org/2008/opensocial

interests

趣味

xs:string

http://ns.opensocial.org/2008/opensocial

ユーザーによる任意入力テキスト

profileUrl

プロフィール情報のある URL

xs:string

http://ns.opensocial.org/2008/opensocial

thumbnailUrl

サムネイル画像のある URL

xs:string

http://ns.opensocial.org/2008/opensocial

gender

性別

xs:string

http://ns.opensocial.org/2008/opensocial

"male" or "female" or "undisclosed"

addresses

地域

tns:Address

http://ns.opensocial.org/2008/opensocial

プロフィールにある都道府県

jobType

職業

xs:string

http://ns.dena.jp/mbga/gameapi/v1

ユーザーによる任意入力テキスト

bloodType

血液型

xs:string

http://ns.dena.jp/mbga/gameapi/v1

"A"|"B"|"O"|"AB" のいずれか (ダブルクオート除く)

hasApp

アプリケーションをインストール済みかどうか

xs:boolean

http://ns.opensocial.org/2008/opensocial

isVerified

個人認証が済んでいるかどうか

xs:boolean

http://ns.dena.jp/mbga/gameapi/v1

isFamous

仮想ユーザや有名人ユーザであるかどうか

xs:boolean

http://ns.dena.jp/mbga/gameapi/v1

grade

ユーザーグレード

xs:int

http://ns.dena.jp/mbga/gameapi/v1

"1":かんたん会員|"2":通常会員|"3"個人認証済み会員 のいずれか


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 のユーザーがそのアプリケーションをインストールしている必要があります。」という記述を削除
  • 2012/12/11
    • 新規作成

PREVIOUS

RESTful API リファレンス

NEXT

AppData