Rankbase API Documentation

Overview

Rankbase is a keyword ranking and analytics platform built by a Shopify app developer, for Shopify app developers. It connects to your Google Analytics 4 property and analyzes how users discover your app through App Store search, which keywords drive the most traffic and installs, and how your search position changes over time.

Working with Claude, Cursor, or another AI assistant? The same data is also available through the Rankbase MCP server, which your assistant can query directly without any API client code.

The Rankbase API lets you access this data programmatically so you can build custom dashboards, automate reporting, feed data into spreadsheets, or integrate keyword insights into your own tools and workflows. For a complete overview of all features, see the Rankbase documentation.

What data is available?

• Keyword rankings — Every search keyword that led users to your Shopify app listing, with position data, dates, countries, and locales.
• Install click keywords — Keywords that led to actual app install button clicks (not just listing views).
• Search type breakdown — Separate organic search results (search) from paid search ads (search_ad).
• Most important keywords — Automatically calculated keyword importance based on the share of total traffic each keyword drives.
• Per-shop install source — Look up the install source for a specific store by its .myshopify.com URL, including the source classification (App Store Search, Direct, Organic Search, etc.), date, and locale.

How it works

When a user searches the Shopify App Store, Shopify sends search query data to your connected Google Analytics 4 property. Rankbase reads this GA4 data, processes it into keyword reports, and exposes it through both the web dashboard and this API. You need to have Google Analytics connected for your app in the Rankbase dashboard before the API can return data.

Quick start

1. Sign up at https://rankbase.io and add your Shopify app.
2. Connect your Google Analytics 4 property in the app settings.
3. Go to the API section in your dashboard and create an API key.
4. Call GET /apps to look up the appId of each of your apps.
5. Use the API key as a Bearer token to make requests to the endpoints below.

Authentication

All API requests require a Bearer token in the Authorization header. You can create API keys from the API section in your dashboard.

Authorization: Bearer rb_your_api_key_here

API keys are scoped to your team. Any app belonging to your team can be queried using the same key. Each team can have up to 5 API keys.

Base URL

All API endpoints are served under the following base URL:

https://rankbase.io/api/v1

Rate Limiting

API requests are limited to 60 requests per minute per client (by IP address). Rate limit information is included in response headers:

GET /apps

Lists every Shopify app in your team, including each app's id — the {appId} required by the app-scoped endpoints (keywords and installs; popular keywords is global and takes none). Call this endpoint first to discover your app IDs: they are Rankbase-internal and do not match your app's Shopify Partner app ID or App Store handle.

Example Request

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/apps"

Response Fields

Example Response

{
  "total_apps": 2,
  "apps": [
    {
      "id": 30,
      "name": "Example Product Labels",
      "handle": "example-product-labels",
      "url": "https://apps.shopify.com/example-product-labels",
      "shopify_app_id": "1234567890",
      "analytics_connected": true,
      "created_at": "2024-04-01T09:30:00+00:00"
    },
    {
      "id": 31,
      "name": "Example Bulk Editor",
      "handle": "example-bulk-editor",
      "url": "https://apps.shopify.com/example-bulk-editor",
      "shopify_app_id": null,
      "analytics_connected": false,
      "created_at": "2024-05-12T14:05:00+00:00"
    }
  ]
}

GET /apps/{appId}/keywords

Find your app's appId with GET /apps.

Retrieve keyword ranking data for a specific Shopify app. Returns all search keywords that led users to your app listing on the Shopify App Store, along with position data, country breakdown, and importance scoring.

The appId is the numeric ID of your app in Rankbase. You can find it in the URL when viewing your app in the dashboard (e.g. /app/30 means appId is 30).

Query Parameters

Example Request

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/apps/30/keywords?days=30"

Example: Filter by date range

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/apps/30/keywords?start_date=2025-01-01&end_date=2025-01-31"

Example: Only install-click keywords from organic search

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/apps/30/keywords?days=30&installed=true&search_type=search"

Response Fields

Example Response

