Get a key, send it in the API-KEY header, and look up one app. The steps below take about five minutes and use only curl. Every example is a real operation in the published OpenAPI document.
Base URL https://api.appstorespy.com/v1 · reference https://api.appstorespy.com/docs
Sign up at https://appstorespy.com/sign_up, then copy your key from https://appstorespy.com/account. Plans and credit allowances are listed at https://appstorespy.com/pricing.
Every request under https://api.appstorespy.com/v1 needs the header. Export the key once so the examples below can be pasted as they are.
export APPSTORESPY_KEY='<your key>'Fetch a Google Play app by its package name. The response is a single JSON object.
GET /play/apps/{id} with id, country
curl -s 'https://api.appstorespy.com/v1/play/apps/com.twitter.android?country=US' -H "API-KEY: $APPSTORESPY_KEY"fields takes a comma-separated list of response fields. An unknown field is rejected with 400 and names the field, so a typo never passes silently. Leave fields out to get every field. Each operation's response fields are listed in the reference.
GET /play/apps/{id} with id, country, fields
curl -s 'https://api.appstorespy.com/v1/play/apps/com.twitter.android?country=US&fields=name,developer_name,rating_value,installs' -H "API-KEY: $APPSTORESPY_KEY"List operations take limit (rows per page, 10 by default, at most 1000 in a query string) and page (starting at 1). limit times page may not exceed 10,000; past that the API answers 400. Rankings and the POST .../query search operations wrap rows in an envelope, {"data": [...], "total_count": N}, where total_count is the total across all pages, not just this page. The GET search operations GET /play/apps and GET /play/developers take the same limit and page but return a bare array.
GET /play/rankings with country, collection, limit, page
curl -s 'https://api.appstorespy.com/v1/play/rankings?country=US&collection=topselling_free&limit=50&page=2' -H "API-KEY: $APPSTORESPY_KEY"Response
{"data": [{"date": "...", "app": "...", "country": "US", "category": "...", "collection": "topselling_free", "rank": 51}, ...], "total_count": 12345}Each billed response carries three headers. Add -i to any curl above to see them. A 400 (an invalid parameter), a 422 (a parameter with the wrong type or value), a 429 (rate limit) and any 5xx server error cost nothing, except on job endpoints (GET /play/apps/{id}/recrawl, GET /ios/apps/{id}/recrawl, GET /play/liveops and GET /play/suggestions), which are still billed; see https://github.com/romamo/as-rest/issues/99. Other errors are billed, 404 included, so check ids first. The listing endpoint has its own read and crawl prices; see its description.
X-CostX-Remaining-CreditsX-ReceiptErrors are JSON. The status code tells you what to do next.
400fields or limit times page above 10,000. Fix the request. It costs nothing, except on the job endpoints named in step 6401402403404422429Updated 2026-10-06