google-play-scraper: Node.js app data from the Google Play store

What google-play-scraper does, and who actually needs it

Google Play has no public, documented API for reading app metadata, ratings, reviews or category rankings. The storefront is HTML and internal endpoints. google-play-scraper exists to sit between those pages and your code, returning plain JavaScript objects instead of markup. The README describes it as a "Node.js module to scrape application data from the Google Play store", and the package.json describes the job as "scrapes app data from google play store".

The audience is narrow but real. ASO analysts who track keyword rankings, indie developers comparing their own listing against competitors, data teams building a small app-metadata warehouse, and researchers who need review text for a study. The library also underpins two related projects by the same author: aso, an App Store Optimization module built on top of it, and google-play-api, a RESTful wrapper that exposes the scraped data over HTTP. If you want the data but not the Node.js dependency, google-play-api is the layer to look at first.

What it is not: a bulk crawler with a scheduler, a proxy rotator or a database. It is a set of functions that fetch and parse. Everything around them is your problem.

The method surface: app, list, search, reviews, permissions, datasafety

The README lists ten methods. app returns the full detail of one application. list returns apps from a Google Play collection, with optional category and age filters. search returns results for a term. developer returns the apps of a given developer. suggest returns up to five completions for a search prefix. reviews returns a page of reviews for one app. similar returns apps similar to a given one. permissions returns the permissions an app requests. datasafety returns the app's data safety information. categories returns the category list from Google Play's dropdown.

The app response is the one worth studying, because it shows how much parsing work the library absorbs. A single call returns title, description and descriptionHTML, summary, installs as a display string alongside minInstalls and maxInstalls as numbers, score and scoreText, ratings, reviews, a histogram keyed by star rating, price and currency, androidVersion, developer fields including email, website and address, genre and genreId, a categories array, icon, headerImage, screenshots, contentRating, updated as a timestamp, version, recentChanges, preregister, earlyAccessEnabled, isAvailableInPlayPass, editorsChoice, features, the resolved url, and appId. Fields that Google Play does not expose for a given app come back as undefined rather than being omitted.

That undefined behaviour is a design decision with consequences. It means your code cannot distinguish "this app has no video" from "the parser stopped finding the video field". Both look identical. If you build a pipeline on this library, treat undefined as a signal to re-check the raw page, not as a settled fact.

Install and first request with google-play-scraper npm

The README gives one installation command. The package is ESM: package.json sets "type": "module" and "exports": "./index.js", so the import form in the examples is the one that works in current versions.

npm install google-play-scraper

After that, a first real request is the app lookup. The README's example passes an appId, which is the ?id= parameter on a Play Store URL, and then logs the result or the error through the same callback.

import gplay from "google-play-scraper";

gplay.app({appId: 'com.google.android.apps.translate'})
  .then(console.log, console.log);

You should see an object shaped like the README's Google Translate sample: title, installs as a string such as '500,000,000+', minInstalls as 500000000, a score around 4.48, a histogram with keys '1' through '5', developer 'Google LLC', and a url ending in the appId with hl and gl query parameters appended.

The app method takes three options: appId, lang (defaults to 'en') and country (defaults to 'us'). The README notes that country is needed when the app is available only in some countries, which is the detail people miss first. A listing that returns nothing for a US request may return a full record for another country code.

For a ranked list, the list method defaults to collection.TOP_FREE and num 500. The README's example narrows it to a category and asks for two results.

import gplay from "google-play-scraper";

gplay.list({
    category: gplay.category.GAME_ACTION,
    collection: gplay.collection.TOP_FREE,
    num: 2
  })
  .then(console.log, console.log);

Each entry in the result carries url, appId, summary, developer, developerId, title and icon. Note fullDetail, which defaults to false: setting it to true makes an extra request per app to fetch the complete record. On a list of 500 that is 500 additional requests, so the option is a cost decision, not a convenience toggle.

Where google-play-scraper breaks, and when it is the wrong tool

