Your first AppstoreSpy API call

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

1. Get an API key

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.

2. Send the key in the API-KEY header

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>'

3. Look up one app

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"

4. Ask only for the fields you need

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"

5. Page through a list

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}

6. Read the credit headers

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-Cost
Credits this request cost
X-Remaining-Credits
Your balance after this request
X-Receipt
Receipt id for this request; quote it to support about a charge

7. Handle errors

Errors are JSON. The status code tells you what to do next.

400
The request was understood but not allowed, such as an unknown name in fields or limit times page above 10,000. Fix the request. It costs nothing, except on the job endpoints named in step 6
401
The API-KEY header is missing or the key is wrong. Check the header name and the key on your account page
402
Your credit balance is used up (wait for the plan's refill or upgrade), or your paid subscription is not active (renew it on the pricing page)
403
This operation is not included in your plan. See the pricing page
404
No such app or developer, or no such path. Check the id and the path against the reference
422
A parameter has the wrong type or value. The body names the parameter and the problem. It costs nothing, except on the job endpoints named in step 6
429
Too many requests for this key on a rate-limited operation, such as the live listing at GET /play/apps/{id}/listing or the daily installs at GET /play/apps/{id}/installs_daily. Back off and retry later; it costs nothing, except on the job endpoints named in step 6

Next

Updated 2026-10-06