# iTunes on Onekey

> 23 endpoints for iTunes (22 stable, 1 beta), 1 to 5 credits each. Category: Music & audio. One key, one JSON shape.

Base URL: https://api.onekey.dev
Auth: header `x-api-key: <key>`. Call shape: `GET /v1/{platform}/{endpoint}?{params}`.
Every response is `{success, data, metadata, error}`; check `success` first. Cost is in `metadata.credits_charged`. Free when served from cache (0.2 credit for a cached response over 100 KB). Failed and not-found calls are refunded.
Status: stable = verified against the live source; beta = not yet verified, fields may be missing.

Page: https://onekey.dev/platforms/itunes
Reference (Markdown): https://onekey.dev/docs/api/itunes.md
All docs: https://onekey.dev/llms.txt

## Canonical fields returned

Unified-schema fields (same names on every platform), with how many of the 23 mapped iTunes endpoints return each:

- `author.displayName` (string): 23
- `media.thumbnailUrl` (URL): 20
- `content.createdAt` (ISO 8601 date): 11
- `content.id` (string): 11
- `content.title` (string): 11
- `content.url` (URL): 11
- `content.category` (string): 10
- `entity.id` (string): 10
- `entity.name` (string): 10
- `entity.url` (URL): 10
- `entity.category` (string): 9
- `entity.releaseDate` (ISO 8601 date): 4
- `entity.stats.itemCount` (integer): 4
- `media.previewUrl` (URL): 4
- `author.id` (string): 3
- `entity.description` (string): 3
- `entity.stats.rating` (number): 3
- `listing.price` (number): 3
- `author.url` (URL): 2
- `content.text` (string): 2
- `entity.stats.ratingCount` (integer): 2
- `package.version` (string): 2
- plus 6 platform-specific fields under `ext.`

## Endpoints

### itunes.lookup_album

iTunes album by collection id.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_album?id=1097861387` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.stats.itemCount`, `entity.category`, `entity.releaseDate`
- Reference: https://onekey.dev/docs/api/itunes/lookup_album.md

### itunes.lookup_album_tracks

Tracks of an iTunes album (first row is the album itself).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_album_tracks?id=1097861387` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.category`, `content.url`, `media.thumbnailUrl`, `media.previewUrl`, `content.createdAt`, `ext.album`, `ext.durationMs`
- Reference: https://onekey.dev/docs/api/itunes/lookup_album_tracks.md

### itunes.lookup_app

App Store app by id.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_app?id=310633997` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.description`, `package.version`, `entity.url`, `media.thumbnailUrl`, `entity.category`, `listing.price`, `entity.stats.rating`, `entity.stats.ratingCount`
- Reference: https://onekey.dev/docs/api/itunes/lookup_app.md

### itunes.lookup_artist

iTunes/Apple Music artist by id.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_artist?id=909253` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `author.id`, `author.displayName`, `author.url`, `ext.genre`
- Reference: https://onekey.dev/docs/api/itunes/lookup_artist.md

### itunes.lookup_artist_albums

Albums of an iTunes artist (first row is the artist itself).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_artist_albums?id=909253` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.stats.itemCount`, `entity.category`, `entity.releaseDate`, `author.id`
- Reference: https://onekey.dev/docs/api/itunes/lookup_artist_albums.md

### itunes.lookup_podcast

Apple Podcasts show by id.
- Price: 1 credit per fresh call. Status: stable. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_podcast?id=1200361736` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.category`, `ext.feedUrl`, `ext.episodeCount`
- Reference: https://onekey.dev/docs/api/itunes/lookup_podcast.md

### itunes.lookup_podcast_episodes

Recent episodes of an Apple Podcasts show (first row is the show).
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/lookup_podcast_episodes?id=1200361736` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `id` (string, required): iTunes/Apple id
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `content.id`, `content.title`, `content.text`, `content.url`, `media.previewUrl`, `content.createdAt`, `author.displayName`, `ext.durationMs`
- Reference: https://onekey.dev/docs/api/itunes/lookup_podcast_episodes.md

### itunes.search_albums

Search iTunes albums.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_albums?q=radiohead` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.stats.itemCount`, `entity.category`, `entity.releaseDate`
- Reference: https://onekey.dev/docs/api/itunes/search_albums.md

### itunes.search_apps

Search App Store iOS apps.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_apps?q=whatsapp` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.description`, `package.version`, `entity.url`, `media.thumbnailUrl`, `entity.category`, `listing.price`, `entity.stats.rating`, `entity.stats.ratingCount`
- Reference: https://onekey.dev/docs/api/itunes/search_apps.md

### itunes.search_artists

