Curl

API Documentation for App Store & Google Play Store

Introduction

The AppTweak API is designed around REST principles. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP headers and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

API Endpoint 
https://api.apptweak.com

Authentication

You authenticate to the AppTweak API by providing one of your secret API token in the request. You can manage your API tokens from your account. Any request performed using one of your API token will be billed on your account so be sure to keep them secret!

Authentication to the API occurs using HTTP Headers. Provide your API token in the X-Apptweak-Key Header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Example Request 
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/ios/applications/284882215.json

Format

All successfull responses return a valid minified JSON document.

The Response Format

The JSON document is a hash which contains the response content and metadata about the request and about the response itself.

Parameters
content:
Varying The response content. Check the documentation of each request to have additional information about its content.
metadata:
hash Holds the metadata about the request and the response. Always holds the two following sub-keys :
metadata -> request
hash Holds the following metdata about the request: the store on which the request was performed, the time at which the request was fulfilled, the path of the request, and the params as parsed by our system. This is useful for debugging and allows you to verify how we treated your request
metadata -> content
hash Depending on the request we might add additional data here. Check the documentation of each request to verify which data are provided. When no additional data are provided, the hash is empty.
Example Request 
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/ios/searches.json?term=puzzle&country=FR&language=fr



Example Object 
{
  "content": [
    {
      "developer": "Ferran Tebe",
      "devices": [
        "iphone",
        "ipad",
        "ipod"
      ],
      "genres": [
        6014,
        6016,
        7012,
        7018
      ],
      "icon": "http://a5.mzstatic.com/eu/r30/Purple7/v4/7b/6f/20/7b6f2010-115a-a5c9-f796-5c89e8fa0564/icon180x180.jpeg",
      "id": 455696756,
      "price": "0,00 €",
      "slug": "puzzle-man-pro-jeu-puzzle",
      "title": "Puzzle Man Pro - un jeu de puzzle classique et addictif"
    },
    ...
  ],
  "metadata": {
    "content": {
      "size": 10,
      "total_size": 66561
    },
    "request": {
      "params": {
        "country": "fr",
        "device": "iphone",
        "format": "json",
        "language": "fr",
        "term": "puzzle"
      },
      "path": "/searches.json",
      "performed_at": "2015-09-23 12:35:56 UTC",
      "store": "ios"
    }
  }
}

Client Libraries

AppTweak provides a client library written in Python to easily interact with our API. This latter is open-source and allows to easily access and manipulate data from our REST API.

Visit the Github project page to learn how to setup and use it.

Usage

Each request you made on the AppTweak API count a for a calculated number of credits (c.f check details for each endpoint). To access our data, you have to subscribe first to one of our API Plan, corresponding to a given number of credits. This latter will allow you to fetch a certain amount of data, based on your number of available credits. At any time, you can check how many credits you have by requesting (for free) the following endpoint: usage.json (See example on the right for more details).


Rate Limit

The AppTweak API also has a limit on the number of requests you can perform in a given amount of time. Currently that limit is set to 60 requests per 10 seconds.


Usage Response

The response to the usage endpoint is a JSON hash containing the following inormation:

units_monthy (number):
Number of remaining credits based on your plan.
units_additional (number):
This value returns the number of remaining additional credits, associated with your account.
requests (hash):
List of hash representing the latest requests you made. A request object is a key/value pairs containing the following properties: path, date, cost, and status.

Note that you can access this endpoint any time for free.

Request Example 
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/usage.json

Response Example 
{
  "units_monthly": 24985,
  "units_additional": 0,
  "requests": [
    {
      "path": "/android/keywords/stats.json?keywords=代金回収&country=jp&language=ja",
      "date": "2019-06-19 19:21:49 +0000",
      "cost": 5,
      "status": 200
    },
    {
      "path": "/ios/keywords/stats.json?keywords=receive%20money&country=ca&language=ca",
      "date": "2019-06-19 19:21:48 +0000",
      "cost": 5,
      "status": 200
    },
    {
      "path": "/android/keywords/stats.json?keywords=paypal%20wire%20cash&country=in&language=en",
      "date": "2019-06-19 19:21:47 +0000",
      "cost": 5,
      "status": 200
    }
  ]
}

Organisation

The AppTweak API allows you to access the iOS and android stores. To specify the app store you wish to perform requests on, you must prefix the path of each request with the name of the OS you wish to access :

ios:
To access the Apple App Store for all iOS devices (iPhone, iPad, ...)
android:
To access the Google Play Store for all android devices (Google Nexus, Samsung Galaxy, HTC One, ...)

We try to provide an experience as smooth as possible by providing request methods and responses as similar as possible on both stores.

Access iOS Documentation Access Android Documentation
Example iOS Requests 
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/ios/applications/284882215.json

$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/ios/categories/top/6000.json

Example Android Requests 
$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/applications/com.facebook.katana.json

$ curl -H "X-Apptweak-Key: your-api-key" \
https://api.apptweak.com/android/categories/top/BUSINESS.json