The README carries a warning in its own words: "I don't use or actively maintain this project anymore, other than reviewing community provided PRs. Expect the parser to break when Google Play's layout changes." That is the single most important line in the repository. The last push to the default branch was on 2026-09-21, so code is still landing, but it lands through community pull requests rather than a maintainer working on the project day to day. The latest tagged release listed in the repository is v6.2.3 from 2019-02-04, while package.json declares version 10.1.3. Releases and the working tree have drifted apart, so "which version am I actually running" is a question you answer from package.json, not from the release list.

The failure mode follows from the mechanism. The library parses HTML with cheerio and fetches with got. When Google Play renames a CSS class, moves a value into a script tag, or changes an internal endpoint, a field silently becomes undefined or a call rejects. Nothing in the response tells you the page changed shape. The test suite runs under mocha with a five second timeout per test, which is a reasonable guard for the maintainers, but a green test run on their fixtures does not prove the live pages still match your target country and language.

The second constraint is scale. There is no built-in throttling, retry policy or proxy support in the dependencies listed in package.json. A loop over thousands of appIds will issue thousands of requests from one IP address. If you need large volumes, the library is the parsing layer and you still have to build the queue, the pacing and the identity management yourself.

It is also the wrong tool if you need official data with a service guarantee. There is no agreement, no SLA and no support channel beyond the issue tracker. If your product depends on Play Store metadata being correct at all times, a scraper is a liability, not infrastructure.

google-play-scraper vs app-store-scraper and the Python ports

The README points to app-store-scraper, a scraper with a similar interface for the iTunes app store. The difference is the target, not the design: same author, same method-shaped API, same parse-the-page approach, so the same fragility applies to Apple's markup instead of Google's. If you need both stores, the two libraries give you a consistent call surface, which is a genuine reason to pick this one over a store-specific alternative.

The other real alternative is a Python port of the same idea. Searches for google play scraper python and google_play_scraper pip are common, and Python implementations of Play Store scraping exist under similar names. The trade-off is ecosystem, not capability: if your data pipeline is pandas and notebooks, a Python package avoids a Node.js runtime in the middle of it. If your service is already Node.js, adding a Python sidecar to scrape app metadata is more moving parts than importing this module. Neither approach removes the underlying problem, which is that both parse pages Google Play can change without notice.

Maintenance cost, licence and what to check before you ship

The licence is MIT, declared in package.json and shipped as a LICENSE file at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept. That is the whole of the licence implication here; whether your specific use of scraped Play Store data is acceptable is a separate question the licence does not answer, and the README does not address it either.

The upgrade cost is the part teams underestimate. Because there is no active maintainer, a break in Google Play's layout is fixed when someone in the community writes a patch and it is reviewed. Your options at that point are to wait, to pin an older version and accept the broken field, or to fork and fix the parser yourself. Budget for the third option. The parsing code lives under lib/, and the repository root also carries index.js and index.d.ts, so TypeScript consumers get types from the package rather than from DefinitelyTyped.

Before you ship, verify the fields you actually store. The README's own sample output shows developerLegalName, developerLegalEmail, developerLegalAddress, developerLegalPhoneNumber, video, videoImage, previewVideo, contentRatingDescription and released all as undefined for a major app. If your schema treats those as required, it will be wrong on day one. Run the app method against your target apps in your target lang and country, and confirm the values you need arrive populated.

Editorial conclusion

Use google-play-scraper if you need a quick, MIT-licensed way to pull Google Play app records, reviews or search results into a Node.js or TypeScript pipeline, and you are prepared to patch the parser yourself when Google Play's layout shifts. Do not adopt it as the backbone of a commercial product that needs a support contract or guaranteed uptime: the README states the author does not use or actively maintain the project beyond reviewing community PRs. Before committing, run gplay.app against three or four app IDs in the countries and languages you care about, and check that every field you plan to store is populated rather than undefined.

Frequently asked questions

Official sources

1. facundoolano/google-play-scraper on GitHub
2. Issues
3. License: MIT
4. README
5. Releases