pocket APIの使い方まとめ(サンプルコード付き)

更新日: 2015/09/02 [更新履歴]
公開日: 2014/06/24

後で読みたい記事をストックできるwebサービスのpocket。「あとでよむ」系のサービスとしては、日本で最大手と言ってもいいですよね。ブログに付けるソーシャルボタンは、これが定番になっています。そのpocketが提供するAPIを利用して、webサービスを作ったり、ブログにちょっとしたサブ機能を加えてみませんか？これからpocketのAPIを始める全ての人の助けになれたらと思い、その使い方をまとめてみました。

アプリケーションの登録

pocketのAPIを登録するには、まず「アプリケーションの登録」を行なう必要があります。「アプリケーションっていうとなんだか難しそう…」と思うかもしれませんが、なんてことはありません。PHPでプログラムを作るなら、「〜.php」がそのアプリケーションにあたります。例えば次のプログラムだって立派な(web)アプリケーションです。

PHP

<?php
	echo '私は立派なプログラムです。' ;

「アプリケーション登録」とは、ざっくり言えば「このPHPであなたのところのAPIを使わせて下さい」と伝える作業です。

アカウントを取得する

なお、APIを利用するには、前提としてpocketのアカウントを所有している必要があります。もし、まだの方は、pocketでアカウントを作成するか、またはGoogleのアカウントで代用することが可能です。

Pocket Sign Up: Pocketのアカウントを作成するためのページ。

Google アカウントの作成: Googleのアカウントを作成するためのページ。

アプリケーションを登録する

それではアプリケーションの登録を行なっていきましょう。登録するには、下記のリンクにアクセスして下さい。まだの場合は最初にログインが求められます。

My Applications: Pocketのアプリケーションを作成するためのページ。

My Applications

アクセスすると、「My Applications」というページに移動します。ここに、登録したアプリの一覧が表示されて、後から情報を編集したり、削除したりできます。まだ何も登録してないので空白ですよね。何はともあれ、まずはアプリケーションを登録してみましょう。「CREATE AN APPLICATION」をクリックして下さい。

Create an Application

それではアプリの情報を登録しましょう。最初は色々と機能を試すためのお試し登録でいいと思います。よろしければ上記のサンプル画像をそのまま真似して下さい。画像はクリックすると拡大して見ることができます。

登録する項目の説明

登録するアプリ情報の、各項目を説明していきます。不安な方は一度、目を通してみて下さい。

名前と概要

一番上から、まずアプリの名前と概要を入力します。例えば、人気サービスのTwilogだったら、名前が「Twilog」、概要は「Twitterをブログ形式で表示するwebサービス」となります。あなたが作成しようとしているサービスに合わせた情報を入力しましょう。ちなみに(生半可な)英語で入力しているのは、単純に日本語だと文字化けを起こしてしまうからです。

パーミッション(アプリの権限)

続いてパーミッションを設定します。パーミッションとは、「そのアプリがどんな権限を持っているか」です。Addは「アイテムの追加」、Modifyは「ストックしているアイテムの情報変更(タグの削除など)」、Retrieveは「ストックしているアイテムの読み取り」の権限をそれぞれ表します。

例えば、「ユーザーが今までにpocketしてきたアイテム(記事)をランダムで10個表示するサービス」だったら、権限は「アイテムの読み取り」だけで十分なので、Retrieveだけにチェックを付けて下さい。例えば、「ユーザーのタグを一括で削除するwebサービス」だったらRetrieveに加えてModifyにチェックを付ける必要がありますね。

まずは「機能を試すためのアプリ」なので、全部の権限にチェックを入れておきましょう。

ちょっと寄り道して…、誰もが利用しているTwitterを例にとってみると分かりやすいかもしれません。上記の画像はTwilogのアプリ認証画面です。赤枠で囲んである部分がパーミッションにあたります。これのpocket版だと思って下さい。

プラットフォーム

最後はプラットフォームの選択です。iPhoneアプリやAndroidアプリ、デスクトップアプリなど様々な種類がありますが、今回はインターネットブラウザ(web)で起動するお手軽なアプリを作ってみましょう。Webにチェックを入れて下さい。

全ての項目に問題がなければ、「I accept the Terms of Service(利用規約に同意しますか？)」にチェックを入れて、「CREATE APPLICATION」をクリックすれば登録完了です。

コンシューマーキーを確認する

無事、アプリケーションの登録に成功すると、先ほどのMy Applicationsのページに遷移し、登録したアプリが一覧に加わっているのを確認できますね！アプリ名の右にあるCONSUMER KEYを保存(メモ)して下さい。サンプルでは29123-af261164b5dc63e823fc922dの部分です。画像はクリックすると拡大することができます。

これは、pocket側が、APIを使っているのがあなたのプログラムだと識別するためのキーとなります。他人に知られないように、管理しておきましょう。

OAuth認証をする

それでは、早速、アプリ認証を行なって「アクセストークン」を取得してみましょう。pocketはOAuth2.0という認証形式を採用しています。公式ドキュメントは、下記のページにあります。

OAuth 2.0: OAuthの公式ウェブサイト。認証の仕組みが解説されています。「とりあえずプログラムを作ってみたい」という段階では、まだ読む必要はないと思います。プログラムを動かしてから読んだ方が分かりやすいはず…。

ドキュメントを読むよりも、何度かプログラムを起動し、体験して流れを掴む方が、圧倒的に分かりやすいと思います。その後、確認の意味で読むのがお勧めです。今は読まずに進んでしまって大丈夫です。

OAuth認証の仕組み

非常にざっくりとした内容なんですが…、pocketのアプリ認証の手順は下記のような感じです。

pocketからリクエストトークンを取得する。
ユーザーがそのリクエストトークンを持って、pocketの「アプリ認証画面」にアクセスする。
ユーザーがアプリを認証して、アプリがアクセストークンを受け取る。

下記ページに、pocketのアプリ認証の公式ドキュメントがあります。次項で紹介するサンプルプログラムは、このページの手順に沿っています。興味があったら、見比べてみて下さい。

Pocket Authentication API Documentation: Pocket Developers内のページ。OAuth認証の手順が解説されています。

サンプルプログラム

下記が、先ほど紹介した3つの手順を実行するOAuth認証のサンプルプログラムです。$consumer_keyと$redirect_uriを設定してから、アクセスしてみて下さい！$redirect_uriは基本的に変更する必要ありませんが、上手く動作しない場合は、URLを直接指定して下さいね。

PHP

