1. TOP
  2. PRODUCT
  3. Listing API

リスト生成をするためのAPIです。
ユーザーの行動ログを元にアイテム間の相関リストや、各ユーザーへのレコメンドリストなどを生成することが出来ます。オンラインレコメンドや、ターゲティングメールなどに使用します。
モデルリングのためのデータを手元に用意していただければ、元データアップロード・リスト生成ロジック実行・リストダウンロードの機能が利用出来ます。
version1で利用できるアルゴリズムは、word2vecのみとなります。

DETAIL

レコメンドリスト、アイテム間の相関リストなど、リストを生成するためのAPIです。
リクルート内ではリスト生成のためのアルゴリズムには様々なものを用いています。イチから実装することをせずに、複数のサービスで共通的に利用できるように汎用化させたものがListing APIです。ログをアップロードし、APIのパラメータでアルゴリズム選択・パラメータ設定することでリストを簡単に作成することが可能になります。
新しいアルゴリズムを開発すると、汎用化した上で新機能として随時追加しています。

NOTES

他人の名称・メールアドレス・住所・電話番号など個人を特定しうる情報はアップロードしないでください。

REFERENCE

w2vを使いレコメンドリストを作成します

エンドポイント

URL:
https://api.a3rt.recruit-tech.co.jp/listing/v1/
メソッド:
GET
No. エンドポイント 説明
1 get_upload_url 演算対象ファイルをアップロードするURLを取得します
2 start_w2v w2v演算を開始します
3 status_w2v w2v演算の処理ステータスを取得します
4 get_download_url 演算結果ファイルをダウンロードするURLの取得します
5 cancel_w2v w2v演算の処理を中断します

リクエストパラメータ

No. パラメータ名 説明 値サンプル 制約 必須
1 apikey APIキーを指定します AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 半角英数字
2 payload webhookの通知先URLを指定します {"_url":"<WEBHOOK_URL>"} 半角英数字 -

レスポンスフィールド

No. フィールド名 説明 値サンプル 返却条件 複数項目
1 status 処理ステータス 0 int 常に返却 -
2 message メッセージ ok string 常に返却 -
3 result 結果
url URL string get_upload_url,get_download_url
正常時に返却
-

ステータスコード / メッセージ

No. status HTTP
status
message 返却条件
1 0 200 ok 正常応答
2 0 200 STARTING instance w2vインスタンスを起動中
3 0 200 SHUTDOWN instance w2vインスタンスをシャットダウン中
4 0 200 STOPPING instance w2vインスタンスを停止中
5 0 200 train data file size exceeds the maximum limit 学習データファイルサイズが大きすぎる(status_w2vの返却値)
6 0 200 train data size exceeds the maximum limit 学習データサイズが大きすぎる(status_w2vの返却値)
7 0 200 train data format error 学習データのフォーマットが不正(status_w2vの返却値)
8 0 200 listing file creation failed リスティングファイル作成エラー(status_w2vの返却値)
9 1000 400 apikey is null APIキー未指定
10 1001 400 apikey not found APIキーが見つからない
11 1002 400 deleted account 退会済み
12 1003 400 temporary account アカウント未承認
13 1010 400 server not found サーバが見つからない
14 1011 400 server parameter error サーバ設定エラー
15 1030 403 access deny アクセス拒否
16 1400 400 api busy 60秒以内に同一のAPIを実行しようとした
17 1400 400 listing file not found リスティングファイルが見つからない
18 1400 400 train data file not found 学習データファイルが見つからない
19 1400 400 train data not found 学習データが見つからない
20 1400 400 train data file size exceeds the maximum limit 学習データファイルサイズが大きすぎる
21 1400 400 webhook error webhook設定が正しくない
22 1400 400 instance is exist すでに、w2vインスタンスが起動されている
23 1400 400 instance not found 起動されているw2vインスタンスは見つからない
24 1403 403 forbidden インスタンス起動の上限に達した
25 1404 404 not found 指定したオブジェクト見つからない
26 1405 405 method not allowed メソッドが正しくない
27 1500 500 internal server error API処理で異常が発生しました

制限事項

API実行に関する制限事項

同一のAPI呼び出しは最低60秒以上待ってから実行してください、60秒以内のアクセス時に'400 Bad Request(API busy)'を返却します、その場合はしばらくお待ちのあと再実行をお願いします

ファイルに関する制限事項

アップロードファイルサイズ:100MB以下
データ行数:100万行以内
レコメンド結果件数:10件

ブラウザによるファイルのアップロードは、今後対応していく予定です

演算インスタンスに関する制限事項

