google-play/
app-rankings

Собирайте публичные рейтинги категорий Google Play по известным URL чартов в виде нормализованных записей приложений с позицией, идентификатором, метаданными магазина, медиафайлами и контекстом сбора.

Google Play App Rankings API

URL категории на входе
Нормализованные записи приложений
Оплата по результатам
0,15 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

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, следите за асинхронной задачей и после успешного завершения читайте нормализованные записи рейтинга.

  1. Выберите публичные URL категорий или рейтингов на play.google.com, в которых контекст чарта уже задает нужный рынок и раздел для сбора.
  2. Отправьте urls и необязательный results_limit методом POST на /v1/google-play/app-rankings и сохраните возвращенный task_id.
  3. Опрашивайте /v1/tasks/{task_id}, пока status не станет succeeded или failed; пока задача в очереди или выполняется, результаты недоступны.
  4. Читайте 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 кредита за каждый, а неиспользованные кредиты оценки возвращаются.

Помимо 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 с необязательным указанием страны: нормализованные поля текста, автора, оценки, времени и ссылки на приложение.

Другие платформы

Объединяйте данные Google Play с публичными данными других поддерживаемых соцсетей.

Google Play App Rankings API — FAQ

Google Play App Rankings API — это программный интерфейс, который собирает данные по публичным URL рейтингов категорий Google Play в нормализованные записи AppItem с доступными позицией, идентификатором приложения, метаданными магазина, медиафайлами, источником и временем сбора.

Отправьте непустой массив публичных URL рейтингов на play.google.com. Поддомены принимаются, но каждый путь должен содержать /store/apps/collection/ или /store/apps/category/; страницы приложений и посторонние пути отклоняются.

Нет. Запрос принимает только urls и необязательный results_limit, поэтому контекст рынка, подборки или категории должен уже содержаться в отправленном URL Google Play.

results_limit принимает значения от 1 до 2 000, по умолчанию 100. Он ограничивает выборку и число сохраненных результатов для всей задачи и задает начальную оценку числа результатов для предоплаты. Несколько URL обрабатываются по порядку в пределах оставшейся квоты задачи.

Нет. Провайдер завершает сбор датасета до того, как SocQ показывает результаты; next_cursor лишь продолжает чтение нормализованных записей, уже сохраненных для успешно завершенной задачи.

Результат AppItem содержит фиксированные поля ID, platform, resource, type, URL, метки времени, app_id, name, text, developer, category, rating, reviews_count, installs, price, rank и media. Необязательные значения источника остаются null, если недоступны.

Тариф — 0,15 кредита SocQ за каждый сохраненный результат при нулевой базовой ставке. SocQ делает предоплату по results_limit или по оценке по умолчанию в 100 результатов, рассчитывается по фактическому числу результатов и возвращает неиспользованную часть оценки; пустой результат стоит ноль.