<?php

	// 設定項目
	$consumer_key = '' ;																													// アプリ登録で取得したコンシューマーキー
	$redirect_uri = ( !isset($_SERVER['HTTPS']) || empty($_SERVER['HTTPS']) ? 'http://' : 'https://' ) . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] ;		// このプログラムを設置するURL
 
	// セッションスタート
	session_start() ;

	// HTML用
	$html = '' ;

	// アプリ認証から帰ってきた時([return=1]があるアクセス)の場合はアクセストークンを取得
	// [手順3] ユーザーがアプリを許可して、アプリがアクセストークンを受け取る、の部分
	if( isset($_GET['return']) && is_string($_GET['return']) && $_GET['return'] == 1 )
	{
		// セッションにリクエストトークンがない場合は不正と判断してエラー
		if( !isset($_SESSION['code']) || empty($_SESSION['code']) )
		{
			$error = 'セッションが上手く機能してないか、手動で[return=1]を付けてアクセスしてます…。' ;
		}

		// セッションにCSRF対策用の[state]がない場合は不正と判断してエラー
		elseif( !isset($_SESSION['state']) || empty($_SESSION['state']) )
		{
			$error = 'セッションが上手く機能してないかもしれません。' ;
		}

		// アクセストークンの取得
		else
		{
			// リクエスト用のコンテキストを作成
			$context = array(
				'http' => array(
					'method' => 'POST' ,
					'content' => http_build_query( array(
						'consumer_key' => $consumer_key ,
						'code' => $_SESSION['code'] ,
					) ) ,
				) ,
			) ;

			// CURLを使ってリクエスト
			$curl = curl_init() ;

			// オプションのセット
			curl_setopt( $curl , CURLOPT_URL , 'https://getpocket.com/v3/oauth/authorize' ) ;
			curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
			curl_setopt( $curl , CURLOPT_CUSTOMREQUEST , $context['http']['method'] ) ;			// メソッド
			curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
			curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
			curl_setopt( $curl , CURLOPT_POSTFIELDS , $context['http']['content'] ) ;			// リクエストボディ
			curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

			// 実行
			$res1 = curl_exec( $curl ) ;
			$res2 = curl_getinfo( $curl ) ;

			// 終了
			curl_close( $curl ) ;

			// 取得したデータ
			$body = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
			$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

			// 関数[pocket_get_query_syncer]を使って、GETパラメータ形式の文字列を配列に変換
			$query = pocket_get_query_syncer( $body ) ;
 
			// CSRF対策
			if( !isset($query['state']) || empty($query['state']) || $query['state'] != $_SESSION['state'] )
			{
				$error = 'セッションに保存してあるstateと、返ってきたstateの値が違います…。' ;
			}

			// アクセストークンが取得できない場合はエラー
			elseif( !isset($query['access_token']) || empty($query['access_token']) )
			{
				$error = 'アクセストークンを取得できませんでした…。' ;
			}

			else
			{
				// アクセストークンを変数に格納
				$access_token = $query['access_token'] ;

				// 出力する
				$html .=  '<h2>実行結果</h2>' ;
				$html .=  '<dl>' ;
				$html .=  	'<dt>ユーザーID</dt>' ;
				$html .=  		'<dd>' . $query['username'] . '</dd>' ;
				$html .=  	'<dt>アクセストークン</dt>' ;
				$html .=  		'<dd>' . $access_token . '</dd>' ;
				$html .=  '</dl>' ;
			}
		}

		// 出力する
		$html .= '<h2>取得したデータ</h2>' ;
		$html .= '<p>下記のデータを取得しました。</p>' ;
		$html .= 	'<h3>ボディ</h3>' ;
		$html .= 	'<p><textarea rows="8">' . $body . '</textarea></p>' ;
		$html .= 	'<h3>レスポンスヘッダー</h3>' ;
		$html .= 	'<p><textarea rows="8">' . $header . '</textarea></p>' ;

		// アプリケーション連携の解除
		$html .= '<h2>アプリケーション連携の解除</h2>' ;
		$html .= '<p>このアプリケーションとの連携は、下記設定ページで解除することができます。</p>' ;
		$html .= '<p><a href="https://getpocket.com/connected_applications" target="_blank">https://getpocket.com/connected_applications</a></p>' ;

		// セッション終了
		$_SESSION = array() ;
		session_destroy() ;
	}

	// [return=1]がないアクセス(初回アクセス)の場合
	// [手順1] pocketからリクエストトークンを取得する、の部分
	else
	{
		// CSRF対策
		session_regenerate_id( true ) ;
		$state = sha1( uniqid( mt_rand() , true ) ) ;
		$_SESSION['state'] = $state ;

		// リダイレクトURLにパラメータを追加
		$redirect_uri .= '?return=1' ;

		// リクエスト用のコンテキストを作成
		$context = array(
			'http' => array(
				'method' => 'POST' ,
				'content' => http_build_query( array(
					'consumer_key' => $consumer_key ,
					'redirect_uri' => $redirect_uri ,
					'state' => $state ,
				) ) ,
			)
		) ;

		// CURLを使ってリクエスト
		$curl = curl_init() ;

		// オプションのセット
		curl_setopt( $curl , CURLOPT_URL , 'https://getpocket.com/v3/oauth/request' ) ;
		curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
		curl_setopt( $curl , CURLOPT_CUSTOMREQUEST , $context['http']['method'] ) ;			// メソッド
		curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
		curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
		curl_setopt( $curl , CURLOPT_POSTFIELDS , $context['http']['content'] ) ;			// リクエストボディ
		curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

		// 実行
		$res1 = curl_exec( $curl ) ;
		$res2 = curl_getinfo( $curl ) ;

		// 終了
		curl_close( $curl ) ;

		// 取得したデータ
		$body = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
		$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

		// 関数[get_query_syncer]を使って、GETパラメータ形式の文字列を配列に変換
		$query = pocket_get_query_syncer( $body ) ;
 
		// リクエストトークンを取得できなければエラー
		if( !isset($query['code']) || empty($query['code']) )
		{
			$error = 'リクエストトークンが取得できませんでした。多分コンシューマーキーの設定が間違っています。' ;
		}
 
		// リクエストで送った[state]の値と、返って来た[state]の値が違ったらエラー
		elseif( !isset($query['state']) || empty($query['state']) || $state != $query['state'] )
		{
			$error = '不正なリクエスト、またはレスポンスです…。' ;
		}
		else
		{
			// セッションにリクエストトークンの値を格納しておく
			$_SESSION['code'] = $query['code'] ;
 
			// ユーザーをアプリ認証画面へアクセス(リダイレクト)させる
			// [手順2] ユーザーがそのリクエストトークンを持って、pocketの「アプリ認証画面」にアクセスする、の部分
			header( 'Location: https://getpocket.com/auth/authorize?request_token=' . $query['code'] . '&redirect_uri=' . $redirect_uri ) ;
		}
	}

	// エラー時の処理
	if( isset($error) || !empty($error) )
	{
		$html = '<p><mark>' . $error . '</mark>もう一度、認証をするには、<a href="' . explode( '?' , $_SERVER['REQUEST_URI'] )[0] . '">こちら</a>をクリックして下さい。</p>' ;
	}

	// GETクエリ形式の文字列を配列に変換する関数
	function pocket_get_query_syncer( $data = '' )
	{
		// 文字列を[&]で区切って配列に変換する
		$ary = explode( '&' , $data ) ;

		// [&]が含まれていない場合は終了
		if( 2 > count( $ary ) )
		{
			return false ;
		}

		// 文字列を配列に整形する
		foreach( $ary as $items )
		{
			$item = explode( '=' , $items ) ;
			$query[ $item[0] ] = $item[1] ;
		}

		// 返却
		return $query ;
	}

?>

<?php
	// ブラウザに[$html]を出力 (HTMLのヘッダーとフッターを付けましょう)
	echo $html ;
?>

OAuth認証を体験できるようにデモページを用意しました。認証時、読み取り権限、書き込み権限を要求していますが、これらは次章以降のデモで利用するためのもので、このアプリケーションが、あなたの操作なしにあなたのデータにアクセスすることはありません。

このコードの動作を確認する

認証の流れ

サンプルプログラムを利用した、アプリ認証の流れは次の通りです。確認しながら、少しずつ進んでみて下さい。

アプリ認証画面

プログラムにアクセスすると、アプリの認証画面に移動するので、「認可」をクリックして下さい。左側には、アプリ登録の際にしたパーミッションの設定が反映されています。画像はクリックすると拡大できます。

アクセストークンを確認する

「認可」をクリックすると、ブラウザにアクセストークンが表示されます。このアクセストークンを利用して、アプリ側はユーザーのデータに、設定したパーミッションのレベルに応じてアクセス(情報を読み取ったり、書き込んだり)することが可能になります。実際にwebサービスを作る場合は、このアクセストークンをデータベースなどに保存して管理することになります。

ユーザーデータの読み取り [Retrieve]

コンシューマーキーとアクセストークンを取得したので、ここからは実際に簡単なプログラムを一緒に作って、APIを利用していきましょう。まずはパーミッションで言うRetrieve(読み取り)の権限を利用してみます。Retrieveに関する公式ドキュメントは下記のページで確認できます。

Pocket API: Retrieving a User's Pocket Data: Retrieveのエンドポイントについての公式ドキュメント。

リクエスト方法

Retrieve権限を利用するためには、下記のURLにPOSTメソッドでリクエストを送ります。

POST https://getpocket.com/v3/get

パラメータ

どんなアイテム(pocketした記事)を、どれだけ読み込むかを、下記のパラメータで指定することができます。[]内が、指定するパラメータの値となります。

consumer_key: コンシューマーキー。
access_token: アクセストークン。
state: ステータスで絞り込む。; unread … 未読(デフォルト); archive … 既読; all … 全て
favorite: お気に入り状態で絞り込む。; 0 … お気に入りのアイテム; 1 … お気に入りじゃないアイテム
tag: タグの状態で絞り込む。; untagged_ … タグが付いてないアイテム; {タグ名} … このタグ名が付いたアイテム
contentType: メディアで絞り込む。; article … 通常の記事など; video … 動画コンテンツ; image … 画像コンテンツ
sort: アイテムのソート。; newest … 新しい順(デフォルト); oldest … 古い順; title … タイトル名順; site … アイテムのURL(ドメイン)名順
detailType: 取得するデータの内容。; simple … 最小限の内容のみ(デフォルト); complete … 全ての内容
search: キーワードで絞り込む。値にキーワードを指定する。
domain: ドメインで絞り込む。syncer.jp、https://syncer.jp、どちらの指定方法でも可。
since: 時間で絞り込む。UNIX TIMESTAMP形式で指定する。指定した日時以降に追加されたアイテムのみ取得する。
count: アイテムの取得件数。最大値は不明。著者の環境では5000件を指定しても取得できた。
offset: アイテムの取得開始位置。この数値分だけパスしてアイテムを取得する。

取得できるJSONデータ

リクエストに成功すると、下記のJSONデータを取得することができます。アイテムはlistプロパティに配列形式で格納されています。アイテムIDは主に「Modifyの権限」で利用することになります。

JSON

