Skip to main content

Downloads Metrics API (Legacy and V2)

This API provides daily and aggregated app download metrics for authorized clients. It is used by external consumers to fetch downloads within a selected date range.

There are currently two endpoint versions:

  • a legacy version kept for backward compatibility
  • a v2 version with standard HTTP error semantics

All new client integrations must use the v2 endpoint.

Use this document as the single integration reference for both versions.

Which endpoint should I use?​

VersionEndpointRecommended forError HTTP behavior
LegacyGET /misc/downloads-apiExisting clients already integratedAlways 200 (errors are in body)
V2GET /misc/v2/downloads-apiAll new client integrationsProper HTTP status codes (400/403/404/429/500)

Base URL:

https://db.appinchina.co

Quick Start (Developers)​

Request​

curl "https://db.appinchina.co/misc/v2/downloads-api?id=YOUR_CLIENT_ID&start=2026-04-01&end=2026-04-30"

Required query params​

  • id (string): your assigned client API ID
  • start (string): start date
  • end (string): end date

Rules​

  • Date range is inclusive.
  • start and end should use YYYY-MM-DD.
  • start must be earlier than or equal to end.
  • Maximum date range is 366 days.
  • Requests are subject to a daily usage limit.

Response Contract​

Success shape​

{
  "data": {
    "result": "success",
    "usage": {
      "dailyLimit": 100,
      "usedToday": 4,
      "remainingToday": 96
    },
    "downloadsData": {
      "start": "2026-04-01",
      "end": "2026-04-30",
      "downloads": [
        {
          "store": "All Stores",
          "updateDownloads": 278,
          "newDownloads": 475,
          "totalDownloads": 753
        },
        {
          "store": "HUAWEI",
          "downloadsArray": [
            {
              "date": "2026-04-01",
              "updateDownloads": 100,
              "newDownloads": 91,
              "totalDownloads": 191
            }
          ],
          "updateDownloads": 214,
          "newDownloads": 204,
          "totalDownloads": 418
        }
      ]
    }
  }
}

Error shape (both versions)​

{
  "data": {
    "result": "error",
    "responseBody": "human-readable message",
    "errorCode": "MACHINE_READABLE_CODE"
  }
}

Some errors include additional fields (for example: dailyLimit, usedToday, remainingToday, resetAt).

Error example​

{
  "data": {
    "result": "error",
    "responseBody": "daily limit reached",
    "errorCode": "DAILY_LIMIT_REACHED",
    "dailyLimit": 100,
    "usedToday": 100,
    "remainingToday": 0,
    "resetAt": "2026-04-18T00:00:00.000Z"
  }
}

Status Codes by Version​

Legacy (/misc/downloads-api)​

  • 200 OK for success and API-level errors.
  • Clients must always inspect data.result.

V2 (/misc/v2/downloads-api)​

  • 200 OK success
  • 400 Bad Request missing/invalid query params or invalid date range
  • 403 Forbidden ID not allowed
  • 404 Not Found mapped internal app not found
  • 429 Too Many Requests daily limit reached
  • 500 Internal Server Error server-side processing error

Error Codes​

  • MISSING_REQUIRED_QUERY_PARAMS
  • INVALID_DATE
  • INVALID_DATE_RANGE
  • DATE_RANGE_TOO_LONG
  • ID_NOT_ALLOWED
  • ID_NOT_FOUND
  • DAILY_LIMIT_REACHED
  • LIMIT_CHECK_FAILED
  • DOWNLOADS_FETCH_FAILED

Integration Guidance​

  • For all new client integrations, use the v2 endpoint.
  • For existing legacy integrations, keep current behavior and migrate when convenient.
  • In both versions, parse data.result and errorCode for deterministic handling.
  1. Check HTTP status (especially in v2).
  2. Parse JSON body.
  3. Check data.result:
    • success -> process downloadsData
    • error -> handle by errorCode
  4. Use usage.remainingToday for client-side throttling/UX.

Migration Notes (Legacy -> V2)​

  • Path changes from /misc/downloads-api to /misc/v2/downloads-api.
  • Error HTTP status semantics become standard in v2.
  • Response body structure remains consistent (data.result, downloadsData, errorCode).