{
  "app_id": 30,
  "app_name": "My Shopify App",
  "days": 30,
  "installed": false,
  "search_type": "all",
  "total_keywords": 42,
  "keywords": {
    "variant image": {
      "totalUsers": 24,
      "positions": [
        {
          "position": 3,
          "date": "2025-02-04",
          "locale": "en",
          "search_type": "search",
          "country": "CA",
          "device": "desktop"
        },
        {
          "position": 2,
          "date": "2025-02-05",
          "locale": "en",
          "search_type": "search",
          "country": "US",
          "device": "mobile"
        }
      ],
      "averagePosition": 2.4,
      "latestPosition": 2,
      "score": 624
    },
    "color swatch": {
      "totalUsers": 5,
      "positions": [
        {
          "position": 1,
          "date": "2025-02-07",
          "locale": "fr",
          "search_type": "search",
          "country": "FR",
          "device": "desktop"
        }
      ],
      "averagePosition": 2,
      "latestPosition": 3,
      "score": 72
    }
  },
  "most_important_keywords": {
    "variant image": 28,
    "color swatch": 15
  }
}

GET /apps/{appId}/installs

Find your app's appId with GET /apps.

Look up the install source for one or more specific stores. Given Shopify .myshopify.com URLs, returns the install event(s) recorded for each store along with the source that drove the install (App Store Search, Direct, Organic Search, Google Ads, LLM, etc.) and the search keyword or referrer that brought the user.

Useful for deep-linking from your CRM, billing portal, or support dashboard so you can investigate where any specific customer originally came from. The lookup is not time-bounded: it returns the install regardless of when it happened, as long as the event is still retained in your Google Analytics property.

Up to 50 shops can be queried in a single request by passing a comma-separated list to shop_url. Internally the call hits Google Analytics once for the whole batch (filtered server-side), so it is meaningfully faster than making N separate calls.

The appId is the numeric ID of your app in Rankbase. You can find it in the URL when viewing your app in the dashboard (e.g. /app/30 means appId is 30).

Query Parameters

Example Request — Single Shop

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/apps/30/installs?shop_url=examplestore.myshopify.com"

Example Request — Batch (Multiple Shops)

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/apps/30/installs?shop_url=shop-a.myshopify.com,shop-b.myshopify.com,shop-c.myshopify.com"

Response Fields

Example Response

{
  "app_id": 30,
  "app_name": "My Shopify App",
  "total_shops": 2,
  "shops": [
    {
      "shop_url": "shop-a.myshopify.com",
      "total_installs": 1,
      "installs": [
        {
          "date": "2026-03-14",
          "shop_id": "12345678",
          "shop_url": "shop-a.myshopify.com",
          "source": "App Store Search",
          "type": "Organic Search",
          "value": "color swatch",
          "locale": "en",
          "country": "US",
          "device": "desktop"
        }
      ]
    },
    {
      "shop_url": "shop-b.myshopify.com",
      "total_installs": 0,
      "installs": []
    }
  ]
}

Empty Results

If a shop has no install event in your retained Google Analytics data, that shop's entry still appears in the response with "total_installs": 0 and an empty installs array. This is not an error — it just means the install isn't in GA (either it predates retention, or the shop hasn't installed your app). The API always returns one entry per requested shop_url.

GET /popular-keywords

Every popular search keyword on the Shopify App Store, discovered from the store's own search autocomplete (a keyword appears there only when merchants actually search it). This is a global dataset: it is the same for every team, is not limited to your apps, and takes no {appId}. Use it for keyword research: finding search phrases to target in your listing or to add to your tracked keywords.

The full list is returned in one response (no pagination). Use q to filter by substring.

Query Parameters

Example Request

curl -H "Authorization: Bearer rb_your_api_key" \
  "https://rankbase.io/api/v1/popular-keywords?q=variant"

Response Fields

Example Response

{
  "total_keywords": 2,
  "keywords": [
    {
      "keyword": "variant image",
      "source": "autocomplete",
      "first_seen_at": "2026-07-11T06:12:00+00:00",
      "last_seen_at": "2026-07-11T06:12:00+00:00"
    },
    {
      "keyword": "variant images",
      "source": "autocomplete",
      "first_seen_at": "2026-07-11T06:12:00+00:00",
      "last_seen_at": "2026-07-11T06:12:00+00:00"
    }
  ]
}

Error Responses

All errors return a JSON object with an error field describing what went wrong.

Example Error Response

{
  "error": "Invalid API key."
}