本記事は、めんどい太郎の Advent Calendar 2023 9日目の記事です。
はじめに
この記事は初心者が書いています。
今回はiTunes Search APIを使って音楽検索をしていきます。
iTunes Search APIとは
iTunesのアイテムを検索できるAPIです。
iTunesには音楽以外にも、アプリや書籍など様々なものが登録されていますのでそれらも検索できます。
詳しくはドキュメントを読んでみてください。(英語ですが)
試す
早速試してみましょう。
といっても、iTunes Search APIはGETリクエストを送信するだけです。簡単。
とりあえずリクエストを送ってみましょう。
curl "https://itunes.apple.com/search?lang=ja_jp&country=jp&limit=1&media=music&entity=album&term=futurebase"
こんなリクエストを送信します。
するとJSONが返ってきます。
このJSONが楽曲データです。
さっきのリクエストを送ったときに実際に返ってきたデータを載せておきます。
{
"resultCount":1,
"results": [
{"wrapperType":"collection", "collectionType":"Album", "artistId":1410047993, "collectionId":1439855219, "artistName":"Kizuna AI (キズナアイ)", "collectionName":"Future Base - Single", "collectionCensoredName":"Future Base - Single", "artistViewUrl":"https://music.apple.com/jp/artist/kizuna-ai-%E3%82%AD%E3%82%BA%E3%83%8A%E3%82%A2%E3%82%A4/1410047993?uo=4", "collectionViewUrl":"https://music.apple.com/jp/album/future-base-single/1439855219?uo=4", "artworkUrl60":"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/91/c5/1b/91c51bdd-6c70-08ce-688f-7d959333d237/859754518640_cover.jpg/60x60bb.jpg", "artworkUrl100":"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/91/c5/1b/91c51bdd-6c70-08ce-688f-7d959333d237/859754518640_cover.jpg/100x100bb.jpg", "collectionPrice":255.00, "collectionExplicitness":"notExplicit", "trackCount":1, "copyright":"℗ 2018 upd8 music", "country":"JPN", "currency":"JPY", "releaseDate":"2018-10-26T07:00:00Z", "primaryGenreName":"エレクトロニック"}]
}
パラメーター
GETリクエストをおくるときのパラメーターを紹介します。
パラメータ | 概要 |
---|---|
lang | 返ってくるデータの言語が指定できます。 |
country | 検索するマーケットの国を指定できます。 |
limit | 検索結果として返すデータの個数制限を指定できます。 |
media | 検索するデータの種類を指定します。music やall などです。 |
entity | 検索するデータの細かい種類を指定します。楽曲の場合はsong やalbum などです。 |
term | 検索文字列を指定します。+ で複数指定できます。 |
だいたいこんな感じです。
https://itunes.apple.com/search?lang=ja_jp&country=jp&limit=1&media=music&entity={song,album,musicArtist}&term={title}+{artist_name}
こんな感じで使うとだいたい思っていたものが取得できます。
({}は各自で指定してください。)
ここで注意すべきなのが、曲によってはentity
がsong
だと結果が0でalbum
にすると表示されるなんてものがあったりします。
シングルなんかは特に多いですね。
また、シングルのアルバム名はたいてい曲名 - Single
のようになっています。
返ってきたJSON
返ってきたJSONをもう一度見てみましょう。
{
"resultCount":1,
"results": [
{"wrapperType":"collection", "collectionType":"Album", "artistId":1410047993, "collectionId":1439855219, "artistName":"Kizuna AI (キズナアイ)", "collectionName":"Future Base - Single", "collectionCensoredName":"Future Base - Single", "artistViewUrl":"https://music.apple.com/jp/artist/kizuna-ai-%E3%82%AD%E3%82%BA%E3%83%8A%E3%82%A2%E3%82%A4/1410047993?uo=4", "collectionViewUrl":"https://music.apple.com/jp/album/future-base-single/1439855219?uo=4", "artworkUrl60":"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/91/c5/1b/91c51bdd-6c70-08ce-688f-7d959333d237/859754518640_cover.jpg/60x60bb.jpg", "artworkUrl100":"https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/91/c5/1b/91c51bdd-6c70-08ce-688f-7d959333d237/859754518640_cover.jpg/100x100bb.jpg", "collectionPrice":255.00, "collectionExplicitness":"notExplicit", "trackCount":1, "copyright":"℗ 2018 upd8 music", "country":"JPN", "currency":"JPY", "releaseDate":"2018-10-26T07:00:00Z", "primaryGenreName":"エレクトロニック"}]
}
整形されてないので人間が見るには見ずらいですね。
軽く要素名を紹介します。
要素名 | 概要 |
---|---|
resultCount | 検索結果の項目数 |
results | 検索結果 |
大まかにみて2つあり、resultCount
で検索結果の項目数をみてresults
で詳しい情報をみるという感じです。
ちなみに、検索結果がなかった場合はresultCount
が0
になります。
{
"resultCount":0,
"results": []
}
それでは、results
の中の要素名を軽く紹介します。
要素名 | 概要 |
---|---|
wrapperType | |
collectionType | 更に細かい種類です。Album とかが返ってきます。 |
artistType |
wrapperType がartist の場合はcollectionType ではなくこちらが返ってきます。 |
iTunes Search APIで気をつけなければいけないのが、wrapperType
までは一緒なのですがこの値によって項目名が変わるということです。
だいたい{wrapperType}{Type, Name, ...}
のようになっています。
また、アーティスト情報を取得した場合は項目が少ないのとアーティスト写真は取得できません。
次の表はアルバム情報を取得した場合ですが、アーティスト情報や楽曲情報を取得した場合も同じような感じです。
要素名 | 概要 |
---|---|
artistId | 楽曲のアーティストのIDです。 |
collectionId | アルバムのIDです。 |
artistName | 楽曲のアーティストの名前です。 |
collectionName | アルバム名です。 |
artistViewUrl | アーティストページのURLです。 |
collectionViewUrl | アルバムページのURLです。 |
artworkUrl{Size} | アルバム写真のURLです。{Size} には写真の大きさが入ります。 |
collectionPrice | アルバムの料金です。country で指定した国の通貨で返されると思われます。 |
trackCount | アルバムの曲数です。 |
copyright | 著作権表示です。 |
country | 国情報です。おそらくcountry で指定した国と同じになると思われます。 |
releaseDate | リリースされたタイムスタンプです。 |
primaryGenreName | アルバムの楽曲タイプです。エレクトロニックなどです。 |
だいたいこんな感じです。
iTunes Search APIは取得するデータによって項目数が変わったりするので大変です。
プログラムに組み込むときは一度curl
で返ってきたJSONを見ておくと良いと思います。
というかドキュメントには一応書いてくれています。
IDから検索
IDから検索する場合はURLが変わります。
curl "https://itunes.apple.com/lookup?lang=ja_jp&country=jp&limit=1&media=music&entity={song,album,musicArtist}&id={id}"
こんな感じです。
search
がlookup
になって、term
がid
に変わったぐらいです。
返ってくるデータはsearch
と同じです。
おわりに
iTunes Search APIはApple Musicの楽曲検索をするときに使用したことがあります。
ちょっとややこしい仕様があったりしますが、ユーザー登録不要で使えるので便利ですね。
GETリクエストを送るだけですし。
ですが、細かい仕様の違いに苦労しました。