○レコメンデーションAPIは、曲名、アーティスト名、ジャンル、年代、ムードなどのメタデータを元にラジオステーション(プレイリスト)を自動作成できるAPIです。
 
○楽曲の属性情報は、Gracenoteの音楽エキスパートチームが実際に曲を聞きながら行うデータ編集作業と、楽曲解析技術+機会学習により導きだされ付与されている信頼性の高いものです。
 
○レコメンデーションAPIはユーザーからのフィードバックを機能としてサービスの盛り込むことも可能です。ユーザーはアーティストやトラックに対してlikesやdislikesのかたちでフィードバックを返すことができます。
 

以下のリンクにドキュメントとレファレンスを載せています。ご参照下さい。

Rhythm API Developer's Guide and Reference

Interactive Rhythm API console

 

Endpoint URL

Rhythm APIに下記のURLにリクエストを送ります:

https://cXXXXXXX.web.cddbp.net/webapi/FORMAT/1.0/

FORMATはjsonあるいはxml(以降の例はすべてJSONで行います)、XXXXXXXはClient IDのハイフン前の部分になります。 例えば、レスポンスをJSONのフォーマットで受け取り、ClientIDが"1234567-09876543210987654321"(これは本当のClientIDではありません) の場合、リクエストを次のURLに送ります

https://c1234567.web.cddbp.net/webapi/json/1.0/

 

ユーザの登録

 

すべてのGracenoteAPIと同じように、GracenoteのサービスをコールするためにUserIDが必要になります。 ユーザーIDを登録するためには、次のURLにリクエストをお送りください

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/register?client=CLIENT_ID

CLIENT_IDは"My Apps"に付与されたClientIDになります。返されたUserIDを保存し、このユーザーの今後のすべてのコールで使ってください。

初めてのラジオステーション

ラジオステーションを作るには一番簡単なのはアーティストの名前で作る方法です。次のコールは"宇多田ヒカル"をベースにラジオステーションを作ります:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/create?artist_name=宇多田ヒカル&lang=jpn&client=CLIENT_ID&user=USER_ID

Response (一部トランケートされた)

{
    "RESPONSE": [
        {
            "STATUS": "OK", 
            "RADIO": [
                {
                    "ID": "150d184ac48104f1cc4fa27fe8523e36"
                }
            ], 			
            "ALBUM": [
                {
                    "ARTIST": [
                        {
                            "VALUE": "宇多田ヒカル"
                        }
                    ], 
                    "GN_ID": "225883786-10316CD0E47B02773DDAEC816A06FD67", 
                    "ORD": "1", 
                    "TITLE": [
                        {
                            "VALUE": "Utada Hikaru SINGLE COLLECTION VOL. 2 [Disc 1]"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "225883793-36A289F58996EE8D955F5ED0917705C0", 
                            "TITLE": [
                                {
                                    "VALUE": "ぼくはくま"
                                }
                            ], 
                            "TRACK_NUM": "7"
                        }
                    ], 
                    "TRACK_COUNT": "13"
                }, 
                {
                    "ARTIST": [
                        {
                            "VALUE": "Various Artists"
                        }
                    ], 
                    "GN_ID": "205109949-11DC5DE80FAA74BF0773677253361893", 
                    "ORD": "2", 
                    "TITLE": [
                        {
                            "VALUE": "月刊エレクトーン2010年3月 参考演奏CD"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "205109950-52275EC75927913A364A73D98B380859", 
                            "TITLE": [
                                {
                                    "VALUE": "さくら"
                                }
                            ], 
                            "TRACK_NUM": "1"
                        }
                    ], 
                    "TRACK_COUNT": "7"
                }
            ]
        }
    ]
}

ご覧のように、RadioID、それからはじめの五曲はデフォルトで返されます。このRadioIDは後ほどプレーキューに進む際に 必要になります、またステーションを個人化するためフィードバックを送る際にも必要になります。

トラックからラジオステーションを生成

トラックからラジオステーションを作るためには、"track_title"と"artist_name"を指定します。例えば、

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/create?artist_name= EXILE&track_title=優しい光&lang=jpn&client=CLIENT_ID&user=USER_ID

