/itunes-store-api

💿 Query Apple store catalogs using the iTunes Search API.

Primary LanguageTypeScriptMIT LicenseMIT

itunes-store-api

💿 Query Apple store catalogs using the iTunes Search API.

build npm size coverage license

  • 🗜️ 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 search("Le Fabuleux Destin d'Amélie Poulain", { country: "fr" })

limit

Only available for search.

Limit the number of results. Defaults to 50.

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

sort

Only available for search.

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

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

media

Only available for search.

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

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

entity

Only available for search.

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

await search("Things", { media: "software", entity: "macSoftware" })

attribute

Only available for search.

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

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

explicit

Only available for search.

Whether to include explicit content. Defaults to true.

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