Complete access to this API is available via monthly subscription. Contact us for pricing and details or try out limited access for free.
No API key set. You won't be able to live test the API calls below.
Login or Get API key

AppEverything API Docs

Rankings - Apps that show up on ranking lists (ie. Overall, Top Grossing, etc)
Details - Basic data about each app (data on the app description page)
Reviews - User reviews associated with each app

Introduction

A few quick details about our REST API

SSL only
We require that all requests are done over SSL.
UTF-8 encoding
We use UTF-8 everywhere.
Method
GET for all read calls, PUT to submit a new app.
Version number
The current version of our API is v1.
Multi-records format
JSON dictionaries separated by newlines.
Date format
All dates in the API are strings in the following format: YYYY-MM-DD.
Error handling
Errors are returned using the following HTTP error codes:
  • 400 - Bad input parameter or malformed request. The error message should indicate what is specifically wrong.
  • 401 - Missing or bad API key (email datageeks@appmonsta.com if you need a new API key).
  • 403 - You're requesting something your subscription doesn't cover (email datageeks@appmonsta.com if you'd like to change your subscription).
  • 404 - The data isn't available yet. This may be because we're still collecting it.
  • 429 - You've exceeded the rate limit for the API you're trying to access. Wait until tomorrow, or contact datageeks@appmonsta.com.
  • 500 - Something went wrong on our end. Email us at datageeks@appmonsta.com with the details of your API request, and we'll troubleshoot it ASAP.
Bulk API requests return request id to validate request:
  • Request id is sent via 'X-Request-ID' HTTP Header. You may get the status of request using Request Status API.

Compression

Our REST API allows the use of compression on the request and the response, using the standards defined by the HTTP 1.1 specification. Some clients will automatically use compression but for some it has to be turned on manually.

Turning on compression can result in speed and size savings of up to 4X.

To use compression make sure your requests to our API include the following header Accept-Encoding: gzip. Our API will compress the response if this header is specified. For more information on how to add this header refer to code examples below.


Authentication

Requests to the REST API are protected with HTTP Basic authentication. You must provide your API key to each request made against our API. If you've an account then you can find your API key in account settings or displayed at the top of this page (you need to be logged in). Otherwise you can always get one here (if you lost your key you can just enter your email again and we will retrieve it for you).

Requests have to use HTTPS. Using HTTP will return 400 error response.


Rankings

Request all rankings by date and by country

https://api.appmonsta.com/v1/stores/<store>/rankings.json=<country_code>&date=<date>

Request Parameters:

  • store: android or itunes.
  • country_code: The two letter country code of any country you've subscribed to.
    ie. AR, AT, AU, BE, BG, BR, CA, CH, CN, CZ, DE, DK, ES, FI, FR, GB, GR, HK, HU, IE, IL, IN, IT, JP, KR, MX, NL, NO, NZ, PH, PL, PT, RO, RU, SE, SG, SK, TH, TR, UA, US, ZA.
  • date: In the following format: YYYY-MM-DD.

Response Fields:

  • app_id: The app id of the app.
  • app_name: The name of the app.
  • avg_rating: An average of the individual ratings, based on a 1-5 scale.
  • country: The country this ranking list is for; 2 letter country code.
  • icon_url: The url of the app icon.
  • price: The price of the app, if it can be scraped from the ranking list.
  • publisher_id: The id of the publisher of this app as assigned by the store.
  • publisher_name: The display name of the publisher of this app.
  • rank: The numerical rank of this app in the given ranking list. Ie, the first app in the list would have 1 for this field, second app would have 2, etc.
  • rank_list: The identifier of which ranking list this is for. We try and use whatever identifier the store uses when possible. If not, we use the display name of the ranking list from the store.
  • timestamp: Date/hour when ranking was last updated.

Response Headers:

  • X-Request-ID: The id of the request to validate via Request Status API.
Note This is a bulk API call. Bulk API calls return one record per line.
Example:

App Ids for All Apps

Get a list of all the app ids AppMonsta knows about

https://api.appmonsta.com/v1/stores/<store>/ids 

Request Parameters:

  • store: android or itunes.

Response:

One app id per line.

Response Headers:

  • X-Request-ID: The id of the request to validate via Request Status API.
Note This is a bulk API call. Bulk API calls return one record per line.
Example:

App details for a single app

Request the most recent app details with the app's unique ID

 https://api.appmonsta.com/v1/stores/<store>/details/<app_id>.json?country=<country_code>

Request Parameters:

  • store: android or itunes.
  • country_code: The two letter country code of the country to fetch this app's details for, or ALL if you don't care which country.
  • app_id: The unique identifier/app_id for the correct store.
  • show_dead: (optional) If show_dead=1 is present, show apps that aren't currently available in the store.

Response Fields:

  • all_histogram: The histogram breakdown of ratings for all versions of this app. A dictionary with the keys 1-5 (as strings) mapped onto number of reviews with that number of stars.
  • all_rating: The average rating for all versions of this app.
  • all_rating_count: The number of ratings for all versions of this app.
  • all_reviews: The number of reviews for all versions of this app, if available as a summarized number.
  • app_name: The name of the app.
  • app_type: Whether the app is categorized as GAME or APPLICATION.
  • bundle_id: The internal bundle identifier of the app binary.
  • content_rating: The age-appropriate content rating of the app.
  • current_histogram: The histogram breakdown of ratings for the current version of this app. Should be a dictionary with the keys 1-5 (as strings) mapped onto number of reviews with that number of stars.
  • current_rating: The average rating for the current version of this app.
  • current_rating_count: The number of ratings for the current version of this app.
  • current_reviews: The number of reviews for the current version of this app, if available as a summarized number.
  • description: The text of the description of the app.
  • downloads: The number of downloads this app has, if available.
  • file_size: The file size of the downloadable app as a human readable string, if present.
  • file_size_bytes: The size of the app binary in bytes, if present.
  • genre: The primary category of an app, as it appears on the store side.
  • genres: All categories of an app, as they are returned from the store side.
  • has_game_center: A boolean (0 or 1) indicating whether this app supports Game Center.
  • iap_price_range: Price range of all in-app products available for the app.
  • icon_url: The url of the app icon.
  • id: The unique identifier for the app as assigned by the store.
  • in_app_purchases: In the iTunes store a list containing all available in-app products.
  • "in_app_purchases": [
      {
         "rank": "1",
         "name": "Town Folk - Skin Pack",
         "price": "$0.99"
      },
      {
         "rank": "2",
         "name": "City Folk - Skin Pack",
         "price": "$0.99"
      }
    ],
    
  • interactive_elements: A string containing interactive elements as listed on the app page.
  • is_universal: Whether the app is universal, meaning it's optimized for both iPhone and iPad.
  • languages: Languages that the app supports, as they're defined on the store side.
  • permissions: List of permissions required by this app.
  • "permissions": ['prevent device from sleeping',
                    'view network connections',
                    'find accounts on the device',
                    'full network access',
                    'receive data from Internet',
                    'access extra location provider commands',
                    'read phone status and identity',
                    'precise location (GPS and network-based)',
                    'approximate location (network-based)']
              
  • price: The price of the app.
  • publisher_address: Physical address of the publisher if listed in the app store.
  • publisher_email: The email address of the publisher of this app, if present.
  • publisher_id: The id of the publisher of this app as assigned by the store.
  • publisher_name: The display name of the publisher of this app.
  • publisher_url: The website of the publisher of this app.
  • related: A dictionary of related apps as presented by the source system. The keys are an identifier for the section of related apps, such as also_installed. The values are lists of app ids.
  • requires_hardware: A string indicating which hardware is required to run this app.
  • requires_os: A string indicating the minimum os/platform version this app requires, if present.
  • screenshot_urls: An array of screenshot urls.
  • seller: App seller name as it appears on Apple’s App Store.
  • status: Indicates what status_date is in relationship to. If it is either 'updated' or 'released', the app is available for download. If it is 'dead', the app is no longer present in the store.
  • status_date: The date the app was updated or released, as a string in whatever format it's displayed on the store.
  • status_unix_timestamp: The parsed unix timestamp of the status_date field.
  • support_url: A support url for this app, if it differs from publisher_url.
  • top_developer: A boolean whether this apps developer is marked as a top developer.
  • version: The current version of the app.
  • video_urls: An array of urls of demo videos for this app, if present.
  • whats_new: The text of the "What's new in this version" writeup, if present.

Note:

Any subscription for API access to this call includes ALL, regardless of what other countries are included in the subscription.

Example:

App details for all apps

Request the most recent app details for all apps

https://api.appmonsta.com/v1/stores/<store>/details.json?country=<country_code>&date=<date>

Request Parameters:

  • store: android or itunes.
  • country_code: The two letter country code of the country to fetch app details for, or ALL to fetch details for every app, regardless of country.
  • date: In the following format: YYYY-MM-DD.
  • show_dead: (optional) If show_dead=1 is present, show apps that aren't currently available in the store.
  • only_changed: (optional) If only_changed=1 is present, only show apps that have changed (in any field) since the previous date.

Requesting datasets older than one month:

  • We archive all app details datasets which are older than 30 days.
  • Historical (older than 30 days) all app details datasets are available only for Monday dates.
  • In order to retrieve all apps details for all apps for an older date you will need to first request data for the nearest Monday date and after that fetch and apply only changed app details (by using only_changed=1 parameter) up to the date you're interested in.

Steps for getting the all app details data for 2014-08-22

  1. 2014-08-22 is Friday and last Monday is 2014-08-18
  2. Fetch complete all app details data for Monday:
    https://api.appmonsta.com/v1/stores/<store>/details.json?country=<country_code>&date=2014-08-18
  3. Fetch only changed app details data from Tuesday through Friday:
    https://api.appmonsta.com/v1/stores/<store>/details.json?country=<country_code>&date=2014-08-19&only_changed=1
    https://api.appmonsta.com/v1/stores/<store>/details.json?country=<country_code>&date=2014-08-20&only_changed=1
    https://api.appmonsta.com/v1/stores/<store>/details.json?country=<country_code>&date=2014-08-21&only_changed=1
    https://api.appmonsta.com/v1/stores/<store>/details.json?country=<country_code>&date=2014-08-22&only_changed=1
    
  4. Apply only changed app details data on top of complete app details dataset in order.
  5. Start with Tuesday's changes and end with Friday's.
  6. You have successfully generated all app details for all apps dataset on your chosen date.

Requesting datasets older than February 2014:

  • We archive all app details datasets which are older than February 2014.
  • Historical (older than February 2014) all app details datasets are available only for Monday dates.
  • We can restore and make available any app details dataset within 2012-2014 on request.

Response Fields and Example: See previous call, Single App Details.

Response Headers:

  • X-Request-ID: The id of the request to validate via Request Status API.
Note This is a bulk API call. Bulk API calls return one record per line.
Example:
Show dead Only changed

Note:

Any subscription for API access to this call includes ALL, regardless of what other countries are included in the subscription.


All reviews

Request all reviews collected

https://api.appmonsta.com/v1/stores/<store>/reviews.json?language=<language>

Request Parameters:

  • store: android or itunes.
  • language: Specify language with two letter language code (ie, EN, FR, IT, etc).
  • start_date: Only returns reviews we have collected after this date. This can sometimes include few days older records than start_date, since it can take some time for us to scrape the reviews. It can also include even older reviews if they have changed in any way since the first time we have collected them.
  • end_date: Used with "start_date" parameter to get reviews we have collected within a particular time frame. If not specified we default this parameter to current date.

Response Fields:

  • app_id: The app id of the app this review is for.
  • app_version: The app version this review is for, if present.
  • date: Review date as a string in ISO format: YYYY-MM-DD.
  • date_str: The original review date format, a string.
  • device: The device the user is using, if present.
  • language: The language the review was written in.
  • last_scraped: Timestamp representing review last scrape date.
  • rating: The star rating the user gave with this review. 1-5.
  • review_id: The id assigned by the store. May be non-unique across apps.
  • review_text: The text of the body of the review.
  • title: The title/subject line of the review, as written by the user, if there is one.
  • user_id: The unique identifier for the user as assigned by the store ( deprecated for iTunes ).
  • user_name: The display name of the user writing the review.

Response Headers:

  • X-Request-ID: The id of the request to validate via Request Status API.
Note This is a bulk API call. Bulk API calls return one record per line.
Example:

Add a New App

Tell us about an app we don't know about yet. We do our best to find all apps, but occasionally we miss one (there isn't a complete list for Google Play).