{"status":1,"complete":0,"list":{"548836533":{"item_id":"548836533","resolved_id":"548836533","given_url":"http:\/\/syncer.jp","given_title":"","favorite":"0","status":"0","time_added":"1426236203","time_updated":"1426236203","time_read":"0","time_favorited":"0","sort_id":0,"resolved_title":"Syncer | \u77e5\u8b58\u3001\u611f\u52d5\u3092\u307f\u3093\u306a\u3068\u540c\u671f(Sync)\u3059\u308b\u30d6\u30ed\u30b0","resolved_url":"http:\/\/syncer.jp\/","excerpt":"Syncer\u30b7\u30f3\u30ab\u30fc\u306fSync(\u540c\u671f)\u3068er(\u3059\u308b\u8005)\u3067\u300c\u77e5\u8b58\u3084\u611f\u52d5\u3092\u540c\u671f\u3059\u308b\u30d6\u30ed\u30b0\u300d\u3068\u3044\u3046\u610f\u5473\u306e\u9020\u8a9e\u3067\u3059\u3002\u307f\u306a\u3055\u3093\u3068\u5171\u306b\u9032\u5316(\u3057\u3093\u304b)\u3057\u3066\u3044\u304d\u305f\u3044\u3068\u3044\u3046\u601d\u3044\u3082\u8fbc\u3081\u3066\u307e\u3059\u3002\u307e\u305f\u6765\u305f\u304f\u306a\u3063\u305f\u3089\u3001Syncer\u3067\u691c\u7d22\u3057\u3066\u306d\uff01","is_article":"0","is_index":"1","has_video":"0","has_image":"1","word_count":"194","image":{"item_id":"548836533","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-what-is-the-hashtag_index.png?ti","width":"348","height":"211"},"images":{"1":{"item_id":"548836533","image_id":"1","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-what-is-the-hashtag_index.png?ti","width":"348","height":"211","credit":"","caption":""},"2":{"item_id":"548836533","image_id":"2","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-how-to-setting-email_index.png?ti","width":"348","height":"211","credit":"","caption":""},"3":{"item_id":"548836533","image_id":"3","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-how-to-setting-password_index.png?ti","width":"348","height":"211","credit":"","caption":""},"4":{"item_id":"548836533","image_id":"4","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-how-to-setting-caption_index.png?ti","width":"348","height":"211","credit":"","caption":""},"5":{"item_id":"548836533","image_id":"5","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-how-to-report-spam_index.png?ti","width":"348","height":"211","credit":"","caption":""},"6":{"item_id":"548836533","image_id":"6","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-how-to-setting-user-notification_index.png?ti","width":"348","height":"211","credit":"","caption":""},"7":{"item_id":"548836533","image_id":"7","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/instagram-site-map_index.png?ti","width":"348","height":"211","credit":"","caption":""},"8":{"item_id":"548836533","image_id":"8","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/js-how-to-processing-decimal-point_index.png?ti","width":"348","height":"211","credit":"","caption":""},"9":{"item_id":"548836533","image_id":"9","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/js-how-to-create-random-number_index.png?ti","width":"348","height":"211","credit":"","caption":""},"10":{"item_id":"548836533","image_id":"10","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/how-to-setting-double-click-event_index.png?ti","width":"348","height":"211","credit":"","caption":""},"11":{"item_id":"548836533","image_id":"11","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/labetter_index.png?ti","width":"348","height":"211","credit":"","caption":""},"12":{"item_id":"548836533","image_id":"12","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/age-checker_index.png?ti","width":"348","height":"211","credit":"","caption":""},"13":{"item_id":"548836533","image_id":"13","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-noise_index.png?ti","width":"348","height":"211","credit":"","caption":""},"14":{"item_id":"548836533","image_id":"14","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-negative-positive-reversal_index.png?ti","width":"348","height":"211","credit":"","caption":""},"15":{"item_id":"548836533","image_id":"15","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-blur_index.png?ti","width":"348","height":"211","credit":"","caption":""},"16":{"item_id":"548836533","image_id":"16","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-reversal_index.png?ti","width":"348","height":"211","credit":"","caption":""},"17":{"item_id":"548836533","image_id":"17","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-sepia-tone_index.png?ti","width":"348","height":"211","credit":"","caption":""},"18":{"item_id":"548836533","image_id":"18","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-gray-scale_index.png?ti","width":"348","height":"211","credit":"","caption":""},"19":{"item_id":"548836533","image_id":"19","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/canvas-how-to-make-mosaic_index.png?ti","width":"348","height":"211","credit":"","caption":""},"20":{"item_id":"548836533","image_id":"20","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/how-to-rotate-image-canvas_index.png?ti","width":"348","height":"211","credit":"","caption":""}}},"835248017":{"item_id":"835248017","resolved_id":"835248017","given_url":"http:\/\/wispyon.com\/themes-wordpress-7features\/","given_title":"","favorite":"0","status":"0","time_added":"1423144872","time_updated":"1423144872","time_read":"0","time_favorited":"0","sort_id":1,"resolved_title":"WordPress\u3092\u8d85\u3048\u308b!\u65b0\u30c6\u30fc\u30de\u30c7\u30b6\u30a4\u30f3\u306e7\u3064\u306e\u7279\u5fb4\u3092\u5927\u516c\u958b!SEO\u5bfe\u7b56\u3084\u30e1\u30f3\u30c6\u6027\u3092\u5411\u4e0a","resolved_url":"http:\/\/wispyon.com\/themes-wordpress-7features\/","excerpt":"\u3053\u306e\u30d6\u30ed\u30b0\u306eWordPress\u30c6\u30fc\u30de\uff08\u30c7\u30b6\u30a4\u30f3\u3084\u6a5f\u80fd\uff09\u3092\u30bc\u30ed\u304b\u3089\u4f5c\u308a\u306a\u304a\u3057\u307e\u3057\u305f\u3002\u81ea\u4f5c\u306f\u6628\u5e741\u6708\u306b\u6b21\u3044\u30672\u5ea6\u3081\u306a\u306e\u3067\u3001\u66f4\u306b\u8efd\u91cf\u5316\u30fb\u4fee\u6b63\u306e\u3057\u3084\u3059\u3055\u30fbSEO\u5bfe\u7b56\u3092\u5411\u4e0a\u3067\u304d\u305f\u3068\u601d\u3044\u307e\u3059\u3002\u305d\u306e\u7279\u5fb4\u30927\u3064\u306b\u308f\u3051\u3066\u7d39\u4ecb\u3057\u307e\u3059\u3002","is_article":"1","is_index":"0","has_video":"0","has_image":"1","word_count":"1717","images":{"2":{"item_id":"835248017","image_id":"2","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xwordpress-pc-themes0-80x60.png.pagespeed.ic.gjbbmx7DpS.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011\u65b0\u30c6\u30fc\u30de\u30c7\u30b6\u30a4\u30f3\u306796\u70b9\u9054\u6210\uff01SEO\u5bfe\u7b56\u30fb\u8efd\u91cf\u5316\u306a\u30697\u3064\u306e\u7279\u5fb4\u3092\u3055\u3089\u3057\u307e\u3059133 shares"},"3":{"item_id":"835248017","image_id":"3","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xlady-smartphone7-80x60.jpg.pagespeed.ic.qn-P4TgAtH.jpg","width":"0","height":"0","credit":"","caption":"159 shares"},"4":{"item_id":"835248017","image_id":"4","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xlady-macbookair-80x60.jpg.pagespeed.ic.eBIiAfqLr9.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011Theme Test Drive\u30d7\u30e9\u30b0\u30a4\u30f3\u3067\u30c6\u30fc\u30de\u4f5c\u6210\u304c\u6357\u308b\uff01\u30c6\u30b9\u30c8\u74b0\u5883\u4e0d\u898161 shares"},"5":{"item_id":"835248017","image_id":"5","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/themes-wordpress-7features3.png.pagespeed.ce.69JiG99QVZ.png","width":"209","height":"400","credit":"","caption":""},"6":{"item_id":"835248017","image_id":"6","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/themes-wordpress-7features2.png.pagespeed.ce.Ju3wi9nQlO.png","width":"640","height":"485","credit":"","caption":""},"7":{"item_id":"835248017","image_id":"7","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xlady-iphone3-80x60.jpg.pagespeed.ic.gY7BAvcSyO.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011Multi Device Switcher\u3067\u30b9\u30de\u30db\u30c6\u30fc\u30de\u81ea\u52d5\u5207\u66ff\uff01Android\u30bf\u30d6\u30ec\u30c3\u30c8\u5bfe\u5fdc\u65b9\u6cd5\u308229 shares"},"8":{"item_id":"835248017","image_id":"8","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xsmartphone-tablet-pc-detect1-80x60.jpg.pagespeed.ic.HhI7Q3jCf7.jpg","width":"0","height":"0","credit":"","caption":"245 shares"},"9":{"item_id":"835248017","image_id":"9","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xsns-count-cache2-0-80x60.png.pagespeed.ic.4ATUZvIg2-.jpg","width":"0","height":"0","credit":"","caption":"\u30b7\u30a7\u30a2\u6570\u306e\u9ad8\u901f\u53d6\u5f97\u306e\u6c7a\u5b9a\u7248\uff01WordPress\u30d7\u30e9\u30b0\u30a4\u30f3SNS Count Cache\u30a2\u30c3\u30d7\u30c7\u30fc\u30c8\u3067\u9032\u531641 shares"},"10":{"item_id":"835248017","image_id":"10","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xsns-button-original-80x60.png.pagespeed.ic.8brxRBFBtw.jpg","width":"0","height":"0","credit":"","caption":"274 shares"},"11":{"item_id":"835248017","image_id":"11","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/themes-wordpress-7features4.png.pagespeed.ce.qNwXwwft1b.png","width":"640","height":"376","credit":"","caption":""},"12":{"item_id":"835248017","image_id":"12","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xcat-jumping-80x60.jpg.pagespeed.ic.PATPpNnjjI.jpg","width":"0","height":"0","credit":"","caption":"331 shares"},"13":{"item_id":"835248017","image_id":"13","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xcat-single-80x60.jpg.pagespeed.ic.lpZYx4I1hP.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011\u56fa\u5b9a\u30da\u30fc\u30b8\u3067page.php\u3067\u306a\u304f\u6295\u7a3f\u8a18\u4e8b\u306esingle\u3092\u5171\u901a\u5229\u7528\u3059\u308b\u65b9\u6cd570 shares"},"14":{"item_id":"835248017","image_id":"14","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xlady_21-80x60.jpg.pagespeed.ic.G_GYiHIhNJ.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011\u30ab\u30c6\u30b4\u30ea\u30fb\u30bf\u30b0\u30da\u30fc\u30b8\u306e\u30bf\u30a4\u30c8\u30eb\u3068\u8aac\u660e\u6587\u3092\u30ab\u30b9\u30bf\u30de\u30a4\u30ba25 shares"},"15":{"item_id":"835248017","image_id":"15","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xbreadcrumb-lady2-80x60.jpg.pagespeed.ic.ri5L3BM1aL.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011\u30d1\u30f3\u304f\u305a\u30ea\u30b9\u30c8\u8a2d\u7f6e\u65b9\u6cd5\uff01\u30d7\u30e9\u30b0\u30a4\u30f3\u4e0d\u8981\u3002\u8907\u6570\u30ab\u30c6\u30b4\u30ea\u304b\u3089\u9078\u629e\u53ef\u306b80 shares"},"16":{"item_id":"835248017","image_id":"16","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xmicrodata-schema-80x60.png.pagespeed.ic.pVpZMPIM2C.jpg","width":"0","height":"0","credit":"","caption":"25 shares"},"17":{"item_id":"835248017","image_id":"17","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xlady-time-80x60.jpg.pagespeed.ic.gzqVpY8m0n.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011\u516c\u958b\u65e5\u3068\u6700\u7d42\u66f4\u65b0\u65e5\u306e\u8868\u793a\u65b9\u6cd5\uff01\u30ea\u30c3\u30c1\u30b9\u30cb\u30da\u30c3\u30c8\u3067SEO\u5bfe\u7b56\u308227 shares"},"18":{"item_id":"835248017","image_id":"18","src":"http:\/\/wispyon.com\/wp\/wp-content\/uploads\/xlady-customfields1-80x60.jpg.pagespeed.ic.IcAcS7G89G.jpg","width":"0","height":"0","credit":"","caption":"\u3010WordPress\u3011\u30ab\u30b9\u30bf\u30e0\u30d5\u30a3\u30fc\u30eb\u30c9\u8a2d\u7f6e\u3067All in One SEO\u3082\u4e0d\u8981\u306b\uff01\u30d7\u30e9\u30b0\u30a4\u30f3\u306a\u3057\u3067287 shares"}}}},"error":null,"search_meta":{"search_type":"normal"},"since":1437723315}

