本記事は、めんどい太郎の 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リクエストを送るだけですし。
ですが、細かい仕様の違いに苦労しました。