Competitors

Returns the team's tracked (followed) competitors for an app as a paginated object: "list", each row enriched with category and keyword overlap against your own app, falling back to a provisional set when the team follows none yet.

The endpoint 404s with resource_not_found when the addressed app does not exist or is not tracked by your team. When the team follows no competitors yet, a provisional set (embedding-similar → top-category apps) is returned rather than erroring, and metadata.is_provisional is true. It reads the scraped catalog only, so it always returns a list — there is no Partner / BigQuery gate.

GET/api/v1/apps/:app/competitors

Tracked competitors

The team's tracked (followed) competitors for this app, paginated as an object: "list". This is the followed set — the same one the dashboard and scorecard use — not catalog-similar discovery. Each row is a compact app card (id, slug, name, rating, reviews_count, est_installs, logo_url) plus five overlap stats against your own app (shared_categories, shared_keywords, relevance_score, category_avg_rank, keyword_avg_rank). The overlap fields are null when that tracked competitor is not also a catalog-competitor of your app; rows with a null relevance_score sort last on relevance.

When the team follows no competitors, a provisional set (embedding-similar → top-category apps) is returned and metadata.is_provisional is true. The endpoint reads the scraped catalog only, so it always returns a list — there is no Partner / BigQuery gate.

Path parameter

Name
app
Type
string
Description
The team app's ULID, e.g. 01JN4HKQX0000000000000000.

Query parameters

Name
sort
Type
string
Description
One of relevance (default), reviews, rating. Whitelisted — any other value returns 422.
Name
order
Type
string
Description
asc or desc (default desc).
Name
page
Type
integer
Description
The page to return (≥ 1). Default 1.
Name
per_page
Type
integer
Description
Rows per page (1–100). Default 25.

Request

GET

/api/v1/apps/:app/competitors

curl -G https://ranksyapp.com/api/v1/apps/01JN4HKQX0000000000000000/competitors \
  -H "Authorization: Bearer rk_live_..." \
  -d sort=reviews \
  -d order=desc \
  -d per_page=25

Response

{
  "object": "list",
  "url": "/api/v1/apps/01JN4HKQX0000000000000000/competitors",
  "page": 1,
  "per_page": 25,
  "total_count": 6,
  "has_more": false,
  "metadata": { "is_provisional": false },
  "data": [
    {
      "id": 4471,
      "slug": "stocky",
      "name": "Stocky",
      "rating": 4.5,
      "reviews_count": 540,
      "est_installs": 9100,
      "logo_url": "https://cdn.shopify.com/app-store/listing/stocky/icon.png",
      "shared_categories": 3,
      "shared_keywords": 27,
      "relevance_score": 84,
      "category_avg_rank": 6.4,
      "keyword_avg_rank": 9.1
    }
  ]
}

List envelope

The list envelope is shared across catalog collections. Competitor lists are not date-windowed, so the coverage block is omitted.

Name
object
Type
string
Description
Always "list".
Name
url
Type
string
Description
Path of this list resource.
Name
page
Type
integer
Description
Current page number (1-based).
Name
per_page
Type
integer
Description
Rows per page.
Name
total_count
Type
integer
Description
Total rows across every page.
Name
has_more
Type
boolean
Description
Whether more pages follow this one.
Name
metadata
Type
object
Description
Endpoint-specific metadata; carries the is_provisional flag for this endpoint.
Name
data
Type
array
Description
The competitor rows.

Competitor row

Name
id
Type
integer
Description
Internal ShopifyApp id of the competitor.
Name
slug
Type
string
Description
App Store slug (handle) of the competitor.
Name
name
Type
string
Description
Competitor app name.
Name
rating
Type
number
Description
Average star rating (rounded to 1 dp), or null when unrated.
Name
reviews_count
Type
integer
Description
Total number of reviews, or null.
Name
est_installs
Type
integer
Description
Estimated active installs, or null when not estimated.
Name
logo_url
Type
string
Description
Competitor app icon URL, or null when not captured.
Name
shared_categories
Type
integer
Description
Catalog categories shared with your app; null when the competitor is not one of your app's catalog-competitors.
Name
shared_keywords
Type
integer
Description
Keywords both apps rank for; null when not a catalog-competitor.
Name
relevance_score
Type
integer
Description
Catalog relevance score (higher = more similar); null when not a catalog-competitor. Null-score rows sort last on relevance.
Name
category_avg_rank
Type
number
Description
Competitor's average rank across the shared categories (1 dp); null when not a catalog-competitor.
Name
keyword_avg_rank
Type
number
Description
Competitor's average rank across the shared keywords (1 dp); null when not a catalog-competitor.

Errors

Beyond the universal 401 / 403 / 422 / 429 (see Errors), this endpoint returns:

404 resource_not_found — the addressed app does not exist or is not tracked by your team.

The endpoint does not read the Shopify Partner integration or BigQuery — it serves from the scraped catalog — so it never returns the 409 partner errors documented for the metrics endpoints. A bad query parameter (an unknown sort token, a non-integer page, per_page over 100) surfaces as 422 validation_failed.