各プロパティの説明

取得できるJSONの各プロパティは次の内容となっています。

status: リクエストの結果(1なら成功)。
item_id: アイテムID。
favorite: 1ならお気に入り状態。
list->status: 0=未読、1=期読。
time_added: pocketした日時。
time_updated: アイテムを更新した日時。
time_read: アイテムを既読にした日時。
time_favorited: アイテムをお気に入りにした日時。
resolved_title: ページタイトル。
resolved_url: ページURL。
excerpt: ページの概要。
is_article: 1なら記事。
has_video: 1なら動画が含まれる。
has_image: 1なら画像が含まれる。
word_count: アイテムに含まれる文字数。ただし、英語サイトのため、日本語ページではほとんど合っていない…。

サンプルプログラム

以上を踏まえたサンプルプログラムが下記です。$consumer_key、$access_tokenを設定してアクセスするだけで起動します。パラメータ部分を連想配列形式で指定して、色々と試してみて下さいね！

PHP

<?php

	// 設定項目
	$consumer_key = '' ;	// コンシューマーキー
	$access_token = '' ;	// アクセストークン
	$request_url = 'https://getpocket.com/v3/get' ;		// リクエストURL
	$request_method = 'POST' ;							// メソッド

	// パラメーター
	$params = array(
		'state' => 'unread' ,						// 未読の記事のみ
		'count' => 10 ,								// 記事10件
		'sort' => 'newest' ,						// 新しい順
		'since' => strtotime( '2013/1/1' ) ,		// 2013/1/1以降
		'detailType' => 'complete' ,				// 詳しいデータ
	) ;
 
	// パラメーターにコンシューマーキーとアクセストークンを追加
	$params = array_merge( $params , array( 'consumer_key' => $consumer_key , 'access_token' => $access_token , ) ) ;

	// コンテキスト
	$context = array(
		'http' => array(
			'method' => $request_method ,
			'content' => http_build_query( $params ) ,
		)
	) ;

	// アイテムデータをJSON形式で取得する (CURLを使用)
	$curl = curl_init() ;

	// オプションのセット
	curl_setopt( $curl , CURLOPT_URL , $request_url ) ;
	curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
	curl_setopt( $curl , CURLOPT_CUSTOMREQUEST , $context['http']['method'] ) ;			// メソッド
	curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
	curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
	curl_setopt( $curl , CURLOPT_POSTFIELDS , $context['http']['content'] ) ;			// リクエストボディ
	curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

	// 実行
	$res1 = curl_exec( $curl ) ;
	$res2 = curl_getinfo( $curl ) ;

	// 終了
	curl_close( $curl ) ;

	// 取得したデータ
	$json = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
	$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

	// HTML用
	$html = '' ;

	// JSONデータをオブジェクト形式に変換する
	$obj = json_decode( $json ) ;

	// エラー判定
	if( !isset($obj->list) )
	{
		$html .= '<p>データを取得できませんでした…。設定を再確認して下さい。</p>' ;
	}
	else
	{
		// HTMLを作成
		$html .= '<h2>実行結果</h2>' ;

		// 個々のアイテムを出力する
		foreach( $obj->list as $item )
		{
			// 各データの整理
			$id = $item->item_id ;									// アイテムのID
			$title = $item->resolved_title ;						// アイテムのタイトル
			$url = $item->resolved_url ;							// アイテムのURL
			$fav = ( $item->favorite == 1 ) ? '★ ' : '' ;			// お気に入りにしているか？
			$date = $item->time_added ;								// pocketした日付(ついでに整形)

			// 日付を整形
			$date = date( 'Y/m/d H:i' , $date ) ;

			// ブラウザに出力
			$html .= '<dl>' ;
			$html .= 	'<dt>アイテムID</dt>' ;
			$html .= 		'<dd>' . $id . '</dd>' ;
			$html .= 	'<dt>タイトル</dt>' ;
			$html .= 		'<dd>' . $fav . $title . '</dd>' ;
			$html .= 	'<dt>URLアドレス</dt>' ;
			$html .= 		'<dd><a href="' . $url . '" target="_blank">' . $url . '</a></dd>' ;
			$html .= 	'<dt>登録した日付</dt>' ;
			$html .= 		'<dd>' . $date . '</dd>' ;

			// 画像
			if( isset( $item->image->src ) && !empty( $item->image->src ) )
			{
				$html .= 	'<dt>イメージ</dt>' ;
				$html .= 		'<dd><img class="_img" src="' . $item->image->src . '"></dd>' ;
			}

			$html .= '</dl>' ;
		}
	}

	// 取得したデータ
	$html .= '<h2>取得したデータ</h2>' ;
	$html .= '<p>下記のデータを取得できました。</p>' ;
	$html .= 	'<h3>JSON</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $json . '</textarea></p>' ;
	$html .= 	'<h3>レスポンスヘッダー</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $header . '</textarea></p>' ;

	// アプリケーション連携の解除
	$html .= '<h2>アプリケーション連携の解除</h2>' ;
	$html .= '<p>このアプリケーションとの連携は、下記設定ページで解除することができます。</p>' ;
	$html .= '<p><a href="https://getpocket.com/connected_applications" target="_blank">https://getpocket.com/connected_applications</a></p>' ;

?>

<?php
	// ブラウザに[$html]を出力 (HTMLのヘッダーとフッターを付けましょう)
	echo $html ;
?>

このコードの動作を確認する

プログラムの実行結果

サンプルプログラムを実行すると、これまでにpocketしたアイテムのデータが出力されます。一度プログラムが正常に起動するのを確認したら、リクエストするパラメータを変更したりして、感覚を掴んでみて下さいね。画像はクリックで拡大できます。

特定のタグで検索する

例えば、タグでアイテムを検索したい場合、パラメータを次のように変更します。hatebumanというタグを付けたアイテムだけが出力されます。

PHP

// パラメーター
$params = array(
	'state' => 'all' ,			// 未読・既読を指定しない
	'tag' => 'hatebuman' ,		// タグ名
) ;

