google-play-scraper-ts

Fully typed Node.js client for Google Play Store metadata inspired by google-play-scraper. The rewrite keeps the familiar API while adding:

• ✅ TypeScript-first types and emitted declaration files
• ✅ Fixtures & offline tests (no live traffic unless LIVE=1)
• ✅ Retries + memoization out of the box
• ✅ Dual CJS/ESM builds with verified parity

Installation

npm install google-play-scraper-ts

Requires Node.js 18 or newer.

Quick start

CommonJS:

const gplay = require('google-play-scraper-ts').default;

const app = await gplay.app({ appId: 'com.spotify.music' });
console.log(app.title, app.score);

ESM / TypeScript:

import gplay, { constants } from 'google-play-scraper-ts';

const topFreeMusic = await gplay.list({
  collection: constants.collection.TOP_FREE,
  category: constants.category.MUSIC_AND_AUDIO,
  num: 10,
});

Common conventions

• lang controls the Play Store UI language (default 'en').
• country controls geotargeting and pricing (default 'us').
• Methods that accept requestOptions forward requestOptions.headers to the underlying HTTP client so you can inject cookies or additional headers (see per-method notes—suggest currently ignores the option for API parity).
• Every function returns a Promise; runtime errors (invalid inputs, store shape changes, HTTP failures) surface as rejected promises.

Proxy routing

• The HTTP client can route calls through HTTP(S) proxies keyed by country (ISO alpha-2, case-insensitive). If no per-country match is found, the optional default proxy is used instead of a direct connection.
• Configure proxies once via configureProxies(settings) or construct an isolated client with createPlayStoreApi({ proxies }). All methods automatically opt into proxy usage—the country argument (or gl query param) determines the lookup.
• HTTPS proxies are supported; pass protocol: 'https' or use an https:// URL. To work with debugging gateways that present expired/self-signed certificates, set rejectUnauthorized: false (defaults to true).

import { createPlayStoreApi } from 'google-play-scraper-ts';

const gplay = createPlayStoreApi({
  proxies: {
    default: { host: 'proxy.example', port: 8080 },
    perCountry: {
      us: { host: 'us-proxy.internal', port: 8080, auth: { username: 'user', password: 'secret' } },
      fr: { url: 'http://fr-proxy.internal:8080' },
      br: { url: 'https://br-proxy.internal:10443', rejectUnauthorized: false },
    },
  },
});

const result = await gplay.app({ appId: 'com.spotify.music', country: 'us' });

Already instantiated clients can be updated in-place with configureProxies(newSettings); pass null or omit entries to clear previously configured proxies.

API reference

All methods are asynchronous and resolve to typed results. The library mirrors the original google-play-scraper surface while enriching the responses with strict TypeScript types.

Shared types

AppDetails

Identification & copy

Ratings & installs

Pricing & monetisation

Media & merchandising

Developer & policies

Platform & release information

AppSummary

Returned by list, search, developer and similar methods when fullDetail is false.

Review

PermissionItem

DataSafetyItem

app(options): Promise<AppDetails>

Fetch detailed information about a single application.

Resolves to an AppDetails object as documented above.

list(options): Promise<AppSummary[] \| AppDetails[]>

Retrieve curated charts (Top Free, Top Paid, Grossing, …). Set fullDetail to fetch the richer AppDetails payload for each entry.

Returns an array of AppSummary entries, or AppDetails entries when fullDetail is enabled.

search(options): Promise<AppSummary[] \| AppDetails[]>

Search the Play Store catalogue.

Results mirror the modern /store/search layout (including single-result pages). When fullDetail is enabled each result is re-fetched via app().

Need the legacy “global” feed? Use searchGlobal(options) to call the former /work/search endpoint. Its options match search(), but expect geo-neutral results unless you route traffic through a country proxy.

searchGlobal(options): Promise<AppSummary[] \| AppDetails[]>

Back-compat wrapper around the legacy /work/search flow. Accepts the same options as search() and returns identical payload shapes. Pagination still uses the shared batchexecute endpoint, but the initial page reflects Google’s global results regardless of the country parameter.

suggest(options): Promise<string[]>

Fetch autocomplete suggestions from Play.

Resolves to an array of suggestion strings ordered by relevance.

developer(options): Promise<AppSummary[] \| AppDetails[]>

List applications published by a developer profile.

Returns developer listings as AppSummary entries, or full details when fullDetail is enabled.

