本記事は、めんどい太郎の 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リクエストを送るだけですし。

ですが、細かい仕様の違いに苦労しました。