特定のキーワードで検索する

例えば、キーワードでアイテムを検索したい場合は、パラメータを次のように変更して下さい。「はてブマン」というキーワードをコンテンツに含んだアイテムだけが出力されます。ちなみに、タグやキーワードは複数指定ができません。

PHP

// パラメーター
$params = array(
	'state' => 'all' , 				// 未読・既読を指定しない
	'search' => 'はてブマン' ,			// タグ名
) ;

お気に入りにしたアイテムのみを検索する

お気に入りにしたアイテムのみを検索したい場合は、パラメータを下記のように変更して下さいね！

PHP

// パラメーター
$params = array(
	'state' => 'all' , 		// 未読・既読を指定しない
	'favorite' => 1 ,			// お気に入りフラグ
) ;

アイテム総数を取得

例えば、「そのユーザーがこれまでにpocketした総アイテム数」を表示させたい場合は、下記のようにデータを取得します。サンプルの29行目に挿入して下さい。正確には「このリクエストで取得したアイテム数」なので、countパラメータは指定しないで下さい。サンプルだと9行目で10と指定してます。

PHP

// 全アイテム数
$all = count( (array)$obj->list ) ;
 
// 全アイテム数を出力
echo '<p>総アイテム数：' . $all . '</p>' ;

活用のアイデア

Retrieveを使えばどんな機能を実現できるか？そのアイデアを紹介します。

今までのアイテムをランダムで表示

ユーザーが今までにpocketしたアイテムの中から、ランダムで10件だけ表示するwebサービス、「ランダムpocket君(仮)」というプログラムを作ってみましょう。下記はサンプルコードです。アクセスするごとに、あなたが登録しているアイテムが10件、ランダムで表示されると思います。実際にはアイテム数が500個、1000個、5000個…と多くなるとそれだけ処理に負荷がかかるので、1日ごとに1回だけランダムでアイテムを抽出する、といったような仕組み作りが必要だと思います。json_decode()の第2引数にtrueを指定すると、JSONデータをオブジェクトではなく、連想配列形式に変換することができます。

PHP

<?php

	// 設定項目
	$consumer_key = '' ;	// コンシューマーキー
	$access_token = '' ;	// アクセストークン
	$request_url = 'https://getpocket.com/v3/get' ;		// リクエストURL
	$request_method = 'POST' ;							// メソッド

	// パラメーター
	$params = array(
		'state' => 'all' ,							// 未読の記事のみ
	) ;
 
	// パラメーターにコンシューマーキーとアクセストークンを追加
	$params = array_merge( $params , array( 'consumer_key' => $consumer_key , 'access_token' => $access_token , ) ) ;

	// コンテキスト
	$context = array(
		'http' => array(
			'method' => $request_method ,
			'content' => http_build_query( $params ) ,
		)
	) ;

	// アイテムデータをJSON形式で取得する (CURLを使用)
	$curl = curl_init() ;

	// オプションのセット
	curl_setopt( $curl , CURLOPT_URL , $request_url ) ;
	curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
	curl_setopt( $curl , CURLOPT_CUSTOMREQUEST , $context['http']['method'] ) ;			// メソッド
	curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
	curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
	curl_setopt( $curl , CURLOPT_POSTFIELDS , $context['http']['content'] ) ;			// リクエストボディ
	curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

	// 実行
	$res1 = curl_exec( $curl ) ;
	$res2 = curl_getinfo( $curl ) ;

	// 終了
	curl_close( $curl ) ;

	// 取得したデータ
	$json = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
	$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

	// HTML用
	$html = '' ;

	// JSONデータをオブジェクトではなく、連想配列形式に変換する
	$array = json_decode( $json , true ) ;

	// エラー判定
	if( !isset($array['list']) )
	{
		$html .= '<p>データを取得できませんでした…。設定を再確認して下さい。</p>' ;
	}

	// アイテム個数が15件以下の場合はエラー
	elseif( 15 > $array['list'] )
	{
		$html .= "もっとpocketしてから来て下さい!!";
	}

	else
	{
		// アイテムリストの配列を変数に格納
		$item_list = $array['list'] ;
 
		// アイテム数を調べる
		$item_count = count( $item_list ) ;

		// アイテム配列の中から、ランダムで10個のキーを取得
		$random_list = array_rand( $item_list ,10 ) ;
 
		// HTMLを作成
		$html .= '<h2>実行結果</h2>' ;
		$html .= '<p>登録しているアイテムの中からランダムで10個のアイテムをピックアップしました。もう一度試すには、<a href="' . explode( '?' , $_SERVER['REQUEST_URI'] )[0] . '">こちら</a>をクリックして下さい。</p>' ;

		// 選ばれたキーのアイテムを出力する
		foreach( $random_list as $key )
		{
			// データが揃ってなければパス
			if( !isset($item_list[ $key ]['item_id']) || !isset($item_list[ $key ]['resolved_title']) || !isset($item_list[ $key ]['resolved_url']) || !isset($item_list[ $key ]['favorite']) || !isset($item_list[ $key ]['time_added']) )
			{
				continue ;
			}

			// 各データの整理
			$id = $item_list[ $key ]['item_id'] ;								// アイテムのID
			$title = $item_list[ $key ]['resolved_title'] ;						// アイテムのタイトル
			$url = $item_list[ $key ]['resolved_url'] ;							// アイテムのURL
			$fav = ( $item_list[ $key ]['favorite']== 1 ) ? '★ ' : '' ;		// お気に入りにしているか？
			$date = $item_list[ $key ]['time_added'] ;							// pocketした日付

			// 日付を整形
			$date = date( 'Y/m/d H:i' , $date ) ;
  
			// ブラウザに出力
			$html .= '<dl>' ;
			$html .= 	'<dt>アイテムID</dt>' ;
			$html .= 		'<dd>' . $id . '</dd>' ;
			$html .= 	'<dt>タイトル</dt>' ;
			$html .= 		'<dd>' . $fav . $title . '</dd>' ;
			$html .= 	'<dt>URLアドレス</dt>' ;
			$html .= 		'<dd><a href="' . $url . '" target="_blank">' . $url . '</a></dd>' ;
			$html .= 	'<dt>登録した日付</dt>' ;
			$html .= 		'<dd>' . $date . '</dd>' ;

			// 画像
			if( isset( $item_list[ $key ]['image']['src'] ) && !empty( $item_list[ $key ]['image']['src'] ) )
			{
				$html .= 	'<dt>イメージ</dt>' ;
				$html .= 		'<dd><img class="_img" src="' . $item_list[ $key ]['image']['src'] . '"></dd>' ;
			}

			$html .= '</dl>' ;
		}
	}

	// 取得したデータ
	$html .= '<h2>取得したデータ</h2>' ;
	$html .= '<p>下記のデータを取得できました。</p>' ;
	$html .= 	'<h3>JSON</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $json . '</textarea></p>' ;
	$html .= 	'<h3>レスポンスヘッダー</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $header . '</textarea></p>' ;

	// アプリケーション連携の解除
	$html .= '<h2>アプリケーション連携の解除</h2>' ;
	$html .= '<p>このアプリケーションとの連携は、下記設定ページで解除することができます。</p>' ;
	$html .= '<p><a href="https://getpocket.com/connected_applications" target="_blank">https://getpocket.com/connected_applications</a></p>' ;

?>

<?php
	// ブラウザに[$html]を出力 (HTMLのヘッダーとフッターを付けましょう)
	echo $html ;
?>

このコードの動作を確認する

アイテムの追加 [Add]

前章では、ユーザーがpocketしたアイテムを読み込む方法を紹介しました。今回は、PHPプログラムを通して、ユーザーのリストにアイテムを追加してみましょう。パーミッションでいうAdd(書き込み)の権限を利用します。公式ドキュメントは下記ページをご参考下さい。

Pocket API: Adding Items to Pocket: Addのエンドポイントについての公式ドキュメント。

リクエスト方法

Add権限を利用してアイテムを追加するには、下記のURLにPOSTメソッドでリクエストを送ります。

POST https://getpocket.com/v3/add

パラメータ

アイテム追加のリクエストを送る際は、下記のパラメータを送信することができます。Addの場合、一度に1つのアイテムしか追加することができません。一度に複数のアイテムを追加したい場合は、後述の「Modifyの権限」を利用することになります。

consumer_key: コンシューマーキー。
access_token: アクセストークン。
url: 追加するアイテムのURL。
title: アイテムのタイトル。ページにタイトルが設定されていない場合のみ反映される。
tags: アイテムのタグ。複数指定する場合は半角カンマ(,)で区切る。

取得できるJSONデータ

リクエストが成功すると、下記のJSONデータを取得することができます。アイテムを追加するのが目的なら、「JSONデータを取得する必要はないんじゃないか？」と思うかもしれませんが、成功判定や、結果表示をする場合に便利ですね。

JSON

