改版履歴日付版変更内容 2014/2/3 1.0 初版 ii

Size: px

Start display at page:

Download "改版履歴日付版変更内容 2014/2/3 1.0 初版 ii"

ひとおじゅふく
7 years ago
Views:

1 トレンド記事抽出 API インタフェース仕様書第 1.0 版 2014 年 2 月 3 日株式会社 NTTドコモ i

2 改版履歴日付版変更内容 2014/2/3 1.0 初版 ii

3 目次 1. はじめにトレンド記事抽出 API 仕様共通仕様エンドポイント一覧 SNS 認証取得ジャンル情報ジャンル情報の取得コンテンツデータ取得キーワード検索エラーレスポンストレンド記事抽出 API の利用例ジャンル情報の取得ジャンル ID 指定によるコンテンツデータ取得 iii

4 1. はじめにトレンド記事抽出 API では Web から収集したトレンド記事を収集できますトレンド記事はジャンルもしくはキーワードを指定すると取得できますたとえばスポーツジャンルを指定すれば図 1のような Web のニュース記事が取得できるでしょうトレンド記事の抽出に Twitter 等の SNS をベースにしているためユーザ単位でのログインを推奨しています今後他の SNS 情報やパーソナライズを実施する場合は別の認証キーが必要になります図 1.トレンド記事抽出 API にてスポーツに関するニュース記事を配信するアプリの例 1

5 2. トレンド記事抽出 API 仕様本章ではトレンド記事抽出 API の利用にあたってのリクエスト/レスポンスの仕様を記載する 2.1. 共通仕様プロトコル文字コード Content-type HTTP UTF-8 application/json 2.2. エンドポイント一覧対象データエンドポイントメソッド 1 SNS 認証取得 GET 2 ジャンル情報 GET 3 コンテンツデータ取得 GET 4 キーワード検索 GET 2.3. SNS 認証取得機能概要外部 SNS サービスのユーザ ID を取得しアプリに返却する現在ユーザ ID を取得できる外部 SNS サービスは Twitter 外部 SNS サービスの認証ページにリダイレクトし認証後 Javascript によりクエリパラメータの location で指定されるアプリ中の場所に結果を返却する備考 Webview やブラウザを開いてアクセスを行ってください本 API はトレンド記事の抽出に Twitte 等を利用しており本 API 利用には Twitter ログインの機会をユーザに提供するのが必須である (Twitter: Twitter 連携にあたって本エンドポイントの利用は必須ではないが利用を推奨する URL メソッドリクエスト URL HTTP メソッド api.apigw.smt.docomo.ne.jp/webcuration/v1/auth.format GET パスパラメータパラメータ format 2

6 値データのフォーマットを指定する必須 /オプション:オプション html html 形式クエリパラメータパラメータ値 provider 認証先のサービス名必須 /オプション: 必須 "twitter" 将来的には facebook 等にも対応を想定パラメータ location 結果の返却先を指定するための URL 必須 /オプション: 必須値アプリに URL スキームで戻るための文字列 test-app:// auth 等リクエスト例 # twitter 認証により新規アカウント登録を行う GET 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

7 <title> 認証完了 </title> </head> <body> 認証が完了しましたアプリケーションに戻りますしばらくお待ちください </body> </html> 4

8 2.4. ジャンル情報ジャンル情報の取得機能概要サーバ側で配信しているコンテンツジャンルを取得する本機能を用いて genreid とジャンル名の対応を取得する備考取得した genreid をコンテンツデータ取得のエンドポイントにおいてクエリパラメータに設定することで各ジャンルのコンテンツデータを取得する URL メソッドリクエスト URL HTTP メソッド api.apigw.smt.docomo.ne.jp/webcuration/v1/genre.format GET パスパラメータパラメータ値 format 必須 /オプション:オプションデフォルト:json json JSON 形式クエリパラメータリクエスト例 # ジャンル設定情報を取得 GET 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

9 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

10 ,... ] ] "subgenreid" : 202, "title" : " 中華 " 2.5. コンテンツデータ取得機能概要 genreid を指定し各ジャンルで配信されているトレンド記事を取得するトレンド記事は1 日に数回定期的に更新される備考アクセスは HTTP リダイレクトされる可能性があるコンテンツ数が n で指定された件数に満たない場合は指定された件数以下でデータを返却する URL メソッドリクエスト URL HTTP メソッド api.apigw.smt.docomo.ne.jp/webcuration/v1/contents.format GET パスパラメータパラメータ値 format データのフォーマットを指定する必須 /オプション:オプションデフォルト:json json JSON 形式クエリパラメータパラメータ値 genreid 表示設定されている genreid を指定する必須 /オプション: 必須表示設定している genreid パラメータ s コンテンツ一覧の開始番号を指定する 7