上記のアーティストベースのレスポンスと似たようなトラックのプレイリストが返されます。

ジャンル、ムード、あるいは年代からラジオステーションを生成

ジャンル(ElectronicaやAlternativeなど)、ムード(SophisticatedやSensualなど)、それから年代(1980年代や1960年代など) からラジオステーションを作ることも可能です。其々の属性のオプションリストを見るためには、まず"fieldvalues"メソッドを コールする必要があります。

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/fieldvalues?fieldname=ATTRIBUTE&lang=jpn&client=CLIENT_ID&user=USER_ID

ATTRIBUTE = RADIOGENRE, RADIOMOOD, あるいはRADIOERAで指定してください。 次のレスポンス(一部トランケートされた)のように、IDとその名前のリストで返されます:


{
        "RESPONSE": [
            {
                "STATUS" : "OK",
                "MOOD": [
                    {
                        "ID" : "65322",
                        "VALUE" : "ピースフル"
                    },
                    {
                        "ID" : "65323",
                        "VALUE" : "ロマンティック"
                    },
                    {
                        "ID" : "65324",
                        "VALUE" : "センチメンタル"
                    }
                ]
            }
        ]
}

ラジオステーションを作るには、ラジオ生成メソッドに好きなジャンル、ムード、年代パラメータに上記のレスポンスにある適切なIDフィールド を使ってください。一つのクエリにジャンル、ムード、年代を合わせて使うこともできます、次のサンプルのように、"1990's, Sentimental, Indie Rock" でラジオステーションを作ります。

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/create?genre=35287&mood=65324&era=29484&lang=jpn&client=CLIENT_ID&user=USER_ID

Response(一部トランケートされた)


{
    "RESPONSE": [
        {
            "STATUS": "OK",
            "RADIO": [
                {
                    "ID": "9444ff8e089819d385d54efd3b140162"
                }
            ], 
            "ALBUM": [
                {
                    "ARTIST": [
                        {
                            "VALUE": "Trashcan Sinatras"
                        }
                    ], 
                    "GN_ID": "7354762-DC47A71888C447B903FDD1FEC0D7137D", 
                    "ORD": "1", 
                    "TITLE": [
                        {
                            "VALUE": "I've Seen Everything"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "7354767-5E7A005790D238B78B102F2A0DE5FD9A", 
                            "TITLE": [
                                {
                                    "VALUE": "The Perfect Reminder"
                                }
                            ], 
                            "TRACK_NUM": "5"
                        }
                    ], 
                    "TRACK_COUNT": "14"
                }, 
                {
                    "ARTIST": [
                        {
                            "VALUE": "Mary Lou Lord"
                        }
                    ], 
                    "GN_ID": "7935475-2862207B6B6DD3568D888CD77EAD461B", 
                    "ORD": "2", 
                    "TITLE": [
                        {
                            "VALUE": "Mary Lou Lord"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "7935483-009D362AB506168DF6646E013EAFE72A", 
                            "TITLE": [
                                {
                                    "VALUE": "Speeding Motorcycle"
                                }
                            ], 
                            "TRACK_NUM": "8"
                        }
                    ], 
                    "TRACK_COUNT": "8"
                }
             ]
        }
    ]
}

特定のジャンル、ムード、年代の組み合わせを使うことで、もらえる結果が制限されることがあります。

リージョン設定

Gracenoteの属性IDとその値はリージョンごとに異なります (例えば、とある国に"World Music"と考えられるものは別の国では"Traditional"と考えられているかも知れません)。リージョンを指定するには、'fieldvalues'のメソッドをコールする時に'country'パラメータを入れるとできます、国コードの定義はISO 3166-1 alpha 3を参照してください(例:'usa'はアメリカ、'jpn'は日本)。例えば、日本リージョンのジャンルステーションを見るには、次のリクエストを実行します:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/fieldvalues?country=jpn&fieldname=RADIOGENRE&client=CLIENT_ID&user=USER_ID