{"item":{"item_id":"649254465","normal_url":"http:\/\/syncer.jp\/pocket-api-matome","resolved_id":"649254465","extended_item_id":"649254465","resolved_url":"http:\/\/syncer.jp\/pocket-api-matome","domain_id":"16802050","origin_domain_id":"16802050","response_code":"200","mime_type":"text\/html","content_length":"22250","encoding":"utf-8","date_resolved":"2015-07-22 21:10:14","date_published":"0000-00-00 00:00:00","title":"pocket API\u306e\u4f7f\u3044\u65b9\u307e\u3068\u3081(\u30b5\u30f3\u30d7\u30eb\u30b3\u30fc\u30c9\u4ed8\u304d)","excerpt":"\u5f8c\u3067\u8aad\u307f\u305f\u3044\u8a18\u4e8b\u3092\u30b9\u30c8\u30c3\u30af\u3067\u304d\u308bweb\u30b5\u30fc\u30d3\u30b9\u306epocket\u3002\u300c\u3042\u3068\u3067\u3088\u3080\u300d\u7cfb\u306e\u30b5\u30fc\u30d3\u30b9\u3068\u3057\u3066\u306f\u3001\u65e5\u672c\u3067\u6700\u5927\u624b\u3068\u8a00\u3063\u3066\u3082\u3044\u3044\u3067\u3059\u3088\u306d\u3002\u30d6\u30ed\u30b0\u306b\u4ed8\u3051\u308b\u30bd\u30fc\u30b7\u30e3\u30eb\u30dc\u30bf\u30f3\u306f\u3001\u3053\u308c\u304c\u5b9a\u756a\u306b\u306a\u3063\u3066\u3044\u307e\u3059\u3002","word_count":"5716","innerdomain_redirect":"0","login_required":"0","has_image":"1","has_video":"0","is_index":"0","is_article":"0","used_fallback":"1","lang":"ja","authors":[],"images":{"1":{"item_id":"649254465","image_id":"1","src":"http:\/\/syncer.jp\/static\/images\/eyecatch\/post\/pocket-api-matome_product.png","width":"638","height":"259","credit":"","caption":""},"2":{"item_id":"649254465","image_id":"2","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-regist-account.png","width":"538","height":"329","credit":"","caption":"pocket\u306e\u30ed\u30b0\u30a4\u30f3\u753b\u9762"},"3":{"item_id":"649254465","image_id":"3","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-my-applications.png","width":"500","height":"375","credit":"","caption":"pocket\u306e\u30a2\u30d7\u30ea\u30b1\u30fc\u30b7\u30e7\u30f3\u7ba1\u7406\u753b\u9762"},"4":{"item_id":"649254465","image_id":"4","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-application-input.png","width":"442","height":"520","credit":"","caption":"pocket\u306e\u30a2\u30d7\u30ea\u30b1\u30fc\u30b7\u30e7\u30f3\u767b\u9332\u30d5\u30a9\u30fc\u30e0"},"5":{"item_id":"649254465","image_id":"5","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-input-application-02.png","width":"500","height":"176","credit":"\u30a2\u30d7\u30ea\u306e\u6a29\u9650","caption":"\u30d1\u30fc\u30df\u30c3\u30b7\u30e7\u30f3"},"6":{"item_id":"649254465","image_id":"6","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_twilog-permission.png","width":"538","height":"393","credit":"","caption":"Twitter\u306e\u30a2\u30d7\u30ea\u8a8d\u8a3c"},"7":{"item_id":"649254465","image_id":"7","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-input-application-03.png","width":"500","height":"291","credit":"","caption":"\u30d7\u30e9\u30c3\u30c8\u30d5\u30a9\u30fc\u30e0"},"8":{"item_id":"649254465","image_id":"8","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_my-application-after-regist.png","width":"538","height":"240","credit":"","caption":""},"9":{"item_id":"649254465","image_id":"9","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-application-authentication.png","width":"538","height":"347","credit":"","caption":"pocket\u306e\u30a2\u30d7\u30ea\u8a8d\u8a3c\u753b\u9762"},"10":{"item_id":"649254465","image_id":"10","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-retrieve-json-data.png","width":"538","height":"421","credit":"","caption":"\u30d7\u30ed\u30b0\u30e9\u30e0\u306e\u5b9f\u884c\u7d50\u679c"},"11":{"item_id":"649254465","image_id":"11","src":"http:\/\/syncer.jp\/static\/images\/dummy\/lazyload-490-382.png","width":"490","height":"382","credit":"","caption":"\u30e9\u30f3\u30c0\u30e0\u8868\u793a\u306e\u30a4\u30e1\u30fc\u30b8"},"12":{"item_id":"649254465","image_id":"12","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_random-pocket.png","width":"500","height":"375","credit":"","caption":""},"13":{"item_id":"649254465","image_id":"13","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_rocketrss.png","width":"500","height":"375","credit":"","caption":""},"14":{"item_id":"649254465","image_id":"14","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_lisgo.png","width":"500","height":"375","credit":"","caption":""},"15":{"item_id":"649254465","image_id":"15","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pinpocket.png","width":"500","height":"375","credit":"","caption":""},"16":{"item_id":"649254465","image_id":"16","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_ifttt-sample.png","width":"500","height":"375","credit":"","caption":""},"17":{"item_id":"649254465","image_id":"17","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_pocket-hatebu-webhook.png","width":"500","height":"226","credit":"","caption":"Web Hook\u306e\u8a2d\u5b9a"},"18":{"item_id":"649254465","image_id":"18","src":"http:\/\/syncer.jp\/strage\/api\/pocket-api-matome\/images\/id54_hatebu-pocket-connect-sample.png","width":"500","height":"375","credit":"","caption":"\u5229\u7528\u3057\u305f\u30a4\u30e1\u30fc\u30b8"}},"videos":[],"resolved_normal_url":"http:\/\/syncer.jp\/pocket-api-matome","given_url":"https:\/\/syncer.jp\/pocket-api-matome"},"status":1}

サンプルプログラム

以上を踏まえたサンプルプログラムが下記です。$consumer_key、$access_tokenを設定してアクセスするだけで起動します。起動後、自分のリストに指定したアイテム(URL)が加わっているかを確認してみて下さいね。サンプルデモはあなた自身のpocketの操作になるので、お試しになる場合はご注意下さい。

PHP

<?php

	// 設定項目
	$consumer_key = '' ;	// コンシューマーキー
	$access_token = '' ;	// アクセストークン
	$request_url = 'https://getpocket.com/v3/add' ;		// リクエストURL
	$request_method = 'POST' ;							// メソッド

	// パラメーター
	$params = array(
		'url' => 'https://syncer.jp/pocket-api-matome' ,		// 追加するURL
		'tags' => 'test,すぐ消す' ,							// アイテムに付けるタグ
	) ;
 
	// パラメーターにコンシューマーキーとアクセストークンを追加
	$params = array_merge( $params , array( 'consumer_key' => $consumer_key , 'access_token' => $access_token , ) ) ;

	// コンテキスト
	$context = array(
		'http' => array(
			'method' => $request_method ,
			'content' => http_build_query( $params ) ,
		)
	) ;

	// アイテムデータをJSON形式で取得する (CURLを使用)
	$curl = curl_init() ;

	// オプションのセット
	curl_setopt( $curl , CURLOPT_URL , $request_url ) ;
	curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
	curl_setopt( $curl , CURLOPT_CUSTOMREQUEST , $context['http']['method'] ) ;			// メソッド
	curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
	curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
	curl_setopt( $curl , CURLOPT_POSTFIELDS , $context['http']['content'] ) ;			// リクエストボディ
	curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

	// 実行
	$res1 = curl_exec( $curl ) ;
	$res2 = curl_getinfo( $curl ) ;

	// 終了
	curl_close( $curl ) ;

	// 取得したデータ
	$json = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
	$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

	// HTML用
	$html = '' ;

	// JSONデータをオブジェクト形式に変換する
	$obj = json_decode( $json ) ;

	// エラー判定
	if( !isset($obj->status) || !$obj->status )
	{
		$html .= '<p>アイテムの追加に失敗しました…。</p>' ;
	}
	else
	{
		// HTMLを作成
		$html .= '<h2>実行結果</h2>' ;
		$html .= '<p>下記のアイテムを追加しました！自分の<a href="https://getpocket.com/" target="_blank">マイリスト</a>を確認してみて下さい。</p>' ;

		// 各データの整理
		$id = $obj->item->item_id ;									// アイテムのID
		$title = $obj->item->title ;								// アイテムのタイトル
		$url = $obj->item->resolved_url ;							// アイテムのURL

		// ブラウザに出力
		$html .= '<dl>' ;
		$html .= 	'<dt>アイテムID</dt>' ;
		$html .= 		'<dd>' . $id . '</dd>' ;
		$html .= 	'<dt>タイトル</dt>' ;
		$html .= 		'<dd>' . $title . '</dd>' ;
		$html .= 	'<dt>URLアドレス</dt>' ;
		$html .= 		'<dd><a href="' . $url . '" target="_blank">' . $url . '</a></dd>' ;

		// 画像
		if( isset( $obj->item->image->src ) && !empty( $obj->item->image->src ) )
		{
			$html .= 	'<dt>イメージ</dt>' ;
			$html .= 		'<dd><img class="_img" src="' . $obj->item->image->src . '"></dd>' ;
		}

		$html .= '</dl>' ;
	}

	// 取得したデータ
	$html .= '<h2>取得したデータ</h2>' ;
	$html .= '<p>下記のデータを取得できました。</p>' ;
	$html .= 	'<h3>JSON</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $json . '</textarea></p>' ;
	$html .= 	'<h3>レスポンスヘッダー</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $header . '</textarea></p>' ;

	// アプリケーション連携の解除
	$html .= '<h2>アプリケーション連携の解除</h2>' ;
	$html .= '<p>このアプリケーションとの連携は、下記設定ページで解除することができます。</p>' ;
	$html .= '<p><a href="https://getpocket.com/connected_applications" target="_blank">https://getpocket.com/connected_applications</a></p>' ;