reviews(options): Promise<{ data: Review[]; nextPaginationToken: string \| null }>

Pull paginated user reviews for a given app.

When paginate is true, the method fetches a single page and returns the next token (if any). The data array contains Review entries.

similar(options): Promise<AppSummary[] \| AppDetails[]>

Retrieve apps from the “Similar” / “Related” clusters for a given listing.

Returns up to ~60 related apps as AppSummary or AppDetails entries.

permissions(options): Promise<string[] \| PermissionItem[]>

Inspect runtime permissions declared in the Play listing.

datasafety(options): Promise<{ sharedData: DataSafetyItem[]; collectedData: DataSafetyItem[]; securityPractices: Array<{ practice?: string; description?: string }>; privacyPolicyUrl?: string }>

Fetch the Google Play “Data safety” disclosure for an app.

The result contains separate sharedData and collectedData arrays of DataSafetyItems, a list of high-level securityPractices, and an optional privacyPolicyUrl.

categories(): Promise<string[]>

Scrape the public category directory and return category identifiers (e.g. 'APPLICATION', 'GAME_TRIVIA').

memoized(options?: { maxAge?: number; max?: number }): PlayStoreApi

Wrap the API with an in-memory cache.

The returned object has the same surface as the default export (including a memoized method) but memoises every call.

Constants helper

The default export re-exports structured enums under constants for convenience:

• constants.collection – TOP_FREE, TOP_PAID, GROSSING.
• constants.category – All Play categories (apps, games, family variants, etc.).
• constants.sort – Review sort orders (NEWEST, RATING, HELPFULNESS).
• constants.age – Age-range filters used by the family charts.
• constants.permission – Permission buckets (COMMON, OTHER).
• constants.clusters – Internal cluster identifiers used by list parsing utilities.

Releases

• Preflight checks before releasing:
  • npm run release:preflight (lint, tests, type verification)
• Publish (requires npm login and 2FA):
  • Patch: npm run release:patch
  • Minor: npm run release:minor
  • Major: npm run release:major
• Notes
  • prepack builds automatically before pack/publish.
  • For scoped packages (e.g. @your-scope/google-play-scraper-ts), publish with --access public (already included in release scripts).
  • To validate after publish: install in a clean folder and require/import both CJS/ESM entries.

Debugging & Fixtures

• Verbose debugging for similar() resolution:
  • Set GP_DEBUG=1 to print minimal breadcrumbs when the service-request cluster id is missing (e.g., container keys available).
• UI tests (manual exploration):
  • Build the library: npm run build
  • Start the UI server: LIVE=1 node ui-tests/server.js
  • Open the playground and use the forms to call each method.
• Record live fixtures for similar() (optional):
  • LIVE=1 npm run build && node scripts/record-similar-fixture.js --appId com.spotify.music --lang en --country us --out tests/fixtures/similar
  • Re-run tests with fixture replay: USE_FIXTURE=1 npm test
• constants.sort – Review sort order values
• constants.age, constants.permission, plus other helpers

Retries & throttling

• Retries – The internal HTTP client retries 5xx responses with exponential backoff (configurable via helper APIs).
• Caching – Use memoized() to deduplicate hot requests. For full control, combine with your own throttling or caching layer.

TypeScript support

• Published package includes type declarations generated from the TypeScript sources.
• npm run verify:types compiles tests/types/usage.ts against the generated .d.ts to guarantee correctness.

Running the docs & tests

npm run lint
LIVE=1 npm test    # only needed when you want to exercise live tests (default suite uses fixtures)
npm run test        # builds both ESM and CJS bundles before running mocha
npm run docs        # generates TypeDoc output in /docs
npm run verify:types

By default the test suite blocks outbound HTTP requests. Set LIVE=1 to allow network calls when you want to run ad-hoc live checks.

Manual UI testing playground

Looking for the interactive UI harness? It now lives in a standalone repository with prebuilt assets and GitHub Pages hosting:

• GitHub repo: google-play-scraper-ts-ui-tests
• Hosted playground: https://guiguito.github.io/google-play-scraper-ts-ui-tests/

The hosted version always targets the latest npm release of this package. It includes the search-mode toggle (modern /store/search vs. legacy /work/search) and the enhanced proxy configuration panel (per-country entries, auth, TLS validation overrides), plus a direct Play Store link for each query so you can inspect the underlying page.

Contributing

Issues and pull requests are welcome! Please review AGENTS.md for repository conventions (linting, commit style, release workflow).