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.

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.

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. 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 team. Rate limit information is included in response headers:

GET /apps/{appId}/keywords

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"
        },
        {
          "position": 2,
          "date": "2025-02-05",
          "locale": "en",
          "search_type": "search",
          "country": "US"
        }
      ],
      "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"
        }
      ],
      "averagePosition": 2,
      "latestPosition": 3,
      "score": 72
    }
  },
  "most_important_keywords": {
    "variant image": 28,
    "color swatch": 15
  }
}

Error Responses

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

Example Error Response

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