Search iTunes music artists.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_artists?q=radiohead` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `author.id`, `author.displayName`, `author.url`, `ext.genre`
- Reference: https://onekey.dev/docs/api/itunes/search_artists.md

### itunes.search_audiobooks

Search Apple audiobooks.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_audiobooks?q=dune` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.category`, `ext.feedUrl`, `ext.episodeCount`
- Reference: https://onekey.dev/docs/api/itunes/search_audiobooks.md

### itunes.search_ebooks

Search Apple Books ebooks.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_ebooks?q=dune` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.description`, `entity.url`, `media.thumbnailUrl`, `entity.stats.rating`, `listing.price`
- Reference: https://onekey.dev/docs/api/itunes/search_ebooks.md

### itunes.search_movies

Search iTunes movies.
- Price: 5 credits per fresh call. Status: beta. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_movies?q=inception` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.text`, `content.category`, `content.url`, `media.thumbnailUrl`, `content.createdAt`, `ext.rating`
- Reference: https://onekey.dev/docs/api/itunes/search_movies.md

### itunes.search_music

Search iTunes music tracks.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_music?q=radiohead` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.category`, `content.url`, `media.thumbnailUrl`, `media.previewUrl`, `content.createdAt`, `ext.album`, `ext.durationMs`
- Reference: https://onekey.dev/docs/api/itunes/search_music.md

### itunes.search_music_videos

Search iTunes music videos.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_music_videos?q=radiohead` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.category`, `content.url`, `media.thumbnailUrl`, `media.previewUrl`, `content.createdAt`, `ext.album`, `ext.durationMs`
- Reference: https://onekey.dev/docs/api/itunes/search_music_videos.md

### itunes.search_podcasts

Search Apple Podcasts shows.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_podcasts?q=history` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.category`, `ext.feedUrl`, `ext.episodeCount`
- Reference: https://onekey.dev/docs/api/itunes/search_podcasts.md

### itunes.search_tv_seasons

Search iTunes TV seasons.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/search_tv_seasons?q=breaking%20bad` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search term
  - `country` (string, optional, default us): 2-letter store country, e.g. us
- Fields returned: `entity.id`, `entity.name`, `author.displayName`, `entity.url`, `media.thumbnailUrl`, `entity.stats.itemCount`, `entity.category`, `entity.releaseDate`
- Reference: https://onekey.dev/docs/api/itunes/search_tv_seasons.md

### itunes.top_albums

Apple Music most-played albums chart.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/top_albums` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `country` (string, optional, default us): 2-letter store country, e.g. us
  - `limit` (string, optional, default 10): Chart size (10, 25, 50, 100)
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.url`, `media.thumbnailUrl`, `content.category`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/itunes/top_albums.md

### itunes.top_free_apps

App Store top free apps chart.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/top_free_apps` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `country` (string, optional, default us): 2-letter store country, e.g. us
  - `limit` (string, optional, default 10): Chart size (10, 25, 50, 100)
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.url`, `media.thumbnailUrl`, `content.category`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/itunes/top_free_apps.md

### itunes.top_free_books

Apple Books top free books chart.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/top_free_books` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `country` (string, optional, default us): 2-letter store country, e.g. us
  - `limit` (string, optional, default 10): Chart size (10, 25, 50, 100)
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.url`, `media.thumbnailUrl`, `content.category`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/itunes/top_free_books.md

### itunes.top_paid_apps

App Store top paid apps chart.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/top_paid_apps` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `country` (string, optional, default us): 2-letter store country, e.g. us
  - `limit` (string, optional, default 10): Chart size (10, 25, 50, 100)
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.url`, `media.thumbnailUrl`, `content.category`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/itunes/top_paid_apps.md

### itunes.top_podcasts

Apple Podcasts top shows chart.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/top_podcasts` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `country` (string, optional, default us): 2-letter store country, e.g. us
  - `limit` (string, optional, default 10): Chart size (10, 25, 50, 100)
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.url`, `media.thumbnailUrl`, `content.category`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/itunes/top_podcasts.md

### itunes.top_songs

Apple Music most-played songs chart.
- Price: 5 credits per fresh call. Status: stable. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/itunes/top_songs` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `country` (string, optional, default us): 2-letter store country, e.g. us
  - `limit` (string, optional, default 10): Chart size (10, 25, 50, 100)
- Fields returned: `content.id`, `content.title`, `author.displayName`, `content.url`, `media.thumbnailUrl`, `content.category`, `content.createdAt`
- Reference: https://onekey.dev/docs/api/itunes/top_songs.md

## Sample request

```bash
curl "https://api.onekey.dev/v1/itunes/lookup_album?id=1097861387" \
  -H "x-api-key: YOUR_API_KEY"
```