https://api.appmonsta.com/v1/stores/<store>/details/<app_id>.json

Request Method: PUT

Request Parameters:

  • store: android or itunes.
  • app_id: the id of the app to add, e.g. com.rovio.angrybirds.

Response: 202 if successfully added.

Example:
$ curl -i -s -u '<your_api_key>:X' https://api.appmonsta.com/v1/stores/android/details/com.rovio.json -X PUT

HTTP/1.1 202 ACCEPTED
Date: Thu, 26 Sep 2013 22:18:38 GMT
Server: Apache/2.2.20 (Ubuntu)
Set-Cookie: client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; expires=Fri, 26-Sep-2014 22:18:38 GMT; Path=/
Vary: Accept-Encoding
Content-Length: 0
Content-Type: text/html; charset=utf-8
          

NOTE: The app details will be available within 10 minutes under normal circumstances. You can poll (no faster than every 10 seconds) the Details for a Single App method to wait for the app to be available.

Get Request Status

Validate a bulk API request to see if it is successfully completed or had any errors

https://api.appmonsta.com/v1/request/<request_id>

Request Method: GET

Request Parameters:

  • request_id: the id that's sent via X-Request-ID.

Response Fields:

  • status: Can be SUCCESS, ERROR, or ABORTED, if the request completed successfully, there are server side errors or the client aborted the request, respectively.
  • request_id: Equals to the request id given as parameter.
  • records: Number of records sent as response. Only available on SUCCESS.
  • md5: md5 sum of the response data. This does not include headers, but only the HTTP body sent. Only available on SUCCESS.
Example: For a successfully completed request:
{
  "status": "SUCCESS",
  "records": 10,
  "md5": "2909acb51bdb441b1f29f703ae6831e2",
  "request_id": "874995c4d75b4cb6bb8bbf6d3ef1d2da"
}
        
For requests that failed because of server error:
{
  "status": "ERROR"
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
        
For an aborted request:
{
  "status": "ABORTED"
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
        
For an unknown request:
{
  "message": "Unknown request id request_id."
}
        
Example (try using a X-Request-Id header returned by one of the requests above):

NOTE: This API will return ERROR for all ongoing requests. Please make sure to query this API after the connection ends.


Access to this API is available via monthly subscription. Contact us for pricing and details.