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
npm install itunes-store-apiUsage
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.
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 })