Google Play Scraper Service

A stateless Python microservice that fetches app data from the Google Play Store.

Tech Stack

Component	Technology
Framework	FastAPI
Language	Python
Scraper	gplay-scraper
Server	uvicorn
Validation	Pydantic

Endpoints

Method	Route	Description
GET	/health	Health check
GET	/charts	Chart rankings
GET	/apps/search	Search apps by term
GET	/apps/{app_id}/identity	App identity and metadata
GET	/apps/{app_id}/listings	Store listing for one locale
GET	/apps/{app_id}/listings/locales	Listings for multiple locales
GET	/apps/{app_id}/metrics	Rating and metrics
GET	/developers/{developer_id}/apps	Developer’s app catalog
GET	/developers/search	Search developers

Key Parameters

Charts

• collection: chart type (default: top_free)
• category: Google Play category (default: APPLICATION)
• country: ISO country code (default: us)
• count: result count (default: 100, max: 200)

Search

• term (required): search query (min 1 character)
• limit: maximum results (default: 10, max: 50)
• country: ISO country code (default: us)

App Data

• country: ISO country code (default: us)
• locale: locale code (default: en)

Error Semantics

The scraper propagates store errors with matching HTTP status codes:

• 404 Not Found — the app is not available on the target store/country. AppNotFoundError is turned into a consistent 404 response by a FastAPI exception handler. The server side interprets this as “permanently not available on this storefront”.
• 5xx — unexpected errors; retried on the server side.

Silent print/warning errors are emitted as structured JSON logs.

Key Differences from the App Store Scraper

Feature	App Store	Google Play
Chart depth	Up to 200	Up to 100
Subtitle	Supported	Not available
Install count	Not available	Available (range)
Locale parameter	lang	locale
Default category	None	APPLICATION
Metric country_code	Actual ISO code	zz sentinel (global)

Note: Because Android metrics are aggregated across the store, the server side stores them as “Global” with the ISO 3166 user-assigned zz code. That code is seeded into the countries table but is filtered out of the public /countries list.

Running

make dev-android      # Start the service
make logs-android     # View logs

API Documentation

While the service is running, OpenAPI documentation is available at /docs (auto-generated by FastAPI).

Design Principles

• Stateless: no database, no cache, no persistent state
• Pydantic models: all responses are validated through Pydantic schemas
• Error propagation: store errors are propagated with the correct HTTP status code (404 for missing apps)
• Port: configurable via the PORT environment variable (default: 7463)