Google People APIを使ってみる

Google APIにPeople APIが公開されたようです。
細かいところはリファレンスを見てもらうとして簡単な解説を記載していきます。

概要

Google+ APIとContacts APIを合わせたようなAPIです。
ただし 情報取得に特化しています。
既存のAPIの上位互換ではないため置き換えるものではありません。

2017-07-06 追記
登録・更新・削除機能が追加されたようです。
Contacts APIを置き換えると明言されたので、People APIで置き換えられるなら順次対応した方が良いでしょう。（まだContacts APIにあってPeople APIにない機能がある？）
G Suite Developers Blog: Google People API now supports updates to Contacts and Contact Groups

API

以下の３つがあります。

• people.get
• people.getBatchget
• people.connections.list

people.get

ユーザーのプロフィール情報を取得します。
URLで言うとここに出ている情報ですね。
https://aboutme.google.com/u/0/

GET https://people.googleapis.com/v1/{resourceName=people/*}

e.g.
Google+のIDを使用した場合、対象ユーザーの公開情報が取得できます。
※このIDはGoogle+プロフィールを表示した時のURL末尾の数字です。Google Apps For WorkであればDirectory APIでのUser.idになります。

GET https://people.googleapis.com/v1/people/101136005779153122515

response

{
 "resourceName": "people/101136005779153122515",
 "etag": "xALpYbJ7M+s=",
 "metadata": {
  "sources": [
   {
    "type": "PROFILE",
    "id": "101136005779153122515"
   },
   {
    "type": "DOMAIN_PROFILE",
    "id": "101136005779153122515"
   }
  ],
  "objectType": "PERSON"
 },
 "locales": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "ACCOUNT",
     "id": "101136005779153122515"
    }
   },
   "value": "ja"
  }
 ],
 "--省略--": ""
}

またresourceNameにpeople/meを指定することで認可したユーザーのプロフィールが取得できます。meが自身のGoogle+IDのエイリアスということですね。

GET https://people.googleapis.com/v1/people/me

people.getBatchget

people.getの複数取得バージョンです。
resourceNamesパラメータに複数のresourceNameを指定します。

GET https://people.googleapis.com/v1/people:batchGet

e.g.
見やすさのためにURLデコードして記載しています。

GET https://people.googleapis.com/v1/people:batchGet?resourceNames=people/101136005779153122515&resourceNames=people/101136005779153122515

レスポンスはpeople.getと似たような感じなので省略します

people.connections.list

こちらは連絡先から一覧情報を取得するためのものです。
また、responseには連絡先情報とGoogle+へのリンクが表示されます。（連絡先とGoogle+情報の概要一覧が出てくる感じです）

GET https://people.googleapis.com/v1/{resourceName=people/*}/connections

resourceNameにはpeople/meしか指定できないと書かれています。
他人の連絡先みえたらまずいですからね。

※ただし2016/3/1現在バグってるみたいです。people/*にマッチしていればどんなresouceNameであれpeople/meとして扱われています。

e.g.

GET https://people.googleapis.com/v1/people/me/connections

response

{
 "connections": [
  {
   "resourceName": "people/c7216717323740958786",
   "etag": "fw5i0/N+AXQ=",
   "metadata": {
    "sources": [
     {
      "type": "CONTACT",
      "id": "6426ee2b8dfcd042"
     }
    ],
    "objectType": "PERSON"
   },
   "names": [
    {
     "metadata": {
      "primary": true,
      "source": {
       "type": "CONTACT",
       "id": "6426ee2b8dfcd042"
      }
     },
     "displayName": "連絡先に登録したユーザー",
     "givenName": "連絡先に登録したユーザー"
    }
   ]
  },
  "--省略--": ""
}

電話番号やアドレスは出ません。表示されるのはあくまで概要です。
詳細を取得するためにはresourceNameのpeople/CXXXXXXXをつかって先ほどのpeople.getを叩きます。
※getBatchgetが用意されているのは1件1件叩くのは非効率だからでしょうね。

e.g.

GET https://people.googleapis.com/v1/people/c7216717323740958786

response

{
 "resourceName": "people/c7216717323740958786",
 "etag": "bXmHGvSA/ms=",
 "metadata": {
  "sources": [
   {
    "type": "CONTACT",
    "id": "6426ee2b8dfcd042"
   }
  ],
  "objectType": "PERSON"
 },
 "names": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "CONTACT",
     "id": "6426ee2b8dfcd042"
    }
   },
   "displayName": "連絡先に登録したユーザー",
   "givenName": "連絡先に登録したユーザー"
  }
 ],
 "addresses": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "CONTACT",
     "id": "6426ee2b8dfcd042"
    }
   },
   "formattedValue": "住所！",
   "type": "work",
   "formattedType": "Work",
   "streetAddress": "住所！"
  }
 ],
 "emailAddresses": [
  {
   "metadata": {
    "primary": true,
    "source": {
     "type": "CONTACT",
     "id": "6426ee2b8dfcd042"
    }
   },
   "value": "[e-mail]",
   "type": "work",
   "formattedType": "Work"
  }
 ],
  "--省略-- ": ""
}

余談

今までのGoogleAPIのパターンではpeople/まで固定で{peopleId}部分が可変（キー）という書き方をしていたのですが本APIは{people/*}が可変という書き方をしているのでちょっと違和感がありますね。
またmaxResultsではなくpageSizeというパラメータで件数を制御しているのも違和感が。設計方針の変更なんでしょうかね。

参考サイト