トレンド記事抽出api...

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved

i

トレンド記事抽出API インタフェース仕様書

第 1.0 版

2014年2月3日

株式会社ＮＴＴドコモ


ii

改版履歴

日付版変更内容

2014/2/3 1.0 初版


iii

目次

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


1

1. はじめに

「トレンド記事抽出 API」では、Web から収集したトレンド記事を収集できます。

トレンド記事はジャンル、もしくはキーワードを指定すると取得できます。

たとえば「スポーツ」ジャンルを指定すれば図１のような Web のニュース記事が取得できるでしょう。

トレンド記事の抽出に、Twitter 等の SNS をベースにしているためユーザ単位でのログインを推奨してい

ます。今後他の SNS 情報やパーソナライズを実施する場合は別の認証キーが必要になります。

図１．トレンド記事抽出 API にてスポーツに関するニュース記事を配信するアプリの例


2

2. トレンド記事抽出 API 仕様

本章ではトレンド記事抽出 API の利用にあたってのリクエスト/レスポンスの仕様を記載する。

2.1. 共通仕様

プロトコル HTTP

文字コード UTF-8

Content-type 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 ログインの機会をユ

ーザに提供するのが必須である。

（Ｔｗitter：https://twitter.com/）

・Twitter 連携にあたって本エンドポイントの利用は必須ではないが、利用を推奨する。

URL・メソッド

リクエスト URL https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/auth{.format}

HTTP メソッド GET

パスパラメータ

パラメータ format


3

説明データのフォーマットを指定する

必須／オプション：オプション

値 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>


4

<title>認証完了</title>

</head>

<body>

認証が完了しました。アプリケーションに戻ります。しばらくお待ちください。

</body>

</html>


5

2.4. ジャンル情報

2.4.1. ジャンル情報の取得

【機能概要】

・サーバ側で配信しているコンテンツジャンルを取得する。

・本機能を用いて genreId とジャンル名の対応を取得する。

【備考】

・取得した genreId をコンテンツデータ取得のエンドポイントにおいてクエリパラメータに設定することで、

各ジャンルのコンテンツデータを取得する。

URL・メソッド

リクエスト URL https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/genre{.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 配列（オブジェクト）各ジャンルのサブジャンルの情報


6

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" : "イタリアン"

},

{


7

"subGenreId" : 202,

"title" : "中華"

}

]

},

...

]

}

2.5. コンテンツデータ取得

【機能概要】

・genreId を指定し、各ジャンルで配信されているトレンド記事を取得する。

・トレンド記事は１日に数回、定期的に更新される。

【備考】

・アクセスは HTTP リダイレクトされる可能性がある。

・コンテンツ数が n で指定された件数に満たない場合は、指定された件数以下でデータを返却する。

URL・メソッド

リクエスト URL https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/contents{.format}









パラメータ genreId

説明表示設定されている genreId を指定する


値表示設定している genreId

パラメータ s

説明コンテンツ一覧の開始番号を指定する


8


デフォルト：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



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 数値

コンテンツ種別（サーバから任意の値

が指定されます。記事がレコメンド記事

か、そうでないか区別可能にするため


9

に送付されます。

10:記事コンテンツ

11:レコメンド記事コンテンツ

3 contentData オブジェクト ○ 表示するコンテンツデータ

contentData の要素


1 title 文字列 ○ コンテンツのタイトル（表示文字を超え

る場合はアプリ側で省略処理を実施）

2 body 文字列コンテンツの本文（表示文字を超える

場合はアプリ側で省略処理を実施）

3 linkUrl 文字列 ○ 元記事の URL

4 imageUrl 文字列コンテンツの写真の URL

5 imageSize オブジェクトコンテンツ中の写真のサイズ。縦 px,横

px で指定。

6 createdDate 文字列 ○ 記事作成日時


7 sourceDomain 文字列 ○ 配信元ドメイン

8 sourceName 文字列 ○ 配信元名称

imageSize の要素


1 height 数値 ○ 画像の縦ピクセル数

2 width 数値 ○ 画像の横ピクセル数