?>

<?php
	// ブラウザに[$html]を出力 (HTMLのヘッダーとフッターを付けましょう)
	echo $html ;
?>

このコードの動作を確認する

活用のアイデア

Addを使えば、webサービス内に、オリジナルの「あとで読む」ボタンを設置することが可能ですが、それだけでは普通ですよね…。次のような機能が、例えばブログにあったら面白いんじゃないでしょうか？

アイテムの変更 [Modify]

Retrieve(アイテムの読み込み)、Add(アイテムの追加)と、紹介してきました。最後は、pocketのAPIの中でも、一番強力な権限、Modify権限でAPIを利用してみましょう！公式ドキュメントは下記のページにあります。

Pocket API: Modifying a User's Pocket Data: Modifyのエンドポイントについての公式ドキュメント。

リクエスト方法

Modify権限を利用してアイテムを変更するには、下記のURLにPOSTメソッドでリクエストを送ります。

POST https://getpocket.com/v3/send

パラメータ

このModify権限のリクエストには、ちょっとクセがあります。少しずつ説明していきますね。まず、基本となるリクエストパラメータは次の3つです。

consumer_key: コンシューマーキー。
access_token: アクセストークン。
actions: アクションをJSONで指定する。

actions

actionsとは…？

actionsには、アイテムを変更するために用意された様々なアクションを、JSON形式で指定することができます。1つのアクションには複数のパラメータがあり、それらをセットで1まとめにしてJSONにする必要があるんです。言葉で言っても分からないのでサンプルを…。

例えば、「IDが999999のアイテムを既読状態にする」を実行するには、actionsの値に次のようにJSONデータを文字列で指定します。

JSON

[
{
"action": "archive",
"item_id": "999999",
"time": "1403449200"
}
]

actionのarchiveが「既読にするアクション」を表していて、item_idでアイテムのIDを、timeで変更の記録時間を指定しているわけです。これらを上記のような1まとめのJSONデータにして、actionsパラメータに指定する形になります。

Modifyでは1度に複数のアクションを指定することができて、その場合は次のように指定します。IDが999999と、888888の記事を1回のリクエストで既読状態にする場合のサンプルです。

JSON

[
{
"action": "archive",
"item_id": "999999",
"time": "1403449200"
},
{
"action": "archive",
"item_id": "888888",
"time": "1403449200"
}
]

[]の中に、半角カンマ(,)で区切った2つのJSONデータを含める形です。さて、これらのJSONデータは、いちいち文字列として書き出すのは大変なので、PHPの場合だったら、json_encode()という関数で配列から変換するのが便利です。例えば、上記のサンプルの場合、次のようになります。

PHP

// 多次元の連想配列を用意する
$action = array(		// 2つの配列を覆う配列が[〜]の部分
 
  array(				// 999999を既読にするアクション
    'action' => 'archive' ,
    'item_id' => '999999' ,
    'time' => '1403449200' ,
  ) ,
  array(  //888888を既読にするアクション
    "action" => 'archive' ,
    "item_id" => '888888' ,
    "time" => '1403449200' ,
  ) ,
 
);
 
// 多次元の連想配列をJSONデータに変換する
$json = json_encode( $action ) ;

このようにして、先ほどサンプルで紹介したJSONデータを作成することができます。これなら、PHPに標準で備わっている配列の追加や削除といった処理をした後、最後にjson_encode()でJSONデータに変換すればいいだけだから簡単ですよね！

パラメータ

それでは、Modifyのactionsに指定できるパラメータを紹介していきます。Addでは1回のリクエストにつき、1つしかできなかった「アイテムの追加」が、Modifyの場合は1度に何件でも指定することができます。

アイテムの追加: action … addを指定; url … アイテムのURL; tags … 付与するタグ(複数の場合は半角カンマ[,]で区切る); time … 記録する変更時間; title … アイテムのタイトル
既読にする: action … archiveを指定; item_id … アイテムのID; time … 記録する変更時間
未読にする: action … readdを指定; item_id … アイテムのID; time … 記録する変更時間
お気に入りにする: action … favoriteを指定; item_id … アイテムのID; time … 記録する変更時間
お気に入りを解除: action … unfavoriteを指定; item_id … アイテムのID; time … 記録する変更時間
アイテムの削除: action … deleteを指定; item_id … アイテムのID; time … 記録する変更時間
タグの追加: action … tags_addを指定; item_id … アイテムのID; tags … 追加するタグ(複数の場合は半角カンマ[,]で区切る); time … 記録する変更時間
タグの削除: action … tags_removeを指定; item_id … アイテムのID; tags … 削除するタグ(複数の場合は半角カンマ[,]で区切る); time … 記録する変更時間
タグの一新: action … tags_replaceを指定; item_id … アイテムのID; tags … 新しく設定するタグ(複数の場合は半角カンマ[,]で区切る); time … 記録する変更時間
タグの全削除: action … tags_clearを指定; item_id … アイテムのID; time … 記録する変更時間
タグのリネーム: action … tag_renameを指定; item_id … アイテムのID; old_tag … リネーム前のタグ; new_tag … リネーム後のタグ; time … 記録する変更時間

例えば、pocketのID:999999のアイテムの、hatebumanというタグをfunassyiに変換するには、次のようにactionsのパラメータを作成します。

PHP

// 多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'tag_rename' ,
		'item_id' => '999999' ,
		'old_tag' => 'hatebuman' ,
		'new_tag' => 'funassyi' ,
	) ,
) ;
 
// 多次元の連想配列をJSONデータに変換する
$json = json_encode( $action ) ;

はたまた、pocketのID:888888のアイテムの既読状態を未読状態に直すには、次のようにactionsのパラメータを作成します。

PHP

// 多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'readd' ,
		'item_id' => '999999' ,
	),
);
 
// 多次元の連想配列をJSONデータに変換する
$json = json_encode( $action ) ;

もちろん、2つのアクションを同時に指定することも可能です。配列の中身を随時、増やせばいいだけですねー。

PHP

// 多次元の連想配列を用意する
$action = array(
	array(
		'action' => 'tag_rename' ,
		'item_id' => '999999' ,
		'old_tag' => 'hatebuman' ,
		'new_tag' => 'funassyi' ,
	) ,
	array(
		'action' => 'readd' ,
		'item_id' => '999999' ,
	) ,
) ;
 
// 多次元の連想配列をJSONデータに変換する
$json = json_encode( $action ) ;

サンプルプログラム

以上を踏まえたサンプルプログラムを用意しました。複数のアクションを設定できる性質を利用して、複数のアイテムを一度に追加します。$consumer_key、$access_tokenを設定してアクセスしてみて下さい。デモを起動すると、このサイトの3つのページがpocketに追加されるはずです。その後、不要でしたら削除して下さい…。

PHP

<?php

	// 設定項目
	$consumer_key = '' ;	// コンシューマーキー
	$access_token = '' ;	// アクセストークン
	$request_url = 'https://getpocket.com/v3/send' ;		// リクエストURL
	$request_method = 'POST' ;								// メソッド

	// アクションのJSON
	$actions = array(
		array(
			'action' => 'add' ,
			'url' => 'https://syncer.jp/' ,
		) ,
		array(
			'action' => 'add' ,
			'url' => 'https://syncer.jp/hatebu-api-matome' ,
		) ,
		array(
			'action' => 'add' ,
			'url' => 'https://syncer.jp/brand-logos' ,
		) ,
	) ;

	// 多次元の連想配列をJSONデータに変換する
	$actions_json = json_encode( $actions ) ;

	// パラメーター
	$params = array(
		'actions' => $actions_json ,								// アクションのJSON
	) ;
 
	// パラメーターにコンシューマーキーとアクセストークンを追加
	$params = array_merge( $params , array( 'consumer_key' => $consumer_key , 'access_token' => $access_token , ) ) ;

	// コンテキスト
	$context = array(
		'http' => array(
			'method' => $request_method ,
			'content' => http_build_query( $params ) ,
		)
	) ;

	// アイテムデータをJSON形式で取得する (CURLを使用)
	$curl = curl_init() ;

	// オプションのセット
	curl_setopt( $curl , CURLOPT_URL , $request_url ) ;
	curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
	curl_setopt( $curl , CURLOPT_CUSTOMREQUEST , $context['http']['method'] ) ;			// メソッド
	curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
	curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
	curl_setopt( $curl , CURLOPT_POSTFIELDS , $context['http']['content'] ) ;			// リクエストボディ
	curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

	// 実行
	$res1 = curl_exec( $curl ) ;
	$res2 = curl_getinfo( $curl ) ;

	// 終了
	curl_close( $curl ) ;

	// 取得したデータ
	$json = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
	$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

	// HTML用
	$html = '' ;

	// JSONデータをオブジェクト形式に変換する
	$obj = json_decode( $json ) ;

	// エラー判定
	if( !isset($obj->status) || !$obj->status )
	{
		$html .= '<p>リクエストに失敗しました…。</p>' ;
	}
	else
	{
		// HTMLを作成
		$html .= '<h2>実行結果</h2>' ;
		$html .= '<p>リクエストに成功しました。</p>' ;

		// リクエストしたデータ
		$html .= '<h2>リクエストしたデータ</h2>' ;
		$html .= '<p>下記内容のアクションでリクエストを送りました。</p>' ;
		$html .= 	'<p><textarea rows="8">' . $actions_json . '</textarea></p>' ;
	}

	// 取得したデータ
	$html .= '<h2>取得したデータ</h2>' ;
	$html .= '<p>下記のデータを取得できました。</p>' ;
	$html .= 	'<h3>JSON</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $json . '</textarea></p>' ;
	$html .= 	'<h3>レスポンスヘッダー</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $header . '</textarea></p>' ;

	// アプリケーション連携の解除
	$html .= '<h2>アプリケーション連携の解除</h2>' ;
	$html .= '<p>このアプリケーションとの連携は、下記設定ページで解除することができます。</p>' ;
	$html .= '<p><a href="https://getpocket.com/connected_applications" target="_blank">https://getpocket.com/connected_applications</a></p>' ;