バージョンv1では、最大10並列までとなります
並列処理の最大時には、演算開始時に'403 Forbidden'(上限エラー)を返却する事があります、その場合はしばらくお待ちのあと再実行をお願いします

ファイルフォーマット

学習データ(アップロードファイル)

CSV形式のテキストファイル

英数字(多バイト文字コードは未サポート)

行ヘッダあり(1行目に user_id,item_id,time_stamp が必要)

制限事項:

アップロードファイルサイズ:100MB以下
データ行数:100万行以内

No. フィールド名 説明 値サンプル
1 user_id ユーザーを識別できるID 01234567890123456789
2 item_id アイテムを識別できるID 01234567
3 time_stamp 時刻(アクセス時間を想定) 2017-01-10 21:11:41.990

演算結果(ダウンロードファイル)

CSV形式のテキストファイル

英数字(多バイト文字コードは未サポート)

行ヘッダなし

制限事項:

レコメンド結果件数:10件

No. フィールド名 説明 値サンプル
1 user_id ユーザーを識別できるID 01234567890123456789
2 item_list   ※レコメンド件数は10件まで アイテムを識別できるID 01234567
item_id アイテムを識別できるID 01234567
スコア値 類似度 0.948221981525
, リスト内もカンマ区切り ,
item_id アイテムを識別できるID 01234567
スコア値 類似度 0.928403615952

SAMPLE REQUEST

前提条件
  • APIキーを事前に取得している、'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'と表記
  • curlコマンドが実行できる環境がある
  • アップロードする演算対象ファイル名を'train_data.csv'と表記
  • ダウンロードする演算結果ファイル名を'output_list.csv'と表記

1)演算対象ファイルアップロードURLの取得

リクエスト curl "https://api.a3rt.recruit-tech.co.jp/listing/v1/get_upload_url" \
--get \
--data "apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
レスポンス

{
	status: 0,
	message: "ok",
	result: {"url": "https://www.・・・"}
}

※メッセージ内 url の httpsから始まる文字列をコピーします

2)演算対象ファイルのアップロード

リクエスト メモ帳に以下の二行を用意し、コマンド文字列を編集します
export UPLOAD_LOCATION='①でコピーした文字列をペーストします'
curl -H 'Content-Type: text/plain' -X PUT --upload-file train_data.csv "$UPLOAD_LOCATION"
レスポンス プロンプトが戻れば、アップロード終了です

3)w2v演算処理開始

リクエスト curl "https://api.a3rt.recruit-tech.co.jp/listing/v1/start_w2v" \
--get \
--data "apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
レスポンス

{
status: 0, message: "STARTING instance" }

4)w2v演算処理のステータス取得

リクエスト curl "https://api.a3rt.recruit-tech.co.jp/listing/v1/status_w2v" \
--get \
--data "apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
レスポンス

{
	status: 0,
	message: "STARTING instance"
}
※演算に時間がかかるため、最大60分程度時間を待ってから確認してください
演算が終了すると以下のステータスを返します
{
	status: 0,
	message: "SHUTDOWN instance"
}

5)演算結果ファイルダウンロードURLの取得

リクエスト curl "https://api.a3rt.recruit-tech.co.jp/listing/v1/get_download_url" \
--get \
--data "apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
レスポンス

{
	status: 0,
	message: "ok",
	result: {"url": "https://www.・・・"}
}

※メッセージ内 url の httpsから始まる文字列をコピーします

6)演算結果ファイルのダウンロード

リクエスト メモ帳に以下の二行を用意し、コマンド文字列を編集します
export DOWNLOAD_LOCATION='⑤でコピーした文字列をペーストします'
curl -o output_list.csv "$DOWNLOAD_LOCATION"
レスポンス プロンプトが戻れば、ダウンロード終了です

7)w2v演算処理の中断(※演算処理の中断の場合は後処理があり、すぐにやり直すことができません、ご了承ください)

リクエスト curl "https://api.a3rt.recruit-tech.co.jp/listing/v1/cancel_w2v" \
--get \
--data "apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
レスポンス

{
	status: 0,
	message: "STOPPING instance"
}

注.webhookを使う場合には、webhookの通知先URLを事前に取得し、下記のように記述してください

リクエスト curl "https://api.a3rt.recruit-tech.co.jp/listing/v1/status_w2v" \
--get \
--data "apikey=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" \
--data "payload={\"_url\":\"https://example.com/webhook_url...\"}"
レスポンス

{
	status: 0,
	message: "ok"
}

※webhook先のURLへ、{"text": "メッセージ"}というJSON文字列が送信されます