認証完了 - Docomo.ne.jp

Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
トレンド記事抽出API
インタフェース仕様書
第 1.0 版
2014年2月3日
株式会社ＮＴＴドコモ
i
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
改版履歴
日付
2014/2/3
版
1.0
変更内容
初版
ii
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
目次
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
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
1. はじめに
「トレンド記事抽出 API」では、Web から収集したトレンド記事を収集できます。
トレンド記事はジャンル、もしくはキーワードを指定すると取得できます。
たとえば「スポーツ」ジャンルを指定すれば図１のような Web のニュース記事が取得できるでしょう。
トレンド記事の抽出に、Twitter 等の SNS をベースにしているためユーザ単位でのログインを推奨してい
ます。今後他の SNS 情報やパーソナライズを実施する場合は別の認証キーが必要になります。
図１．トレンド記事抽出 API にてスポーツに関するニュース記事を配信するアプリの例
1
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
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
2
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
説明
データのフォーマットを指定する
必須／オプション：オプション
値
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
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
<title>認証完了</title>
</head>
<body>
認証が完了しました。アプリケーションに戻ります。しばらくお待ちください。
</body>
</html>
4
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
2.4. ジャンル情報
2.4.1. ジャンル情報の取得
【機能概要】
・サーバ側で配信しているコンテンツジャンルを取得する。
・本機能を用いて genreId とジャンル名の対応を取得する。
【備考】
・取得した genreId をコンテンツデータ取得のエンドポイントにおいてクエリパラメータに設定することで、
各ジャンルのコンテンツデータを取得する。
URL・メソッド
リクエスト URL
https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/genre{.format}
HTTP メソッド
GET
パスパラメータ
パラメータ
format
説明
必須／オプション：オプション
デフォルト：json
値
json JSON 形式
クエリパラメータ
リクエスト例
# ジャンル設定情報を取得
GET https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/genre
レスポンス（JSON）
キー
値
必須
説明
配列（オブジェクト）
○
コンテンツジャンル及び設定情報
値
必須
説明
1 genreId
数値
○
ジャンルの ID（1 以上の整数）
2 title
文字列
○
ジャンルの表示名称（全角 20 文字）
3 description
文字列
ジャンルの説明文（全角 40 文字）
4 subGenre
配列（オブジェクト）
各ジャンルのサブジャンルの情報
1 genre
genre の要素
キー
5
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
subGenre の要素
キー
値
必須
説明
1 subGenreId
数値
○
サブジャンルの ID（100 以上の整数）
2 title
文字列
○
3 description
文字列
サブジャンルの表示名称（全角 20 文
字）
ジャンルの説明文（全角 40 文字）
レスポンス例（JSON 形式）
#ジャンル情報の取得
{
"genre": [
{
"genreId": 1,
"title": "スポーツ",
"description" : "スポーツニュースをお届けします！",
"subGenre" : [
{
"subGenreId" : 101,
"title" : "野球",
"description" : "野球ニュースをお届けします！"
},
{
"subGenreId" : 102,
"title" : "サッカー",
}
]
},
{
"genreId": 2,
"title": "グルメ",
"subGenre" : [
{
"subGenreId" : 201,
"title" : "イタリアン"
},
{
6
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
"subGenreId" : 202,
"title" : "中華"
}
]
},
...
]
}
2.5. コンテンツデータ取得
【機能概要】
・genreId を指定し、各ジャンルで配信されているトレンド記事を取得する。
・トレンド記事は１日に数回、定期的に更新される。
【備考】
・アクセスは HTTP リダイレクトされる可能性がある。
・コンテンツ数が n で指定された件数に満たない場合は、指定された件数以下でデータを返却する。
URL・メソッド
リクエスト URL
https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/contents{.format}
HTTP メソッド
GET
パスパラメータ
パラメータ
format
説明
データのフォーマットを指定する
必須／オプション：オプション
デフォルト：json
値
json JSON 形式
クエリパラメータ
パラメータ
genreId
説明
表示設定されている genreId を指定する
必須／オプション：必須
値
表示設定している genreId
パラメータ
s
説明
コンテンツ一覧の開始番号を指定する
7
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
必須／オプション：オプション
デフォルト：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
2 startIndex
3 itemsPerPage
値
数値（0 以上の整
数）
数値（1 以上の整
数）
数値（0 以上の整
数）
必須
○
○
○
4 issueDate
文字列
○
5 articleContents
配列（オブジェクト）
○
値
必須
説明
コンテンツの全件数
取得コンテンツの開始番号
取得コンテンツの返却件数
記事セットの作成時刻
YYYY-MM-DDThh:mm:ssTZD
コンテンツの配列．※設定されたコンテ
ンツが無い場合空配列を返却
articleContents の要素
キー
説明
コンテンツの識別子、すべてのコンテン
1 contentId
数値
○
ツでユニークな値（ long 型：
9223372036854775807 まで）
コンテンツ種別（サーバから任意の値
2 contentType
数値
が指定されます。記事がレコメンド記事
か、そうでないか区別可能にするため
8
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
に送付されます。
10:記事コンテンツ
11:レコメンド記事コンテンツ
3 contentData
オブジェクト
○
表示するコンテンツデータ
値
必須
説明
1 title
文字列
○
2 body
文字列
3 linkUrl
文字列
4 imageUrl
文字列
5 imageSize
オブジェクト
6 createdDate
文字列
○
7 sourceDomain
文字列
○
配信元ドメイン
8 sourceName
文字列
○
配信元名称
contentData の要素
キー
コンテンツのタイトル（表示文字を超え
る場合はアプリ側で省略処理を実施）
コンテンツの本文（表示文字を超える
場合はアプリ側で省略処理を実施）
○
元記事の URL
コンテンツの写真の URL
コンテンツ中の写真のサイズ。縦 px,横
px で指定。
記
事
作
成
日
時
YYYY-MM-DDThh:mm:ssTZD
imageSize の要素
キー
値
必須
説明
1 height
数値
○
画像の縦ピクセル数
2 width
数値
○
画像の横ピクセル数
レスポンス例（JSON 形式）
{
"totalResults" : 10,
"startIndex" : 1,
"itemsPerPage" : 10,
"issueDate" : "2013-05-01T11:11:11+0900",
"articleContents" :[
{
"contentId" : 100,
"contentData" :
9
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
{
"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" : "アメリカの新聞「ワシントン・ポスト」が安倍総理大臣の歴史認識を巡る発言を批判する社説を掲
載したことに対し、佐々江駐米大使が、日本は歴史に常に正面から向き合ってきたという内容の反論を投稿しま
した。",
“linkUrl”: “http://asahi.com/test”,
"createdDate" : "2013-05-01T11:11:11+0900",
"sourceDomain" : "asahi.com",
"sourceName" : "朝日新聞デジタル"
}
10
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
},
{
"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" : "埼玉県宮代町の東武動物公園でことし３月に誕生した珍しいトラ、ホワイトタイガーの赤ちゃんが
２日から一般に公開され、愛くるしい姿で訪れた人たちを楽しませています。 ",
“linkUrl”: “http://asahi.com/test”,
"createdDate" : "2013-05-01T11:11:11+0900",
"sourceDomain" : "asahi.com",
"sourceName" : "朝日新聞デジタル"
}
},
{
"contentId" : 105,
"contentData" :
{
"title" : "【ニュース記事】寺山修司さん没後３０年舞台や展覧会",
"body" : "詩人や劇作家など幅広い芸術活動を展開し影響を与え続けている寺山修司さんが亡くなって４日
で３０年を迎えることから、全国各地でゆかりのある舞台の上演や展覧会が相次ぎ寺山作品の魅力が見直され
ています。",
“linkUrl”: “http://asahi.com/test”,
"createdDate" : "2013-05-01T11:11:11+0900",
"sourceDomain" : "asahi.com",
11
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
"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 を指定することによりキーワードが含まれるトレンド記事を取得する。
・返却されるトレンド記事はコンテンツデータ取得と同様、１日に数回、定期的に更新される。
【備考】
・アクセスは HTTP リダイレクトされる可能性がある。
・コンテンツ数が n で指定された件数に満たない場合は、指定された件数以下でデータを返却する。
・本機能利用により、エンドユーザに好みのキーワードを入力させそのキーワードを含むトレンド
記事を取得する機能の設置が必須である。
URL・メソッド
リクエスト URL
https:// api.apigw.smt.docomo.ne.jp/webCuration/v1/search{.format}
HTTP メソッド
GET
パスパラメータ
パラメータ
format
説明
データのフォーマットを指定する
12
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
必須／オプション：オプション
デフォルト：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
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
数）
2 startIndex
3 itemsPerPage
数値（1 以上の整
数）
数値（0 以上の整
数）
○
○
取得コンテンツの開始番号
取得コンテンツの返却件数
記事セットの作成時刻
4 issueDate
YYYY-MM-DDThh:mm:ssTZD
文字列
custom が true の場合のみ返却され
る。
5 articleContents
配列（オブジェクト）
○
値
必須
コンテンツの配列．※設定されたコンテ
ンツが無い場合空配列を返却
articleContents の要素
キー
説明
コンテンツの識別子、すべてのコンテン
1 contentId
数値
○
ツでユニークな値（ long 型：
9223372036854775807 まで）
コンテンツ種別（サーバから任意の値
が指定されます。記事がレコメンド記事
2 contentType
か、そうでないか区別可能にするため
数値
に送付されます。
10:記事コンテンツ
11:レコメンド記事コンテンツ
3 contentData
オブジェクト
○
表示するコンテンツデータ
値
必須
説明
1 title
文字列
○
2 body
文字列
3 linkUrl
文字列
3 imageUrl
文字列
4 imageSize
オブジェクト
5 createdDate
文字列
contentData の要素
キー
コンテンツのタイトル（表示文字を超え
る場合はアプリ側で省略処理を実施）
コンテンツの本文（表示文字を超える
場合はアプリ側で省略処理を実施）
○
元記事の URL
コンテンツの写真の URL
コンテンツ中の写真のサイズ。縦 px,横
px で指定。
○
記事作成日時
14
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
YYYY-MM-DDThh:mm:ssTZD
6 sourceDomain
文字列
○
配信元ドメイン
7 sourceName
文字列
○
配信元名称
15
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
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
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
01
UUID 取得
02
SNS 認証取得
03
SNS 認証管理
04
ジャンル情報
05
カスタムジャンル情報
06
サービス設定
07
コンテンツデータ取得
08
サービス導線コンテンツデータ取得
09
キーワード関連コンテンツデータ取得
10
キーワードレコメンド結果取得
11
不適切コンテンツ情報
12
ログ情報
レスポンス例（JSON 形式）
{
"error": {
"code": "010",
"message": "00：共通
HTTP リクエストパラメータが不正です。"
}
}
17
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
3.
トレンド記事抽出 API の利用例
本章ではスポーツジャンルに関する Web 中のトレンド情報を取得するまでの流れを示します。
3.1. ジャンル情報の取得
まず、ジャンル情報取得のエンドポイントを用いてジャンル ID とジャンル名の紐づけを取得します。
本エンドポイント利用により、ジャンル ID「１」が「スポーツ」ジャンルであることがわかりました。
18
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
3.2. ジャンル ID 指定によるコンテンツデータ取得
スポーツジャンルのトレンド情報を取得するには、ジャンル ID「１」を指定してコンテンツデータ取得のエン
ドポイントにアクセスします。
19

Download Report