?>

<?php
	// ブラウザに[$html]を出力 (HTMLのヘッダーとフッターを付けましょう)
	echo $html ;
?>

このコードの動作を確認する

「Retrieveの権限」でアイテムを読み込むことで、アイテムIDを取得できます。この「アイテムID」を利用して、「追加」以外のModifyの権限のアクションを試してみて下さいね！

レートリミット

現在、pocketのAPIには、下記の通りレートリミット(使用制限)が定められています。通常の使用では超えることのない回数ですが、意識はしておきましょう。

Rate Limits: レートリミットについての公式の解説。

レートリミットの回数

1ユーザー (アクセストークン): 1時間につき320回
1アプリケーション (コンシューマーキー): 1時間につき10,000回

例えば、あなたが作ったアプリに、AさんとBさんというユーザーがいて、彼らは1時間につき320回ずつしか、あなたのアプリを通してAPIを利用できません。が、あなたのアプリの方は合計10,000回、APIを利用することができるため、AさんとBさんがフルで使っても、残り9,360回、APIを利用(提供)することができるわけです。

仮にレートリミットを超えた場合、最初の使用から1時間後の時点になるまで、APIを利用することができなくなります。

レートリミットの確認方法

レートリミットはAPIリクエストを送った際のレスポンスヘッダーの中に含まれています。PHPでは、@file_get_contents()でリクエストを送った後、自動的に配列の$http_response_headerに格納されます。CURLで送った場合は、文字列で取得できます。下記がレスポンスヘッダーの例です。赤文字に含まれているのがレートリミットの情報です。

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Content-Type: application/json
Date: Fri, 24 Jul 2015 09:40:04 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
P3P: policyref="/w3c/p3p.xml", CP="ALL CURa ADMa DEVa OUR IND UNI COM NAV INT STA PRE"
Pragma: no-cache
Server: Apache
Set-Cookie: PHPSESSID=h7qcnf9gmbb3kql5nrqb32ouo7; path=/
Status: 200 OK
X-Limit-Key-Limit: 10000
X-Limit-Key-Remaining: 9980
X-Limit-Key-Reset: 457
X-Limit-User-Limit: 500
X-Limit-User-Remaining: 490
X-Limit-User-Reset: 459
X-Source: Pocket
transfer-encoding: chunked
Connection: keep-alive

explode()やtrim()などを利用して、面倒くさいですが、目的の値を取り出しましょう。

各項目の説明

X-Limit-Key-Limit: アプリの最大使用回数 (10,000回)
X-Limit-Key-Remaining: アプリの残り使用回数 (9,995回)
X-Limit-Key-Reset: アプリの回数リセットまでの秒数 (3,540秒)
X-Limit-User-Limit: ユーザーの最大使用回数 (320回)
X-Limit-User-Remaining: ユーザーの残り使用回数 (315回)
X-Limit-User-Reset: ユーザーの回数リセットまでの秒数 (3,540秒)

ステータスコード

レスポンスヘッダーにはステータスコードの情報が格納されています。ステータスコードは、APIリクエストが成功したのか、また、エラーだったのなら何がいけなかったのか、を判断する情報となります。例えば下記、200だったら「リクエストは成功」です。

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Content-Type: application/json
Date: Fri, 24 Jul 2015 09:40:04 GMT
Expires: Thu, 19 Nov 1981 08:52:00 GMT
P3P: policyref="/w3c/p3p.xml", CP="ALL CURa ADMa DEVa OUR IND UNI COM NAV INT STA PRE"
Pragma: no-cache
Server: Apache
Set-Cookie: PHPSESSID=h7qcnf9gmbb3kql5nrqb32ouo7; path=/
Status: 200 OK
X-Limit-Key-Limit: 10000
X-Limit-Key-Remaining: 9980
X-Limit-Key-Reset: 457
X-Limit-User-Limit: 500
X-Limit-User-Remaining: 490
X-Limit-User-Reset: 459
X-Source: Pocket
transfer-encoding: chunked
Connection: keep-alive

pocket APIのステータスコードの詳細は、下記の公式ドキュメントで確認することができます。APIのリクエストが上手くいかない場合は、エラーになる原因を、ステータスコードをヒントに探しましょう。

Response, Status, and Error Codes: Pocket Developers内のページ。各ステータスコードについての説明が掲載されています。

ステータスコードの一覧

下記が主なステータスコードの一覧です。

200: リクエストが成功
401: ユーザーのアクセストークンが不正
403: ユーザーがアプリを認証していない
503: pocketのサーバーがダウンしている

APIを利用したサービス事例

最後に、pocketのAPIを利用して制作されたwebサービスを紹介します。「何かを作りたくなる！」と、制作欲求を刺激される素晴らしい作品ばかりです！

Tanaoroshi.

はてなブックマークとpocketと連携して、横断検索ができるウェブサービスです。2015年7月に誕生しました。サービス名の通り、はてブはするけど、pocketはするけど、そのまま見ないで埋もれてしまったアイテムの活用を支援してくれるウェブサービスですねー。

Tanaoroshi.: Tanaoroshi.の公式ウェブサイト。

はてブとpocketから一括検索できるwebサービス『tanaoroshi』を作ってOpenshiftで公開しました: 開発者のBokuwebさんによる開発記録です。

RandomPocket

現在は閉鎖されています。pocketに入れたアイテムの中から、未読の記事をランダムで表示してくれるwebサービスです。「”あとで読む”は”一生読まない”説」を主張する私としては、こういった振り返る「きっかけ」を提供してくれるwebサービスは物凄く素晴らしいと思いました。

ついカッとなってPocketの未読記事をランダムに読めるWebサービス「RandomPocket」をつくりました。: RandomPocket作者による開発記録。

Pocket の未読記事をランダム表示してくれる RandomPocket: RandomPocketを紹介している記事がありました！

RocketSS

登録したRSSの新着記事を、自動でpocketに送ってくれるwebサービスです。pocketユーザーは、これがあれば、RSSと「おさらば」できちゃいますね。

RocketSS: RocketSSのウェブサイト。

Rss to PocketというWEBサービスを公開しました: RocketSS作者による開発記録。

RocketSSにサービス名を変更しました: RocketSSの、サービス名の変更について。

Lisgo

こちらはiPhoneアプリです。Lisgoはpocketに登録してあるアイテムを、音声で読み上げてくれるサービスです。「読む」って行為はそれだけに時間を使わなければならず、多くの場合「やらず終い」になりますが、音声で読み上げてくれるなら、他の何かをやりながら「ついでに」記事を消化していけます。素晴らしいアイデアだと思います。

Lisgo - Listen to It Later App for Pocket: Lisgoの公式ウェブサイト。

Lisgo: iTunes内のページ。Lisgoのダウンロード。

【耳で読む】Pocketの記事を音読してくれるiPhoneアプリ「Lisgo」: Lisgoの紹介記事がありました。

Pinpocket

pocketに登録してあるアイテムを、Pinterest風に表示するwebサービスです。「より見やすく」だとか、「〜風に」だとか、見栄えを変えるだけでも立派なサービスになりますよね！残念ながら、2015年1月に確認したら既に閉鎖していました…。

IFTTT

pocketのAPIを利用したwebサービスとして「IFTTT」も忘れてはいけませんよね。「pocketしたら○○をする」「○○をしたらpocketする」といった、「他のwebサービスとの連携」をサポートするために、APIを利用するのも有用ですねー。そういえば、はてブをするとpocketしてくれる連携サービスってないんですね…。