{

"totalResults" : 10,

"startIndex" : 1,

"itemsPerPage" : 10,

"issueDate" : "2013-05-01T11:11:11+0900",

"articleContents" :[

{

"contentId" : 100,

"contentData" :


10

{

"title" : "【ニュース記事+サービス導線コンテンツあり】原子を動かして制作世界最小の動画",

"body" : "縦横数万分の１ミリずつしかない背景の上で、原子を１つずつ動かすことで制作された「世界一小

さなアニメーション動画」が完成し、ギネス世界記録に認定されました。",

“linkUrl”: “http://nhk.or.jp/test”,

"createdDate" : "2013-05-01T11:11:11+0900",

"sourceDomain" : "nhk.or.jp",

"sourceName" : "NHK オンライン"

},

},

{

"contentId" : 101,

"contentData" :

{

"title" : "【ニュース記事＋ボタン 3 つ】米で５歳児が誤射、２歳の妹死亡子ども向けライフルで",

"body" : "米ケンタッキー州バークスビル近くで４月３０日、５歳の男児が誤って２歳の妹をライフルで撃ち、

死なせる事件が起きた。",

“linkUrl”: “http://asahi.com/test”,

"createdDate" : "2013-05-01T11:11:11+0900",

"sourceDomain" : "asahi.com",

"sourceName" : "朝日新聞デジタル"

}

},

{

"contentId" : 102,

"contentData" :

{

"title" : "【ニュース記事＋追加ボタン】首相の歴史認識への批判に駐米大使反論",

"body" : "アメリカの新聞「ワシントン・ポスト」が安倍総理大臣の歴史認識を巡る発言を批判する社説を掲

載したことに対し、佐々江駐米大使が、日本は歴史に常に正面から向き合ってきたという内容の反論を投稿しま

した。",


"createdDate" : "2013-05-01T11:11:11+0900",



}


11

},

{

"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" : "埼玉県宮代町の東武動物公園でことし３月に誕生した珍しいトラ、ホワイトタイガーの赤ちゃんが

２日から一般に公開され、愛くるしい姿で訪れた人たちを楽しませています。 ",


"createdDate" : "2013-05-01T11:11:11+0900",



}

},

{

"contentId" : 105,

"contentData" :

{

"title" : "【ニュース記事】寺山修司さん没後３０年舞台や展覧会",

"body" : "詩人や劇作家など幅広い芸術活動を展開し影響を与え続けている寺山修司さんが亡くなって４日

で３０年を迎えることから、全国各地でゆかりのある舞台の上演や展覧会が相次ぎ寺山作品の魅力が見直され

ています。",


"createdDate" : "2013-05-01T11:11:11+0900",



12


}

},

{

"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 を指定することによりキーワードが含まれるトレンド記事を取得する。

・返却されるトレンド記事はコンテンツデータ取得と同様、１日に数回、定期的に更新される。

【備考】

・アクセスは HTTP リダイレクトされる可能性がある。

・コンテンツ数が n で指定された件数に満たない場合は、指定された件数以下でデータを返却する。

・本機能利用により、エンドユーザに好みのキーワードを入力させそのキーワードを含むトレンド

記事を取得する機能の設置が必須である。

URL・メソッド

リクエスト URL https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/search{.format}






13





パラメータ 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



1 totalResults 数値（0 以上の整 ○ コンテンツの全件数


14

数）

2 startIndex 数値（1 以上の整

数） ○

取得コンテンツの開始番号

3 itemsPerPage 数値（0 以上の整

数） ○

取得コンテンツの返却件数

4 issueDate 文字列

記事セットの作成時刻


custom が true の場合のみ返却され

る。

5 articleContents 配列（オブジェクト） ○ コンテンツの配列．※設定されたコンテ

ンツが無い場合空配列を返却

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 文字列 ○ 記事作成日時


15


6 sourceDomain 文字列 ○ 配信元ドメイン

7 sourceName 文字列 ○ 配信元名称


16

imageSize の要素


1 height 数値 ○ 画像の縦ピクセル数

2 width 数値 ○ 画像の横ピクセル数


コンテンツデータ取得を参照のこと。

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 共通


17

01 UUID 取得

02 SNS 認証取得

03 SNS 認証管理

04 ジャンル情報

05 カスタムジャンル情報

06 サービス設定

07 コンテンツデータ取得

08 サービス導線コンテンツデータ取得

09 キーワード関連コンテンツデータ取得

10 キーワードレコメンド結果取得

11 不適切コンテンツ情報

12 ログ情報


{

"error": {

"code": "010",

"message": "00：共通 HTTP リクエストパラメータが不正です。"

}

}


18

3. トレンド記事抽出 API の利用例

本章ではスポーツジャンルに関する Web 中のトレンド情報を取得するまでの流れを示します。

3.1. ジャンル情報の取得

まず、ジャンル情報取得のエンドポイントを用いてジャンル ID とジャンル名の紐づけを取得します。

本エンドポイント利用により、ジャンル ID「１」が「スポーツ」ジャンルであることがわかりました。


19

3.2. ジャンル ID 指定によるコンテンツデータ取得

スポーツジャンルのトレンド情報を取得するには、ジャンル ID「１」を指定してコンテンツデータ取得のエン

ドポイントにアクセスします。

トレンド記事抽出api...

Documents