11 値必須 /オプション:オプションデフォルト:1 1 以上の整数パラメータ値 n カテゴリ内のコンテンツ一覧の取得件数を指定する必須 :オプションデフォルト:10 0 以上 50 以下の整数リクエスト例 #ジャンル 1 のコンテンツを 1 件目から 20 件取得する場合 GET 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 型 : まで) 2 contenttype 数値コンテンツ種別 (サーバから任意の値が指定されます記事がレコメンド記事かそうでないか区別可能にするため 8

12 に送付されます 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" : " T11:11: ", "articlecontents" :[ "contentid" : 100, "contentdata" : 9

13 "title" : " ニュース記事 +サービス導線コンテンツあり原子を動かして制作世界最小の動画 ", "body" : " 縦横数万分の1ミリずつしかない背景の上で原子を1つずつ動かすことで制作された世界一小さなアニメーション動画が完成しギネス世界記録に認定されました ", linkurl : "createddate" : " T11:11: ", "sourcedomain" : "nhk.or.jp", "sourcename" : "NHK オンライン",, "contentid" : 101, "contentdata" : "title" : " ニュース記事 +ボタン 3 つ米で5 歳児が誤射 2 歳の妹死亡子ども向けライフルで", "body" : " 米ケンタッキー州バークスビル近くで4 月 30 日 5 歳の男児が誤って2 歳の妹をライフルで撃ち死なせる事件が起きた ", linkurl : "createddate" : " T11:11: ", "sourcedomain" : "asahi.com", "sourcename" : " 朝日新聞デジタル", "contentid" : 102, "contentdata" : "title" : " ニュース記事 + 追加ボタン首相の歴史認識への批判に駐米大使反論 ", "body" : "アメリカの新聞ワシントンポストが安倍総理大臣の歴史認識を巡る発言を批判する社説を掲載したことに対し佐々江駐米大使が日本は歴史に常に正面から向き合ってきたという内容の反論を投稿しました ", linkurl : "createddate" : " T11:11: ", "sourcedomain" : "asahi.com", "sourcename" : " 朝日新聞デジタル" 10

14 , "contentid" : 103, "contentdata" : "title" : " ミュージックきゃりーぱみゅぱみゅにんじゃりばんばん ", linkurl : "createddate" : " T11:11: ", "sourcedomain" : "music.dmkt-sp.jp", "sourcename" : "d ミュージック", "contentid" : 104, "contentdata" : "title" : " ニュース記事ホワイトタイガーの赤ちゃん公開 ", "body" : " 埼玉県宮代町の東武動物公園でことし3 月に誕生した珍しいトラホワイトタイガーの赤ちゃんが 2 日から一般に公開され愛くるしい姿で訪れた人たちを楽しませています ", linkurl : "createddate" : " T11:11: ", "sourcedomain" : "asahi.com", "sourcename" : " 朝日新聞デジタル", "contentid" : 105, "contentdata" : "title" : " ニュース記事寺山修司さん没後 30 年舞台や展覧会 ", "body" : " 詩人や劇作家など幅広い芸術活動を展開し影響を与え続けている寺山修司さんが亡くなって4 日で30 年を迎えることから全国各地でゆかりのある舞台の上演や展覧会が相次ぎ寺山作品の魅力が見直されています ", linkurl : "createddate" : " T11:11: ", "sourcedomain" : "asahi.com", 11

15 "sourcename" : " 朝日新聞デジタル", "contentid" : 106, "contentdata" : "title" : " ミュージック+ 追加ボタンきゃりーぱみゅぱみゅにんじゃりばんばん ", linkurl : music.dmkt-sp.jp/test, "createddate" : " T11:11: ", "sourcedomain" : "music.dmkt-sp.jp", "sourcename" : "d ミュージック",. ] 2.6. キーワード検索機能概要 keyword を指定することによりキーワードが含まれるトレンド記事を取得する返却されるトレンド記事はコンテンツデータ取得と同様 1 日に数回定期的に更新される備考アクセスは HTTP リダイレクトされる可能性があるコンテンツ数が n で指定された件数に満たない場合は指定された件数以下でデータを返却する本機能利用によりエンドユーザに好みのキーワードを入力させそのキーワードを含むトレンド記事を取得する機能の設置が必須である URL メソッドリクエスト URL HTTP メソッド api.apigw.smt.docomo.ne.jp/webcuration/v1/search.format GET パスパラメータパラメータ format データのフォーマットを指定する 12

