iTunes Search APIを使って音楽検索をしてみる

本記事は、[めんどい太郎の Advent Calendar 2023](https://qiita.com/advent-calendar/2023/mendoitarou_first_calendar) 9日目の記事です。

# はじめに

この記事は初心者が書いています。

今回はiTunes Search APIを使って音楽検索をしていきます。

# iTunes Search APIとは

iTunesのアイテムを検索できるAPIです。

iTunesには音楽以外にも、アプリや書籍など様々なものが登録されていますのでそれらも検索できます。

詳しくはドキュメントを読んでみてください。(英語ですが)

https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/index.html

# 試す

早速試してみましょう。

といっても、iTunes Search APIはGETリクエストを送信するだけです。簡単。

とりあえずリクエストを送ってみましょう。

```Shell
curl "https://itunes.apple.com/search?lang=ja_jp&country=jp&limit=1&media=music&entity=album&term=futurebase"
```

こんなリクエストを送信します。

するとJSONが返ってきます。

この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をもう一度見てみましょう。

```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``になります。

```JSON
{
 "resultCount":0,
 "results": []
}
```

それでは、``results``の中の要素名を軽く紹介します。

| 要素名 | 概要 |
|:-:|:-|
| wrapperType || 返ってきたデータの種類です。``collection``や``artist``が返ってきます。 |
| 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を見ておくと良いと思います。

というかドキュメントには一応書いてくれています。

https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/UnderstandingSearchResults.html#//apple_ref/doc/uid/TP40017632-CH8-SW1

## IDから検索

IDから検索する場合はURLが変わります。

```Shell
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リクエストを送るだけですし。

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