Add new public endpoints + recommended-keywords pagination (v1.1.0)

.claude-plugin/marketplace.json

@@ -9,8 +9,8 @@
     {
       "name": "asolytics-api",
       "source": "./",
-      "description": "Use the Asolytics Public API for App Store Optimization (ASO) research and automation: app metadata, availability, versions, installs and revenue estimates, rankings, keyword metrics, live search, recommended keywords, keyword tracking, competitors, projects, balance, and store charts.",
-      "version": "1.0.1",
+      "description": "Use the Asolytics Public API for App Store Optimization (ASO) research and automation: app metadata, availability, versions, installs and revenue estimates, rankings, keyword metrics, live search, recommended keywords, keyword tracking, competitors, projects, per-country keyword counts, balance, subscription limits, and store charts.",
+      "version": "1.1.0",
       "author": {
         "name": "Asolytics",
         "url": "https://asolytics.pro"

.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "asolytics-api",
   "displayName": "Asolytics API — App Store Optimization (ASO)",
-  "description": "Use the Asolytics Public API for App Store Optimization (ASO) research and automation: app metadata, availability, versions, installs and revenue estimates, rankings, keyword metrics, live search, recommended keywords, keyword tracking, competitors, projects, balance, and store charts.",
-  "version": "1.0.1",
+  "description": "Use the Asolytics Public API for App Store Optimization (ASO) research and automation: app metadata, availability, versions, installs and revenue estimates, rankings, keyword metrics, live search, recommended keywords, keyword tracking, competitors, projects, per-country keyword counts, balance, subscription limits, and store charts.",
+  "version": "1.1.0",
   "author": {
     "name": "Asolytics",
     "url": "https://asolytics.pro"

README.md

@@ -13,14 +13,14 @@ This is mainly an **ASO research & intelligence API** — pull keyword and app d
 | --- | --- |
 | **Keyword metrics** | Popularity (search volume), results count, and other metrics for any keyword — plus **popularity history** over time and an app's **ranking history** for a keyword. |
 | **Live search results** | The real **top-50 search results** for any keyword, country, and store — fetched live, right now. |
-| **Keyword ideas** | Recommended keywords Asolytics suggests for an app. |
+| **Keyword ideas** | Recommended keywords Asolytics suggests for a project — filterable by state and source. |
 | **App metadata** | Current store listing for any app — title, subtitle, description, screenshots & media, version history, and the countries it's available in. |
 | **Installs & revenue estimates** | Monthly **estimated installs** and **revenue**, per app and per country. |
-| **Rankings & store charts** | An app's category and keyword **ranking history**, plus full **top-500 store charts** by country, category, and device. |
+| **Rankings & store charts** | An app's category and keyword **ranking history** (or the **latest position per keyword** in one call), plus full **top-500 store charts** by country, category, and device. |
 | **Competitors** | The competitor set for any app. |
 | **Lookups** | Reference data to build valid queries: countries, locales, devices, categories, and clusters. |
 
-It can also **manage your own Asolytics workspace** in one place — your projects, tracked keywords & folders, competitor marks, and your remaining API **token balance** (the API is metered).
+It can also **manage your own Asolytics workspace** in one place — your projects (including **per-country keyword counts**), tracked keywords & folders, competitor marks, your **plan limits** (`total` vs `used`), and your remaining API **token balance** (the API is metered).
 
 Full endpoint-by-endpoint reference: [`skills/asolytics-api/references/endpoints.md`](skills/asolytics-api/references/endpoints.md).
 

skills/asolytics-api/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: asolytics-api
-version: 1.0.1
-description: Use the Asolytics Public API for ASO research and automation. Trigger this skill when the agent needs to query app metadata, availability, versions, installs, revenue, rankings, keyword metrics, live search results, recommended keywords, tracked keywords, tracking folders, competitors, projects, balance, or store charts from Asolytics. Also use it when a user wants curl examples, lightweight integrations, or repeatable reporting workflows against the Asolytics API.
+version: 1.1.0
+description: Use the Asolytics Public API for ASO research and automation. Trigger this skill when the agent needs to query app metadata, availability, versions, installs, revenue, rankings, keyword metrics, live search results, recommended keywords, tracked keywords, tracking folders, competitors, projects, per-country keyword counts, balance, subscription/plan limits, or store charts from Asolytics. Also use it when a user wants curl examples, lightweight integrations, or repeatable reporting workflows against the Asolytics API.
 homepage: https://github.com/Asolytics-Pro/asolytics-app-store-optimization-api
 ---
 
@@ -63,7 +63,7 @@ Use the Applications endpoints for:
 - store availability
 - version history
 - installs and revenue history
-- ranking history
+- ranking history (full history, or the latest known position per keyword via `applications/ranking/latest-by-keywords`)
 
 Start with the narrowest possible app set because some metadata endpoints bill per returned pair.
 
@@ -75,7 +75,7 @@ Use the Keywords and Recommended Keywords endpoints for:
 - popularity history
 - latest keyword metrics
 - live search top 50
-- recommended keyword review
+- recommended keyword review — `recommended-keywords` is **paginated** (`page`/`per_page`, 100–1000); loop until `pagination.current_page == pagination.total_pages`, and narrow with `filters[recommended_keyword_state][]` (recommended/tracked/declined) or `filters[sources][]` (meta/competitors/suggestions/rankings/related)
 - async rank tracking jobs with optional webhook callbacks
 
 When the user wants automation, prefer plain HTTP calls and return the exact request payload you used.
@@ -101,6 +101,13 @@ Use Competitors and Store Charts for:
 - marking or unmarking a competitor
 - retrieving top-500 charts by store, country, cluster, category, and device
 
+### Project & Account Insight
+
+Use Projects and Subscription for cheap, high-level dashboards:
+
+- `projects/countries-keywords-counts` — per-country tracked / recommended / ranking keyword counts plus their day-over-day `dynamic`, for one project. A cheap snapshot of project breadth; note it reflects the **previous day** (use the list endpoints for exact, current values).
+- `subscription/limits` — plan `total` vs `used` for keywords, apps, archived apps, and public API tokens. Pair with `GET /public-api/v1/balance` whenever quota or token headroom matters before a wide query.
+
 ## Guardrails
 
 - Treat the API as unstable unless the current OpenAPI spec confirms the shape you expect.

skills/asolytics-api/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

skills/asolytics-api/references/api-overview.md

@@ -42,6 +42,7 @@ curl -sS \
 - Installs history
 - Revenue history
 - Ranking history
+- Latest ranking position per keyword (`applications/ranking/latest-by-keywords`)
 
 ### Common Catalogs
 
@@ -60,7 +61,7 @@ Use these first when the user does not already know valid store, locale, country
 - Latest metrics
 - Live search top 50
 - Ranking track jobs
-- Recommended keywords
+- Recommended keywords (paginated; filter by state and source)
 - Decline and undecline actions
 
 ### Tracking
@@ -75,10 +76,15 @@ Use these first when the user does not already know valid store, locale, country
 - Mark competitor
 - Unmark competitor
 
+### Subscription
+
+- Plan limits — `total` vs `used` for keywords, apps, archived apps, and public API tokens (`subscription/limits`)
+
 ### Other
 
 - Balance
 - Projects list
+- Per-country keyword counters (`projects/countries-keywords-counts`)
 - Store charts
 
 ## Practical Workflow
@@ -122,3 +128,23 @@ curl -sS \
   -X POST "https://app.asolytics.pro/public-api/v1/tracking/folders" \
   -d '{"project_id":123,"name":"Core Keywords","description":"Tier 1 terms"}'
 ```
+
+### Latest position per keyword
+
+```bash
+curl -sS \
+  -H "X-PUBLIC-API-TOKEN: $ASOLYTICS_PUBLIC_API_TOKEN" \
+  --get "https://app.asolytics.pro/public-api/v1/applications/ranking/latest-by-keywords" \
+  --data-urlencode "origin_id=1234567890" \
+  --data-urlencode "country_code=US" \
+  --data-urlencode "keywords[]=fitness app" \
+  --data-urlencode "keywords[]=workout tracker"
+```
+
+### Plan limits (total vs used)
+
+```bash
+curl -sS \
+  -H "X-PUBLIC-API-TOKEN: $ASOLYTICS_PUBLIC_API_TOKEN" \
+  "https://app.asolytics.pro/public-api/v1/subscription/limits"
+```

skills/asolytics-api/references/endpoints.md

@@ -3,7 +3,7 @@
 - Source docs: `https://app.asolytics.pro/api/public-api/documentation`
 - Source OpenAPI: `https://app.asolytics.pro/api/public-api/docs?public-api-docs.json`
 - Generated from spec version: `1.0.0-alpha`
-- Generated at: `2026-06-12T15:44:35.307158+00:00`
+- Generated at: `2026-06-18T18:24:01.072654+00:00`
 
 ## Authentication
 
@@ -64,6 +64,16 @@
 `filters[position][from]` - in `query` - integer
 `filters[position][to]` - in `query` - integer
 
+### `GET /public-api/v1/applications/ranking/latest-by-keywords`
+
+- Summary: Latest ranking position per keyword
+- Notes: Returns the app's **latest known** ranking position for each of the requested keywords in the given store/country. Because keywords are parsed on independent schedules, each keyword carries its own `date` — they will not always share the same parse day. Keywords the app does not currently rank for are omitted from the response. The store (Google Play / App Store) is inferred from the `origin_id`. **Costs:** 1 token per 30 requested keywords, minimum 5 per call (billed on the request, not the number of rows returned).
+- Parameters:
+
+`origin_id` - in `query` - string - required
+`country_code` - in `query` - string - required
+`keywords[]` - in `query` - array<string> - required - maxItems=1000
+
 ### `GET /public-api/v1/applications/revenue`
 
 - Summary: Application revenue history
@@ -140,7 +150,7 @@
 - Parameters:
 
 `project_id` - in `query` - integer - required
-`filters[competitor_state][]` - in `query` - array<string>
+`filters[competitor_state][]` - in `query` - array<string> - maxItems=50
 
 ### `POST /public-api/v1/competitors/mark`
 
@@ -176,7 +186,7 @@
 `keywords[]` - in `query` - array<string> - required - maxItems=250
 `store` - in `query` - string - required - enum: APP_STORE, GOOGLE_PLAY
 `country_code` - in `query` - string - required
-`metrics[]` - in `query` - array<string> - required
+`metrics[]` - in `query` - array<string> - required - maxItems=50
 
 ### `GET /public-api/v1/keywords/popularity`
 
@@ -202,20 +212,6 @@
 `date_from` - in `query` - string - required
 `date_to` - in `query` - string - required
 
-### `POST /public-api/v1/keywords/ranking/track`
-
-- Summary: Track keyword rankings
-- Notes: Runs an on-demand keyword-ranking scan for a (store, country) and returns each keyword's top positions with the apps holding them. Use this when you need fresh ranking data *now* for keywords you don't already have tracked. Without `response_conf` the call blocks on the scan and the response carries the result; with `response_conf.url` the task is queued and the result is later POSTed to that URL (the immediate response then only carries task info). Up to 500 keywords per request. Keywords already in your tracked-keyword quota are billed as free; the remainder are **paid keywords**. **Costs:** 5 tokens per paid keyword, minimum 5 per call.
-
-- Request body:
-
-- Content-Type: `application/json`
-- `store` required: string (APP_STORE, GOOGLE_PLAY)
-- `country_code` required: string — Sourced from `/v1/common-catalogs/countries`.
-- `keywords` required: array<string>
-- `custom_data`: object — Arbitrary key/value data echoed back in the task info.
-- `response_conf`: object — When present, the task is processed asynchronously and the result is POSTed to `url`.
-
 ## Live Search
 
 ### `GET /public-api/v1/live-search`
@@ -231,6 +227,14 @@
 
 ## Projects
 
+### `GET /public-api/v1/projects/countries-keywords-counts`
+
+- Summary: Get per-country keyword counters
+- Notes: Returns, for every store country of the project, the tracked / recommended / ranking keyword counters together with their day-over-day `dynamic`. The result is keyed by 2-letter country code. **Note:** these counters are pre-aggregated and reflect the **previous day's** snapshot, so they may lag the real data by up to a day. For exact, up-to-the-moment values use the list endpoints directly (e.g. `/v1/tracking/keywords`, `/v1/recommended-keywords`, `/v1/applications/ranking`). **Costs:** 20 tokens per call.
+- Parameters:
+
+`project_id` - in `query` - integer - required
+
 ### `GET /public-api/v1/projects/list`
 
 - Summary: List user projects
@@ -241,13 +245,15 @@
 ### `GET /public-api/v1/recommended-keywords`
 
 - Summary: List recommended keywords
-- Notes: Returns the keywords we recommend you track for a project in the given country, surfaced from the project's app metadata, competitors' metadata, store suggestions, current rankings and related keywords. Each entry carries the phrase, the `sources` that proposed it and its current `state` (`recommended` — fresh suggestion, `tracked` — already in your tracking set, `declined` — you previously dismissed it via `/decline`). Filter by state or by source(s) to narrow the working set. **Costs:** `max(10, ceil(returned / 100))` tokens — minimum 10 per call, then 1 extra token for every started bucket of 100 returned keywords.
+- Notes: Returns the keywords we recommend you track for a project in the given country, surfaced from the project's app metadata, competitors' metadata, store suggestions, current rankings and related keywords. Each entry carries the phrase, the `sources` that proposed it and its current `state` (`recommended` — fresh suggestion, `tracked` — already in your tracking set, `declined` — you previously dismissed it via `/decline`). Filter by state or by source(s) to narrow the working set. The result is paginated — `pagination.total` reflects the filtered universe. **Costs:** `max(10, ceil(returned / 100))` tokens — minimum 10 per call, then 1 extra token for every started bucket of 100 keywords returned on the page.
 - Parameters:
 
 `project_id` - in `query` - integer - required
 `country_code` - in `query` - string - required
-`filters[recommended_keyword_state][]` - in `query` - array<string>
-`filters[sources][]` - in `query` - array<string>
+`page` - in `query` - integer
+`per_page` - in `query` - integer
+`filters[recommended_keyword_state][]` - in `query` - array<string> - maxItems=50
+`filters[sources][]` - in `query` - array<string> - maxItems=50
 
 ### `POST /public-api/v1/recommended-keywords/decline`
 
@@ -289,6 +295,13 @@
 `date_from` - in `query` - string - required
 `date_to` - in `query` - string - required
 
+## Subscription
+
+### `GET /public-api/v1/subscription/limits`
+
+- Summary: Get subscription limits
+- Notes: Returns the plan limits of the authenticated user's current subscription — `max_keywords`, `max_apps`, `max_archived_apps` and `max_public_api_tokens` — each as a `total` (plan allowance) / `used` (currently consumed) pair. Team members see their team owner's plan. **Costs:** 1 token per call.
+
 ## Tracking Folders
 
 ### `GET /public-api/v1/tracking/folders`