16 値必須 /オプション:オプションデフォルト:json json JSON 形式クエリパラメータパラメータ値 genreid 検索対象の genreid を指定する必須 /オプション:オプション検索対象の genreid パラメータ keyword 検索キーワードを指定する必須 /オプション: 必須値検索キーワードを UTF-8 で URL エンコードしたもの( 文字列 ) パラメータ値 s コンテンツ一覧の開始番号を指定する必須 /オプション:オプションデフォルト:1 1 以上の整数パラメータ値 n カテゴリ内のコンテンツ一覧の取得件数を指定する必須 :オプションデフォルト:10 0 以上 50 以下の整数リクエスト例 # 全ジャンルのコンテンツをラーメンで検索して 1 件目から 20 記事取得する場合 GET 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

17 数 ) 2 startindex 数値 (1 以上の整数 ) 3 itemsperpage 数値 (0 以上の整数 ) 4 issuedate 文字列 5 articlecontents 配列 (オブジェクト) 取得コンテンツの開始番号取得コンテンツの返却件数記事セットの作成時刻 YYYY-MM-DDThh:mm:ssTZD custom が true の場合のみ返却されるコンテンツの配列. 設定されたコンテンツが無い場合空配列を返却 articlecontents の要素キー値必須コンテンツの識別子すべてのコンテン 1 contentid 数値ツでユニークな値 ( long 型 : まで) 2 contenttype 数値コンテンツ種別 (サーバから任意の値が指定されます記事がレコメンド記事かそうでないか区別可能にするために送付されます 10: 記事コンテンツ 11:レコメンド記事コンテンツ 3 contentdata オブジェクト表示するコンテンツデータ contentdata の要素キー値必須 1 title 文字列コンテンツのタイトル( 表示文字を超える場合はアプリ側で省略処理を実施 ) 2 body 文字列コンテンツの本文 ( 表示文字を超える場合はアプリ側で省略処理を実施 ) 3 linkurl 文字列元記事の URL 3 imageurl 文字列コンテンツの写真の URL 4 imagesize オブジェクトコンテンツ中の写真のサイズ縦 px, 横 px で指定 5 createddate 文字列記事作成日時 14

18 6 sourcedomain 文字列配信元ドメイン 7 sourcename 文字列配信元名称 YYYY-MM-DDThh:mm:ssTZD 15

19 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

20 01 UUID 取得 02 SNS 認証取得 03 SNS 認証管理 04 ジャンル情報 05 カスタムジャンル情報 06 サービス設定 07 コンテンツデータ取得 08 サービス導線コンテンツデータ取得 09 キーワード関連コンテンツデータ取得 10 キーワードレコメンド結果取得 11 不適切コンテンツ情報 12 ログ情報レスポンス例 (JSON 形式 ) "error": "code": "010", "message": "00: 共通 HTTP リクエストパラメータが不正です " 17

21 3. トレンド記事抽出 API の利用例本章ではスポーツジャンルに関する Web 中のトレンド情報を取得するまでの流れを示します 3.1. ジャンル情報の取得まずジャンル情報取得のエンドポイントを用いてジャンル ID とジャンル名の紐づけを取得します本エンドポイント利用によりジャンル ID 1 がスポーツジャンルであることがわかりました 18

22 3.2. ジャンル ID 指定によるコンテンツデータ取得スポーツジャンルのトレンド情報を取得するにはジャンル ID 1 を指定してコンテンツデータ取得のエンドポイントにアクセスします 19

<4D6963726F736F667420576F7264202D20819C486F70658F6F93588ED297708AC7979D89E696CA837D836A83858341838B8169342E33566572816A2E646F63>

<4D6963726F736F667420576F7264202D20819C486F70658F6F93588ED297708AC7979D89E696CA837D836A83858341838B8169342E33566572816A2E646F63> 商品管理商品管理を行うためのメニューです 4.1 商品管理のサイドメニュー商品管理には以下のサイドメニューがあります商品一覧登録済みの商品の一覧を表示します既に登録済みの商品の検索検索した商品を編集する際に使用します新規作成商品を新規登録する画面

改 版 履 歴 日 付 版 変 更 内 容 2014/2/3 1.0 初 版 ii

改版履歴日付版変更内容 2014/2/3 1.0 初版 ii