> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Import Google Play report exports and read App Store Connect-style analytics rollups

Google Play analytics uses a synced dataset. Appeeky imports Play Console CSV reports and Android vitals first, then dashboard endpoints read from the imported data instead of calling Google live on every page load.

This avoids slow live GCS reads on every dashboard request and gives the UI the same shape as App Store Connect analytics.

***

## Data Sources

| Metric family                                                 | Source                                                   |
| ------------------------------------------------------------- | -------------------------------------------------------- |
| Installs, device acquisitions, first opens, MAU, install base | `stats/installs/` CSV exports                            |
| Ratings count and average rating                              | `stats/ratings/` CSV exports                             |
| Crashes and ANRs                                              | `stats/crashes/` CSV exports and Developer Reporting API |
| Crash rate and ANR rate                                       | Developer Reporting API                                  |
| Store listing visitors, acquisitions, conversion              | `stats/store_performance/` CSV exports                   |
| Search terms and traffic sources                              | `stats/store_performance/` traffic source report         |

Google captures daily rows, but report exports can lag Play Console by several days. Monthly CSV files are updated as Google publishes new data.

***

## Import Report Families

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/google-play/analytics/import-reports" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prefixes": [
      "stats/installs/",
      "stats/crashes/",
      "stats/ratings/",
      "stats/store_performance/"
    ],
    "maxObjects": 100
  }'
```

| Field        | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `prefixes`   | Report folders to import. Defaults to all supported stats prefixes. |
| `maxObjects` | Safety cap for how many objects to import in one request.           |
| `bucket`     | Optional bucket override. Usually use saved `reportsBucket`.        |

Use this endpoint for initial backfill and manual sync testing. Scheduled jobs can run the same import flow in the background.

***

## Import One Report

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/google-play/analytics/import-report" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objectName": "stats/ratings/ratings_com.example.app_202601_overview.csv"
  }'
```

This is useful when testing one CSV object or replaying a failed import.

***

## Sync Android Vitals

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/google-play/apps/com.example.app/analytics/vitals-sync" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-05-01",
    "to": "2026-06-01"
  }'
```

Vitals sync queries the Google Play Developer Reporting API and stores daily crash/ANR metrics for dashboard reads.

***

## Read App Analytics

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/google-play/apps/com.example.app/analytics?from=2026-05-01&to=2026-06-01" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

Response shape:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "platform": "google",
    "packageName": "com.example.app",
    "period": {
      "from": "2026-05-01",
      "to": "2026-06-01"
    },
    "totals": {
      "device_acquisitions": 107,
      "first_opens": 15,
      "mau": 242,
      "store_listing_visitors": 920,
      "store_listing_acquisitions": 107,
      "store_listing_conversion_rate": 0.1163,
      "ratings_count": 12,
      "average_rating": 4.5,
      "crash_rate": 0.0012,
      "anr_rate": 0.0004
    },
    "rows": []
  }
}
```

***

## Read Account Analytics

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/google-play/analytics?from=2026-05-01&to=2026-06-01" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

Use this to show an account-level overview across imported Play apps.

***

## Sources and Countries

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/google-play/apps/com.example.app/analytics/sources?from=2026-05-01&to=2026-06-01" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

This endpoint returns traffic source, country, and UTM breakdowns where Google includes them in the store performance report.

***

## Search Terms

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/google-play/apps/com.example.app/analytics/search-terms?from=2026-05-01&to=2026-06-01" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

Search-term rows come from the `stats/store_performance/` traffic source export. Google may suppress low-volume rows, and some monthly exports may not include the `Search term` column.

Expected row fields:

| Field                           | Description                      |
| ------------------------------- | -------------------------------- |
| `search_term`                   | Play Store search term           |
| `store_listing_visitors`        | Visitors from that term          |
| `store_listing_acquisitions`    | Acquisitions from that term      |
| `store_listing_conversion_rate` | Acquisitions divided by visitors |
| `country`                       | Country breakdown when available |

***

## Dashboard Mapping

| Dashboard card                | Google Play source                               |
| ----------------------------- | ------------------------------------------------ |
| Device acquisitions           | `stats/installs/`                                |
| First opens                   | `stats/installs/`                                |
| MAU                           | `stats/installs/`                                |
| Install base                  | `stats/installs/`                                |
| Crash rate                    | Developer Reporting API and `stats/crashes/`     |
| ANR rate                      | Developer Reporting API and `stats/crashes/`     |
| Average rating                | `stats/ratings/`                                 |
| Store listing conversion rate | `stats/store_performance/`                       |
| Search terms                  | `stats/store_performance/` traffic source report |

Revenue and buyer metrics require financial report access. They are separate from the four stats folders above.

***

## Why Not Query GCS Live?

Live GCS requests are acceptable for testing, but not for every dashboard view:

* Report files can be large.
* CSV parsing is slower than reading already-synced analytics data.
* Google exports are monthly files with daily rows inside.
* The same report may be needed by multiple users, charts, and filters.
* Background imports let the UI stay fast and consistent.

The recommended model is:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Scheduled import -> synced analytics data -> dashboard API -> web UI
```