トレンド 記 事 抽 出 API インタフェース 仕 様 書 第 1.0 版 2014 年 2 月 3 日 株 式 会 社 NTTドコモ i
改 版 履 歴 日 付 版 変 更 内 容 2014/2/3 1.0 初 版 ii
目 次 1. はじめに... 1 2. トレンド 記 事 抽 出 API 仕 様... 2 2.1. 共 通 仕 様... 2 2.2. エンドポイント 一 覧... 2 2.3. SNS 認 証 取 得... 2 2.4. ジャンル 情 報... 5 2.4.1. ジャンル 情 報 の 取 得... 5 2.5. コンテンツデータ 取 得... 7 2.6. キーワード 検 索... 12 2.7. エラーレスポンス... 16 3. トレンド 記 事 抽 出 API の 利 用 例... 18 3.1. ジャンル 情 報 の 取 得... 18 3.2. ジャンル ID 指 定 によるコンテンツデータ 取 得... 19 iii
1. はじめに トレンド 記 事 抽 出 API では Web から 収 集 したトレンド 記 事 を 収 集 できます トレンド 記 事 はジャンル もしくはキーワードを 指 定 すると 取 得 できます たとえば スポーツ ジャンルを 指 定 すれば 図 1のような Web のニュース 記 事 が 取 得 できるでしょう トレンド 記 事 の 抽 出 に Twitter 等 の SNS をベースにしているためユーザ 単 位 でのログインを 推 奨 してい ます 今 後 他 の SNS 情 報 やパーソナライズを 実 施 する 場 合 は 別 の 認 証 キーが 必 要 になります 図 1.トレンド 記 事 抽 出 API にてスポーツに 関 するニュース 記 事 を 配 信 するアプリの 例 1
2. トレンド 記 事 抽 出 API 仕 様 本 章 ではトレンド 記 事 抽 出 API の 利 用 にあたってのリクエスト/レスポンスの 仕 様 を 記 載 する 2.1. 共 通 仕 様 プロトコル 文 字 コード Content-type HTTP UTF-8 application/json 2.2. エンドポイント 一 覧 対 象 データ エンドポイント メソッド 1 SNS 認 証 取 得 https://api.apigw.smt.docomo.ne.jp/webcuration/v1/auth GET 2 ジャンル 情 報 https://api.apigw.smt.docomo.ne.jp/webcuration/v1/genre GET 3 コンテンツデータ 取 得 https://api.apigw.smt.docomo.ne.jp/webcuration/v1/contents GET 4 キーワード 検 索 https://api.apigw.smt.docomo.ne.jp/webcuration/v1/search GET 2.3. SNS 認 証 取 得 機 能 概 要 外 部 SNS サービスのユーザ ID を 取 得 し アプリに 返 却 する 現 在 ユーザ ID を 取 得 できる 外 部 SNS サービスは Twitter 外 部 SNS サービスの 認 証 ページにリダイレクトし 認 証 後 Javascript によりクエリパラメータの location で 指 定 されるアプリ 中 の 場 所 に 結 果 を 返 却 する 備 考 Webview やブラウザを 開 いてアクセスを 行 ってください 本 API はトレンド 記 事 の 抽 出 に Twitte 等 を 利 用 しており 本 API 利 用 には Twitter ログインの 機 会 をユ ーザに 提 供 するのが 必 須 である (Twitter:https://twitter.com/) Twitter 連 携 にあたって 本 エンドポイントの 利 用 は 必 須 ではないが 利 用 を 推 奨 する URL メソッド リクエスト URL HTTP メソッド https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/auth.format GET パスパラメータ パラメータ format 2
値 データのフォーマットを 指 定 する 必 須 /オプション:オプション html html 形 式 クエリパラメータ パラメータ 値 provider 認 証 先 のサービス 名 必 須 /オプション: 必 須 "twitter" 将 来 的 には facebook 等 にも 対 応 を 想 定 パラメータ location 結 果 の 返 却 先 を 指 定 するための URL 必 須 /オプション: 必 須 値 アプリに URL スキームで 戻 るための 文 字 列 test-app:// auth 等 リクエスト 例 # twitter 認 証 により 新 規 アカウント 登 録 を 行 う GET https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/auth?provider=twitter&location= test-appli%2f%3a%3aauth レスポンス(HTML+JS) キー 値 必 須 1 result 文 字 列 "success" / "fault" 2 authid 文 字 列 provider から 払 い 出 される 固 有 の ID ユーザ 識 別 子 レスポンス 例 # URL スキームを 利 用 し result パラメータで 認 証 結 果 を 返 却 する 例 サーバ 側 で$result$を 認 証 結 果 に $authid$を provider から 払 い 出 される 固 有 の ID に 置 換 <html> <head> <script type="text/javascript"> function returnresult(result, authid) document.location =test-appli://auth?result=' + result + '&authid=' + authid; returnresult('$result$', '$authid$'); </script> 3
<title> 認 証 完 了 </title> </head> <body> 認 証 が 完 了 しました アプリケーションに 戻 ります しばらくお 待 ちください </body> </html> 4
2.4. ジャンル 情 報 2.4.1. ジャンル 情 報 の 取 得 機 能 概 要 サーバ 側 で 配 信 しているコンテンツジャンルを 取 得 する 本 機 能 を 用 いて genreid とジャンル 名 の 対 応 を 取 得 する 備 考 取 得 した genreid をコンテンツデータ 取 得 のエンドポイントにおいてクエリパラメータに 設 定 することで 各 ジャンルのコンテンツデータを 取 得 する URL メソッド リクエスト URL HTTP メソッド https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/genre.format GET パスパラメータ パラメータ 値 format 必 須 /オプション:オプション デフォルト:json json JSON 形 式 クエリパラメータ リクエスト 例 # ジャンル 設 定 情 報 を 取 得 GET https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/genre レスポンス(JSON) キー 値 必 須 1 genre 配 列 (オブジェクト) コンテンツジャンル 及 び 設 定 情 報 genre の 要 素 キー 値 必 須 1 genreid 数 値 ジャンルの ID(1 以 上 の 整 数 ) 2 title 文 字 列 ジャンルの 表 示 名 称 ( 全 角 20 文 字 ) 3 description 文 字 列 ジャンルの 文 ( 全 角 40 文 字 ) 4 subgenre 配 列 (オブジェクト) 各 ジャンルのサブジャンルの 情 報 5
subgenre の 要 素 キー 値 必 須 1 subgenreid 数 値 サブジャンルの ID(100 以 上 の 整 数 ) 2 title 文 字 列 サブジャンルの 表 示 名 称 ( 全 角 20 文 字 ) 3 description 文 字 列 ジャンルの 文 ( 全 角 40 文 字 ) レスポンス 例 (JSON 形 式 ) #ジャンル 情 報 の 取 得 "genre": [ "genreid": 1, "title": "スポーツ", "description" : "スポーツニュースをお 届 けします!", "subgenre" : [ "subgenreid" : 101, "title" : " 野 球 ", "description" : " 野 球 ニュースをお 届 けします!", "subgenreid" : 102, "title" : "サッカー", ], "genreid": 2, "title": "グルメ", "subgenre" : [ "subgenreid" : 201, "title" : "イタリアン", 6
,... ] ] "subgenreid" : 202, "title" : " 中 華 " 2.5. コンテンツデータ 取 得 機 能 概 要 genreid を 指 定 し 各 ジャンルで 配 信 されているトレンド 記 事 を 取 得 する トレンド 記 事 は1 日 に 数 回 定 期 的 に 更 新 される 備 考 アクセスは HTTP リダイレクトされる 可 能 性 がある コンテンツ 数 が n で 指 定 された 件 数 に 満 たない 場 合 は 指 定 された 件 数 以 下 でデータを 返 却 する URL メソッド リクエスト URL HTTP メソッド https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/contents.format GET パスパラメータ パラメータ 値 format データのフォーマットを 指 定 する 必 須 /オプション:オプション デフォルト:json json JSON 形 式 クエリパラメータ パラメータ 値 genreid 表 示 設 定 されている genreid を 指 定 する 必 須 /オプション: 必 須 表 示 設 定 している genreid パラメータ s コンテンツ 一 覧 の 開 始 番 号 を 指 定 する 7
値 必 須 /オプション:オプション デフォルト:1 1 以 上 の 整 数 パラメータ 値 n カテゴリ 内 のコンテンツ 一 覧 の 取 得 件 数 を 指 定 する 必 須 :オプション デフォルト:10 0 以 上 50 以 下 の 整 数 リクエスト 例 #ジャンル 1 のコンテンツを 1 件 目 から 20 件 取 得 する 場 合 GET https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/contents?genreid=1&s=1&n=20 レスポンス(JSON) キー 値 必 須 1 totalresults 数 値 (0 以 上 の 整 コンテンツの 全 件 数 数 ) 2 startindex 数 値 (1 以 上 の 整 取 得 コンテンツの 開 始 番 号 数 ) 3 itemsperpage 数 値 (0 以 上 の 整 取 得 コンテンツの 返 却 件 数 数 ) 4 issuedate 文 字 列 記 事 セットの 作 成 時 刻 YYYY-MM-DDThh:mm:ssTZD 5 articlecontents 配 列 (オブジェクト) コンテンツの 配 列. 設 定 されたコンテ ンツが 無 い 場 合 空 配 列 を 返 却 articlecontents の 要 素 キー 値 必 須 コンテンツの 識 別 子 すべてのコンテン 1 contentid 数 値 ツ で ユ ニ ー ク な 値 ( long 型 : 9223372036854775807 まで) 2 contenttype 数 値 コンテンツ 種 別 (サーバから 任 意 の 値 が 指 定 されます 記 事 がレコメンド 記 事 か そうでないか 区 別 可 能 にするため 8
に 送 付 されます 10: 記 事 コンテンツ 11:レコメンド 記 事 コンテンツ 3 contentdata オブジェクト 表 示 するコンテンツデータ contentdata の 要 素 キー 値 必 須 1 title 文 字 列 コンテンツのタイトル( 表 示 文 字 を 超 え る 場 合 はアプリ 側 で 省 略 処 理 を 実 施 ) 2 body 文 字 列 コンテンツの 本 文 ( 表 示 文 字 を 超 える 場 合 はアプリ 側 で 省 略 処 理 を 実 施 ) 3 linkurl 文 字 列 元 記 事 の URL 4 imageurl 文 字 列 コンテンツの 写 真 の URL 5 imagesize オブジェクト コンテンツ 中 の 写 真 のサイズ 縦 px, 横 px で 指 定 6 createddate 文 字 列 記 事 作 成 日 時 YYYY-MM-DDThh:mm:ssTZD 7 sourcedomain 文 字 列 配 信 元 ドメイン 8 sourcename 文 字 列 配 信 元 名 称 imagesize の 要 素 キー 値 必 須 1 height 数 値 画 像 の 縦 ピクセル 数 2 width 数 値 画 像 の 横 ピクセル 数 レスポンス 例 (JSON 形 式 ) "totalresults" : 10, "startindex" : 1, "itemsperpage" : 10, "issuedate" : "2013-05-01T11:11:11+0900", "articlecontents" :[ "contentid" : 100, "contentdata" : 9
"title" : " ニュース 記 事 +サービス 導 線 コンテンツあり 原 子 を 動 かして 制 作 世 界 最 小 の 動 画 ", "body" : " 縦 横 数 万 分 の1ミリずつしかない 背 景 の 上 で 原 子 を1つずつ 動 かすことで 制 作 された 世 界 一 小 さなアニメーション 動 画 が 完 成 し ギネス 世 界 記 録 に 認 定 されました ", linkurl : http://nhk.or.jp/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "nhk.or.jp", "sourcename" : "NHK オンライン",, "contentid" : 101, "contentdata" : "title" : " ニュース 記 事 +ボタン 3 つ 米 で5 歳 児 が 誤 射 2 歳 の 妹 死 亡 子 ども 向 けライフルで", "body" : " 米 ケンタッキー 州 バークスビル 近 くで4 月 30 日 5 歳 の 男 児 が 誤 って2 歳 の 妹 をライフルで 撃 ち 死 なせる 事 件 が 起 きた ", linkurl : http://asahi.com/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "asahi.com", "sourcename" : " 朝 日 新 聞 デジタル", "contentid" : 102, "contentdata" : "title" : " ニュース 記 事 + 追 加 ボタン 首 相 の 歴 史 認 識 への 批 判 に 駐 米 大 使 反 論 ", "body" : "アメリカの 新 聞 ワシントン ポスト が 安 倍 総 理 大 臣 の 歴 史 認 識 を 巡 る 発 言 を 批 判 する 社 説 を 掲 載 したことに 対 し 佐 々 江 駐 米 大 使 が 日 本 は 歴 史 に 常 に 正 面 から 向 き 合 ってきたという 内 容 の 反 論 を 投 稿 しま した ", linkurl : http://asahi.com/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "asahi.com", "sourcename" : " 朝 日 新 聞 デジタル" 10
, "contentid" : 103, "contentdata" : "title" : " ミュージック きゃりーぱみゅぱみゅ にんじゃりばんばん ", linkurl : http://music.dmkt-sp.jp/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "music.dmkt-sp.jp", "sourcename" : "d ミュージック", "contentid" : 104, "contentdata" : "title" : " ニュース 記 事 ホワイトタイガーの 赤 ちゃん 公 開 ", "body" : " 埼 玉 県 宮 代 町 の 東 武 動 物 公 園 でことし3 月 に 誕 生 した 珍 しいトラ ホワイトタイガーの 赤 ちゃんが 2 日 から 一 般 に 公 開 され 愛 くるしい 姿 で 訪 れた 人 たちを 楽 しませています ", linkurl : http://asahi.com/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "asahi.com", "sourcename" : " 朝 日 新 聞 デジタル", "contentid" : 105, "contentdata" : "title" : " ニュース 記 事 寺 山 修 司 さん 没 後 30 年 舞 台 や 展 覧 会 ", "body" : " 詩 人 や 劇 作 家 など 幅 広 い 芸 術 活 動 を 展 開 し 影 響 を 与 え 続 けている 寺 山 修 司 さんが 亡 くなって4 日 で30 年 を 迎 えることから 全 国 各 地 でゆかりのある 舞 台 の 上 演 や 展 覧 会 が 相 次 ぎ 寺 山 作 品 の 魅 力 が 見 直 され ています ", linkurl : http://asahi.com/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "asahi.com", 11
"sourcename" : " 朝 日 新 聞 デジタル", "contentid" : 106, "contentdata" : "title" : " ミュージック+ 追 加 ボタン きゃりーぱみゅぱみゅ にんじゃりばんばん ", linkurl : http:// music.dmkt-sp.jp/test, "createddate" : "2013-05-01T11:11:11+0900", "sourcedomain" : "music.dmkt-sp.jp", "sourcename" : "d ミュージック",. ] 2.6. キーワード 検 索 機 能 概 要 keyword を 指 定 することによりキーワードが 含 まれるトレンド 記 事 を 取 得 する 返 却 されるトレンド 記 事 はコンテンツデータ 取 得 と 同 様 1 日 に 数 回 定 期 的 に 更 新 される 備 考 アクセスは HTTP リダイレクトされる 可 能 性 がある コンテンツ 数 が n で 指 定 された 件 数 に 満 たない 場 合 は 指 定 された 件 数 以 下 でデータを 返 却 する 本 機 能 利 用 により エンドユーザに 好 みのキーワードを 入 力 させそのキーワードを 含 むトレンド 記 事 を 取 得 する 機 能 の 設 置 が 必 須 である URL メソッド リクエスト URL HTTP メソッド https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/search.format GET パスパラメータ パラメータ format データのフォーマットを 指 定 する 12
値 必 須 /オプション:オプション デフォルト:json json JSON 形 式 クエリパラメータ パラメータ 値 genreid 検 索 対 象 の genreid を 指 定 する 必 須 /オプション:オプション 検 索 対 象 の genreid パラメータ keyword 検 索 キーワードを 指 定 する 必 須 /オプション: 必 須 値 検 索 キーワードを UTF-8 で URL エンコードしたもの( 文 字 列 ) パラメータ 値 s コンテンツ 一 覧 の 開 始 番 号 を 指 定 する 必 須 /オプション:オプション デフォルト:1 1 以 上 の 整 数 パラメータ 値 n カテゴリ 内 のコンテンツ 一 覧 の 取 得 件 数 を 指 定 する 必 須 :オプション デフォルト:10 0 以 上 50 以 下 の 整 数 リクエスト 例 # 全 ジャンルのコンテンツをラーメンで 検 索 して 1 件 目 から 20 記 事 取 得 する 場 合 GET https:// api.apigw.smt.docomo.ne.jp/webcuration/v1/search?keyword=%e3%83%a9%e3 %83%bc%e3%83%a1%e3%83%b3&s=1&n=20 レスポンス(JSON) キー 値 必 須 1 totalresults 数 値 (0 以 上 の 整 コンテンツの 全 件 数 13
数 ) 2 startindex 数 値 (1 以 上 の 整 数 ) 3 itemsperpage 数 値 (0 以 上 の 整 数 ) 4 issuedate 文 字 列 5 articlecontents 配 列 (オブジェクト) 取 得 コンテンツの 開 始 番 号 取 得 コンテンツの 返 却 件 数 記 事 セットの 作 成 時 刻 YYYY-MM-DDThh:mm:ssTZD custom が true の 場 合 のみ 返 却 され る コンテンツの 配 列. 設 定 されたコンテ ンツが 無 い 場 合 空 配 列 を 返 却 articlecontents の 要 素 キー 値 必 須 コンテンツの 識 別 子 すべてのコンテン 1 contentid 数 値 ツ で ユ ニ ー ク な 値 ( long 型 : 9223372036854775807 まで) 2 contenttype 数 値 コンテンツ 種 別 (サーバから 任 意 の 値 が 指 定 されます 記 事 がレコメンド 記 事 か そうでないか 区 別 可 能 にするため に 送 付 されます 10: 記 事 コンテンツ 11:レコメンド 記 事 コンテンツ 3 contentdata オブジェクト 表 示 するコンテンツデータ contentdata の 要 素 キー 値 必 須 1 title 文 字 列 コンテンツのタイトル( 表 示 文 字 を 超 え る 場 合 はアプリ 側 で 省 略 処 理 を 実 施 ) 2 body 文 字 列 コンテンツの 本 文 ( 表 示 文 字 を 超 える 場 合 はアプリ 側 で 省 略 処 理 を 実 施 ) 3 linkurl 文 字 列 元 記 事 の URL 3 imageurl 文 字 列 コンテンツの 写 真 の URL 4 imagesize オブジェクト コンテンツ 中 の 写 真 のサイズ 縦 px, 横 px で 指 定 5 createddate 文 字 列 記 事 作 成 日 時 14
6 sourcedomain 文 字 列 配 信 元 ドメイン 7 sourcename 文 字 列 配 信 元 名 称 YYYY-MM-DDThh:mm:ssTZD 15
imagesize の 要 素 キー 値 必 須 1 height 数 値 画 像 の 縦 ピクセル 数 2 width 数 値 画 像 の 横 ピクセル 数 レスポンス 例 (JSON 形 式 ) コンテンツデータ 取 得 を 参 照 のこと 2.7. エラーレスポンス HTTP 主 要 ステータスコード ステータスコード 200 OK 成 功 応 答 304 Not Modified 未 使 用 400 Bad Request リクエストパラメータ 不 正 401 Unauthorized 認 証 に 関 するエラー 404 Not Found 未 使 用 405 Method Not Allowed 未 使 用 500 Internal Server Error サーバ 内 部 エラー レスポンス(JSON 形 式 ) キー 値 必 須 1 error オブジェクト エラーオブジェクト 1 code Number エラーコード 2 message String エラーメッセージ( 機 能 コード:エラー 内 容 ) エラーコード 一 覧 エラーコード 000 下 記 以 外 の 予 期 せぬエラー( 内 部 サーバエラー 等 ):500 Internal Server Error 010 リクエストパラメータ 不 正 :400 Bad Request 020 認 証 に 関 するエラー:401 Unauthorized 030 UUID の 失 効 :401 Unauthorized エラーメッセージ( 機 能 番 号 ) 一 覧 機 能 コード 00 共 通 16
01 UUID 取 得 02 SNS 認 証 取 得 03 SNS 認 証 管 理 04 ジャンル 情 報 05 カスタムジャンル 情 報 06 サービス 設 定 07 コンテンツデータ 取 得 08 サービス 導 線 コンテンツデータ 取 得 09 キーワード 関 連 コンテンツデータ 取 得 10 キーワードレコメンド 結 果 取 得 11 不 適 切 コンテンツ 情 報 12 ログ 情 報 レスポンス 例 (JSON 形 式 ) "error": "code": "010", "message": "00: 共 通 HTTP リクエストパラメータが 不 正 です " 17
3. トレンド 記 事 抽 出 API の 利 用 例 本 章 ではスポーツジャンルに 関 する Web 中 のトレンド 情 報 を 取 得 するまでの 流 れを 示 します 3.1. ジャンル 情 報 の 取 得 まず ジャンル 情 報 取 得 のエンドポイントを 用 いてジャンル ID とジャンル 名 の 紐 づけを 取 得 します 本 エンドポイント 利 用 により ジャンル ID 1 が スポーツ ジャンルであることがわかりました 18
3.2. ジャンル ID 指 定 によるコンテンツデータ 取 得 スポーツジャンルのトレンド 情 報 を 取 得 するには ジャンル ID 1 を 指 定 してコンテンツデータ 取 得 のエン ドポイントにアクセスします 19