Google Play App Rankings
URL чарта Google Play определяет категорию или рейтинг для сбора, а results_limit задает глубину выборки — от 1 до 2 000 записей. Каждый сохраненный результат соответствует спецификации AppItem, поэтому позицию можно анализировать вместе с доступными идентификатором пакета, разработчиком, категорией, оценкой, числом отзывов, установками, ценой, медиафайлами, исходным URL и временем сбора.
Возможности Google Play App Rankings API
- Пакеты URL чартовОтправляйте непустой массив urls с публичными страницами категорий или рейтингов на play.google.com вместо отдельных полей страны или категории.
- Проверка URL рейтингов Google PlayСреда выполнения принимает play.google.com и его поддомены, только если путь содержит /store/apps/collection/ или /store/apps/category/.
- Ограниченный сбор рейтинговИспользуйте results_limit от 1 до 2 000. Если его не указать, применяется 100 — это же значение используется для оценки стоимости и по умолчанию при выборке у провайдера.
- Нормализованные позиции приложенийПолучайте rank вместе с доступными app_id, name, developer, category, rating, reviews_count, installs, price, media и публичными метаданными источника в единой структуре AppItem.
- Асинхронная работа с датасетомОтправленные строки URL запускают асинхронный датасет у провайдера; SocQ сохраняет нормализованные записи и возвращает состояние задачи через общий механизм чтения задач.
- Курсор по сохраненным результатамПосле успешного завершения листайте записи SocQ с помощью непрозрачного next_cursor из механизма чтения задач и limit от 1 до 500. Этот курсор не является токеном страницы Google Play или провайдера.
- Расчет по фактическим результатамSocQ заранее списывает оценку по запрошенному числу результатов или значению по умолчанию, затем берет 0,15 кредита за каждый сохраненный результат и возвращает неиспользованные кредиты оценки; пустой результат стоит по нулевой базовой ставке.
Параметры Google Play App Rankings API
| Параметры | Обязательный | Описание |
|---|---|---|
urls | Обязательный | Обязательный непустой массив публичных URL рейтингов Google Play. Каждый URL должен относиться к play.google.com или его поддомену и содержать в пути /store/apps/collection/ или /store/apps/category/; страна и категория как отдельные поля не принимаются. |
results_limit | Необязательный | Необязательное положительное целое число от 1 до 2 000. По умолчанию 100; ограничивает выборку и число сохраненных записей для всей задачи и задает начальную оценку стоимости. Входные URL обрабатываются по порядку в пределах оставшейся квоты задачи. |
Как использовать Google Play App Rankings API
Отправьте один или несколько известных URL чартов Google Play, следите за асинхронной задачей и после успешного завершения читайте нормализованные записи рейтинга.
- Выберите публичные URL категорий или рейтингов на play.google.com, в которых контекст чарта уже задает нужный рынок и раздел для сбора.
- Отправьте urls и необязательный results_limit методом POST на /v1/google-play/app-rankings и сохраните возвращенный task_id.
- Опрашивайте /v1/tasks/{task_id}, пока status не станет succeeded или failed; пока задача в очереди или выполняется, результаты недоступны.
- Читайте data.results.items и продолжайте с next_cursor, только когда has_more равно true.
curl -X POST "https://api.socq.ai/v1/google-play/app-rankings" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://play.google.com/store/apps/collection/topselling_free"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?cursor={next_cursor}&limit=50Сценарии использования Google Play App Rankings API
- Снимки чартов категорий: Храните rank и collected_at вместе, чтобы сравнивать отдельно собранные снимки известного чарта Google Play.
- Поиск приложений из рейтингов: Превращайте отобранный набор URL категорий в нормализованные записи приложений для проверки, разметки или последующего обогащения каталога.
- Проверка позиций портфеля: Сопоставляйте доступные поля app_id и developer с внутренним портфелем и изучайте каждую возвращенную позицию, не полагаясь только на совпадение отображаемых названий.
- Анализ магазина между запусками: Загружайте фиксированные поля AppItem в хранилище данных, чтобы допускающие null оценки, число отзывов, установки, цены и позиции оставались сопоставимыми между сборами.
Практические советы по Google Play App Rankings API
- Используйте публичный URL категории или чарта Google Play, а не страницу приложения, поисковую фразу, код страны или название категории; в этом запросе есть только urls и results_limit.
- Используйте URL play.google.com, путь которого содержит /store/apps/collection/ или /store/apps/category/; страницы приложений и посторонние пути не проходят проверку еще до начала сбора.
- При нескольких входных URL results_limit общий для всей задачи. URL обрабатываются по порядку, и каждый получает только оставшуюся квоту, поэтому разбивайте работу на отдельные задачи, если каждому чарту нужна собственная квота.
- Считайте метаданные приложений допускающими null. Сохраняйте app_id, url, rank и collected_at, если они есть, и не рассчитывайте, что оценки, число отзывов, установки, цена или медиафайлы всегда будут заполнены.
- Не передавайте курсор источника. Дождитесь успешного завершения и затем используйте только непрозрачный next_cursor из data.results, чтобы листать сохраненные записи SocQ.
- Планируйте бюджет по results_limit на момент отправки. Итоговые кредиты считаются по фактическому числу сохраненных результатов — по 0,15 кредита за каждый, а неиспользованные кредиты оценки возвращаются.
Связанные API
Помимо Google Play App Rankings API, используйте эти API, когда нужен другой тип публичных данных Google Play.
- Google Play App Detail API — Получайте нормализованные публичные данные карточки Google Play по известным URL приложений: название, описание в магазине, разработчик, категория, видимые метрики, цена, медиа и контекст сбора.
- Google Play App Reviews API — Собирайте публичные отзывы о приложениях по URL play.google.com с необязательным указанием страны: нормализованные поля текста, автора, оценки, времени и ссылки на приложение.