Apple неособо афиширует, что у iTunes Store идругих каталогов есть кривенькое, нопростое поисковое API поэтому ярешил онём написать. Изэтой заметки выузнаете, что API умеет икак его использовать.
Поиск в каталогах Apple
API ищет посодержимому iTunes Store, iBooks Store, Apple Podcasts и App Store. Соответственно, можно найти песни, фильмы, книги, подкасты и приложения.
API работает подавно забытому принципу JSONP, тоесть возвращает Content-Type:
text/javascript
вместо нормального
application/json
.
GET /search?media=podcast&term=python HTTP/1.1Host: itunes.apple.comAccept: application/jsonHTTP/2 200content-type: text/javascript; charset=utf-8{...}
Конечно, эту особенность можно просто игнорировать:
import requestsdef search(term, media): url = "https://itunes.apple.com/search" payload = {"term": term, "media": media} response = requests.get(url, params=payload) response.raise_for_status() results = response.json().get("results", []) return results
>>> results = search("python", media="podcast")>>> results[0]["collectionName"]'Talk Python To Me'
Параметры запроса
Поиск можно настроить:
term
поисковый запрос, единственный обязательный параметр;media
тип произведения (movie
,podcast
,music
,audiobook
,software
,ebook
,all
), поумолчаниюall
;country
страна произведения, двухсимвольный ISO-код (us
,ru
, ...), по умолчаниюus
;limit
максимальное количество результатов, по умолчанию50
.
Пример функции, которая поддерживает все параметры:
import requestsdef search(term, media="all", country="us", limit=10): url = "https://itunes.apple.com/search" payload = {"term": term, "media": media, "country": country, "limit": limit} response = requests.get(url, params=payload) response.raise_for_status() results = response.json().get("results", []) return results
Ответ
Общая структура ответа:
{ "resultCount": 10, "results": [ { "wrapperType": "track", "kind": "song", "artistId": 1495668306, "collectionId": 527039271, "trackId": 527039276, "artistName": "Dodge & Fuski", "collectionName": "Never Say Die (Deluxe Edition)", "trackName":"Python", ... }, { "wrapperType": "track", "kind": "podcast", "collectionId": 979020229, "trackId": 979020229, "artistName": "Michael Kennedy (@mkennedy)", "collectionName": "Talk Python To Me" ... }, ... ]}
Конкретный набор полей зависит оттипа произведения
(kind
) иполноценно нигде неописан, насколько мне
известно. Часто заполнены:
artistId
идентификатор автора произведения;artistName
автор;artistViewUrl
ссылка на автора на сайте Apple;collectionId
идентификатор альбома;collectionName
название альбома;collectionViewUrl
ссылка на альбом на сайте Apple;trackId
идентификатор композиции;trackName
название композиции;artworkUrl100
ссылка на превьюшку произведения 100x100 пикселей;country
страна произведения;primaryGenreName
жанр произведения.
Для подкастов ясделал типизированную обёртку пакет podsearch, можно посмотреть набор полей внём.
Запрос поидентификатору
Если известен идентификатор объекта (artistId
,
collectionId
, trackId
), можно вызвать
метод lookup
понему:
import requestsdef lookup(object_id): url = "https://itunes.apple.com/lookup" payload = {"id": object_id} response = requests.get(url, params=payload) response.raise_for_status() results = response.json().get("results", []) return results
>>> results = lookup(979020229)>>> results[0]["collectionName"]'Talk Python To Me'
Нюансы
Про необычный Content-Type ответа я уже упомянул. Кроме того:
- Страна произведения (
country
) есть как впараметрах запроса, так и вответе. Но впараметрах это двухсимвольный ISO-код (ru
), а вответетрёхсимвольный (RUS
). - Схемы ответа несуществует.
- Apple ограничивает частоту вызова API 20 запросами вминуту.
Описание API на сайте Apple
Пакет для поиска по подкастам
Если хотите больше интересных штук наPython подписывайтесь на канал @ohmypy