itunes-store-api

💿 Query Apple store catalogs using the iTunes Search API.

• 🗜️ Small: Tree-shakeable and around 1.4 kB on modern platforms
• 🔎 URLs: Supports looking items up from their store URLs
• 🧪 Reliable: Fully tested with 100% code coverage
• 📦 Typed: Written in TypeScript and includes definitions out-of-the-box
• 💨 Zero dependencies

Introduction

itunes-store-api is a typed iTunes Search API client which adds support for looking items up from their store URLs.

Installation

Skypack

import { search, lookup } from "https://cdn.skypack.dev/itunes-store-api"

Yarn

yarn add itunes-store-api

npm

npm install itunes-store-api

Usage

search

Import search.

import { search } from "itunes-store-api"

Invoke it asynchronously and access results in return.

const { results } = await search("M83")

// results: [Result, Result, Result…]

lookup

Import lookup.

import { lookup } from "itunes-store-api"

Invoke it asynchronously using a lookup type ("id", "isbn", "upc", "url", "amgAlbumId", "amgArtistId" or "amgVideoId") and access a result in return.

const { results } = await lookup("id", 1007596731)

// results: [Result]

"url"

A variety of store catalog URLs are supported when using the "url" lookup type.

| Entity | Example | | ----------- | --------------------------------------------------------------------------- | | Software | https://apps.apple.com/us/app/letterboxd/id1054271011 | | Audiobook | https://books.apple.com/gb/audiobook/the-diary-of-a-young-girl/id1440416363 | | Book | https://books.apple.com/us/book/the-communist-manifesto/id395544966 | | Author | https://books.apple.com/us/author/albert-camus/id57528162 | | Song | https://music.apple.com/us/album/kim-jessie/1007596648?i=1007596731 | | Album | https://music.apple.com/us/album/wolfgang-amadeus-phoenix/1450828963 | | Music Video | https://music.apple.com/us/music-video/daydreaming/1441607175 | | Artist | https://music.apple.com/us/artist/a-g-cook/744253464 | | Podcast | https://podcasts.apple.com/us/podcast/panic-podcast/id1495115716 |

Options

Both search and lookup support a trailing options argument.

country

A two-letter country code where the queried store catalog will be from. Defaults to "us".

await lookup("id", 1491051628, { country: "fr" })

limit

Limit the number of results. Defaults to 50.

await search("C418", { limit: 10 })

sort

Whether to sort results by popularity ("popular") or recentness ("recent"). Defaults to "popular".

await search("Twitter", { sort: "popular" })

media

The media type to search for—see Table 2-1. Defaults to "all".

await search("Lost in Translation", { media: "movie" })

entity

The type of results returned, relative to the specified media type—see Table 2-1.

const album = await lookup("id", 1007596648)
const songs = await lookup("id", 1007596648, { entity: "song" })

// album: { results: [ResultAlbum] }
// songs: { results: [ResultMusicTrack, ResultMusicTrack, ResultMusicTrack…] }

attribute

Which attribute to search for, relative to the specified media type—see Table 2-2.

await search("Greta Gerwig", { entity: "movieArtist", attribute: "actorTerm" })

explicit

Whether to include explicit content. Defaults to true.

await search("My Beautiful Dark Twisted Fantasy", { explicit: true })