APIからのレスポンスの言語(サポートされる言語のみ)を変更するには、'lang'パラメータに3文字ISO 639-2 language codeコードを指定します(例:'eng'は英語、'jpn'は日本語). 例えば、フランス語のすべてのムードステーションを見るには、次のようなリクエストを実行します:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/fieldvalues?lang=fre&fieldname=RADIOMOOD&client=CLIENT_ID&user=USER_ID

 

オプショナルパラメータ

 

パラメータ デフォルト値 説明
focus_similarity 0から1000までの整数 1000 (最も類似) ステーションの曲がどれほどシードアーティストあるいはシードトラックと類似するかを制御する(属性ラジオステーションに適応できません), 0が最も類似しない、1000が最も類似する
focus_popularity 0から1000までの整数 1000 (最もポピュラー) ステーションの曲のポピュラー度を制御する、0がポピュラー最も低く、1000がポピュラー度最も高い
dmca {yes,no} no DMCAを"yes"に設定することで、DMCAルールによって、同じアーティストからのトラック数を制限します。DMCAルールはステーションが生成してから変更できません。ステーション生成するときに、DMCAを指定しなけれいけません。
return_count Integer 5 APIに何曲返ってほしいを通知する
select_extended {cover,link} None "cover"はトラックずつアルバムカバーアートのリンクを追加します。”link”は3rdパーティと情報交換するための外部IDをを追加します。(外部IDの可用性はClientIDの権限レベルに依存することをご注意ください) このパラメータの複数値指定はコンマで区切ります
lang 3文字ISO 639-2 language code eng (英語) レスポンスの言語を設定する(サポートされる言語のみ)
country 3文字ISO 3166-1 alpha 3 country code usa リージョンシステムを指定する(サポートされるリージョンのみ)

フィードバックの送信、それからもっと多いトラックのゲット

このAPIは個人化のラジオサービスのため、ユーザーイベントが起こる度、APIはアプリからの通知を期待しています。 ユーザーイベントは、あるトラックがプレイされたり、スキップされたり、あるトラックかアーティストが"like"あるいは"dislike"されたり などのことを指します。異なるユーザーイベントに対して、APIは異なる反応をします。 サポートされるイベントタイプは次のようになります:


track_played - トラックにプレー済のマークをつける。プレーキューは移動される(プレー済の曲をドロップし、新しい曲をキューの最後に追加する)

track_skipped - トラックに”skipped”をつける。 プレーキューが移動する.

track_like - トラックに"liked"をつける。プレーキューは移動しない

track_dislike - トラックに”disliked”をつける。 プレーキューがリフレッシュされる

artist_like - アーティストに”liked”をつける。プレーキューは移動しない

artist_dislike - アーティストに”disliked”をつける。 プレーキューがリフレッシュされる

 

コールが成功したら、"success"ステータスと共に、フィードバックに基づいた新しいトラックセットが返されます。例えば、ステーションを作り、はじめの五曲をもらいました、そして一曲目に"track_played"イベントを付けて送信したら、5曲のレスポンスがもらえます:トラック1-4は前のレスポンスの2-5で、トラック5は新たに追加されたものです。(例、プレーキューは “一個上に移動した”).

アーティストに"dislike"を付けた場合、キューのすべてが取替えられます。上記のフィードバックタイプと共に、GN_ID(通常はラジオ生成コールでもらっている)それからトラックGN_IDを付ける必要があります、 例えば、12345-ABCDEF:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/event?radio_id=RADIO_ID&event=track_played_12345-ABCDEF&client=CLIENT_ID&user=USER_ID

 

複数のイベントを一つのコールにまとめることが可能です。次の例は、どうやってAPIにユーザーがトラック"12345"をdislikeし、スキップしたことを知らせるリクエストです:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/event?radio_id=RADIO_ID&event=track_dislike_12345-ABCDEF;track_skipped_12345-ABCDEF&client=CLIENT_ID&user=USER_ID

 

APIドキュメント

 

RhythmAPIの詳細と上級なトピックス、例えば:'先取り'、'レコメンデーション'、'XMLオプション'などは次のドキュメントを参照してください:

 

Rhythm API Reference