# Shopify AI Rank Checker (`onescales/shopify-ai-rank-checker`) Actor Shopify Global Catalog ranking checker tool for ChatGPT, Gemini, Perplexity & Grok shopping results. Spot competitors and data gaps instantly. - **URL**: https://apify.com/onescales/shopify-ai-rank-checker.md - **Developed by:** [One Scales](https://apify.com/onescales) (community) - **Categories:** AI, E-commerce, SEO tools - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 2 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Shopify AI Rank Checker ### Introduction ChatGPT, Gemini, Perplexity, Grok, and Copilot are already recommending products to shoppers — and they're not crawling your website to do it. They query Shopify's Global Catalog directly through the UCP (Universal Commerce Protocol) MCP interface. Every product on Shopify is in this catalog by default, but merchants have almost no visibility into how they actually rank when an AI searches for something like "trail running shoes" or "organic coffee beans." Shopify AI Rank Checker queries the same Global Catalog MCP endpoint that AI shopping agents use, finds your shop's product among the results, and reports your exact rank, who's outranking you, and how complete your listing data looks to the catalog. No Shopify API key, partner account, or bearer token is required — the actor authenticates the same lightweight way real AI agents do. [![Watch the video](https://img.youtube.com/vi/RLQLs9Q0oyI/maxresdefault.jpg)](https://www.youtube.com/watch?v=RLQLs9Q0oyI) ### Features - Checks your product's rank position for any number of keywords in a single run — the same rank AI agents like ChatGPT, Gemini, Perplexity, and Grok see and act on - Scans the top 100 results per keyword using real cursor-based pagination against the Global Catalog - Two report modes: a **Simple** report (rank, matched URL, top 10 result URLs) for quick checks, or a **Full** report with complete product, variant, and seller data for every single competitor scanned — not just your own listing — via `rank1`, `rank2`, ... `rankN` columns - See exactly which competitors are outranking you and why, with their full product data side by side with yours - Reports a data quality score for your matched product in Full mode, based on which enrichment signals (description, media, options, rating, categories) are present - Lets you set buyer shipping context (country) to see country-specific results - No API key, OAuth flow, or Shopify Partner account needed ### Use Cases - Merchants finding out for the first time whether ChatGPT, Gemini, Perplexity, or Grok are even surfacing their products - Merchants doing a quick, lightweight check of where they rank for a keyword (Simple mode) - Merchants auditing their visibility in AI agent shopping results before and after SEO/content changes (Full mode) - Agencies running agentic-commerce visibility reports for Shopify clients - Tracking how a product's rank shifts over time by scheduling repeated runs - Comparing your own listing's data completeness against the competitors ranking above you - Spotting when a product disappears from Global Catalog results entirely (stock issues, data problems, etc.) ### Input #### In the Apify UI | Field | Required | Description | |---|---|---| | **Shop Domain** | Yes | Your shop's domain to find in results, e.g. `example-store.myshopify.com`. Matched against the catalog's seller domain and storefront URL. | | **Keywords** | Yes | List of search queries to check your rank for (1–50 keywords). One API call is made per keyword. | | **Report Detail** | No | `Simple` (default) returns just keyword, rank, the matched product's URL, and the top 10 result URLs. `Full` returns everything, including complete data for every scanned result via `rank1`...`rankN` columns. | | **Ships-To Country** | No | ISO 3166-1 alpha-2 country code for buyer context, e.g. `US`, `DE`, `GB` (default `US`). Affects which results and prices are returned. | The scan depth is fixed at the top 100 results per keyword and isn't configurable in the input — this keeps runs predictable and cost-consistent. #### As JSON ```json { "shop_domain": "example-store.myshopify.com", "keywords": ["trail running shoes", "waterproof hiking boots"], "report_detail": "simple", "ships_to_country": "US" } ```` ### Output One dataset row is produced per keyword checked. The fields returned depend on the **Report Detail** setting. #### In the Apify UI (Output tab → "Catalog Rank Results") **Simple mode** | Column | Description | |---|---| | **Keyword** | The search keyword that was checked | | **Rank** | Your product's position in results, or empty if not found in the top 100 | | **URL Found** | The full URL to your matched product (the first product from your shop that ranked) | | **Top 10 Results** | The URLs of the top 10 scanned results for this keyword | **Full mode** — everything above (rank fields differ slightly, see below) plus: | Column | Description | |---|---| | **Scanned** | Number of results actually scanned for this keyword | | **Matched Product** | Title of your product that matched | | **Product URL** | Checkout/product URL of your matched product | | **Not Found Reason** | Explanation when no match was found | | **Data Quality Score** | 0–100 score of enrichment signals (description, media, options, rating, categories) present on your matched product | | **Rank 1 ... Rank 100** | Full product, variant, and seller data for every product scanned — including title, description, price, image, availability, condition, checkout URL, and seller domain/name/policies | #### As JSON Simple mode: ```json { "keyword": "7 foot pool table", "rank": 2, "urlFound": "https://www.legacybilliards.com/products/baylor-ii-7-ft-pool-table-modern", "top10Results": [ "https://www.playgosports.com/products/gosports-mid-size-...", "https://www.legacybilliards.com/products/baylor-ii-7-ft-pool-table-modern", "https://www.garvee.com/products/garvee-pool-table-7ft-foldable-...", "..." ] } ``` Full mode: ```json { "keyword": "7 foot pool table", "rank": 2, "totalScanned": 50, "matchedTitle": "Baylor 7 Ft Pool Table - Modern Series", "matchedUrl": "https://www.legacybilliards.com/cart/39636266057837:1", "notFoundReason": null, "dataQualityScore": 60, "enrichmentChecks": { "hasDescription": true, "hasMedia": true, "hasOptions": true, "hasRating": false, "hasCategories": false }, "priceRange": { "min": { "amount": 374999, "currency": "USD" }, "max": { "amount": 374999, "currency": "USD" } }, "rank1": { "title": "GoSports Mid-Size 7ft x 3.9ft Billiards Game Table", "productId": "gid://shopify/p/7IVcI03tgSahE96SzlH04f", "description": "A foldable 7ft mid-size billiards table with full set...", "price": { "amount": 59999, "currency": "USD" }, "available": true, "condition": ["new"], "productUrl": "https://www.playgosports.com/products/...", "checkoutUrl": "https://www.playgosports.com/cart/...", "shopDomain": "playgosports-com.myshopify.com", "shopName": "PlayGoSports.com" }, "rank2": { "...": "same structure as rank1, for the product in position 2" } } ``` ### Support For bugs, feature requests, or questions — reach us at https://docs.google.com/forms/d/e/1FAIpQLSfsKyzZ3nRED7mML47I4LAfNh\_mBwkuFMp1FgYYJ4AkDRgaRw/viewform?usp=dialog ### Tags shopify, ai, keyword, rank, checker, check, tool, ai seo, aeo, aio, shopify global catalog, rank checker, Keyword Rank Checker Tool, keyword tool, ranking, competitors, position, tracker, rank tracker # Actor input Schema ## `shop_domain` (type: `string`): Your shop's domain to find in results, matched against variant.seller.domain, e.g. example-store.myshopify.com ## `keywords` (type: `array`): Search queries to check your rank for (1-50 keywords). ## `report_detail` (type: `string`): Simple: keyword, rank, the URL of your matched product, and the top 10 result URLs. Full: everything, including complete product/variant/seller data for every scanned result via rank1...rankN columns. ## `ships_to_country` (type: `string`): ISO 3166-1 alpha-2 country code for buyer context, e.g. US, DE, GB. ## Actor input object example ```json { "shop_domain": "example-store.myshopify.com", "keywords": [ "trail running shoes" ], "report_detail": "simple", "ships_to_country": "US" } ``` # Actor output Schema ## `catalogRankResults` (type: `string`): Rank results for all checked keywords # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "shop_domain": "example-store.myshopify.com", "keywords": [ "trail running shoes" ], "ships_to_country": "US" }; // Run the Actor and wait for it to finish const run = await client.actor("onescales/shopify-ai-rank-checker").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "shop_domain": "example-store.myshopify.com", "keywords": ["trail running shoes"], "ships_to_country": "US", } # Run the Actor and wait for it to finish run = client.actor("onescales/shopify-ai-rank-checker").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "shop_domain": "example-store.myshopify.com", "keywords": [ "trail running shoes" ], "ships_to_country": "US" }' | apify call onescales/shopify-ai-rank-checker --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=onescales/shopify-ai-rank-checker", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Shopify AI Rank Checker", "description": "Shopify Global Catalog ranking checker tool for ChatGPT, Gemini, Perplexity & Grok shopping results. Spot competitors and data gaps instantly.", "version": "1.0", "x-build-id": "vbE48Kd8fPxNP2dTd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/onescales~shopify-ai-rank-checker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-onescales-shopify-ai-rank-checker", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/onescales~shopify-ai-rank-checker/runs": { "post": { "operationId": "runs-sync-onescales-shopify-ai-rank-checker", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/onescales~shopify-ai-rank-checker/run-sync": { "post": { "operationId": "run-sync-onescales-shopify-ai-rank-checker", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "shop_domain", "keywords" ], "properties": { "shop_domain": { "title": "Shop Domain", "type": "string", "description": "Your shop's domain to find in results, matched against variant.seller.domain, e.g. example-store.myshopify.com" }, "keywords": { "title": "Keywords", "maxItems": 50, "type": "array", "description": "Search queries to check your rank for (1-50 keywords).", "items": { "type": "string", "maxLength": 200 } }, "report_detail": { "title": "Report Detail", "enum": [ "simple", "full" ], "type": "string", "description": "Simple: keyword, rank, the URL of your matched product, and the top 10 result URLs. Full: everything, including complete product/variant/seller data for every scanned result via rank1...rankN columns.", "default": "simple" }, "ships_to_country": { "title": "Ships-To Country", "type": "string", "description": "ISO 3166-1 alpha-2 country code for buyer context, e.g. US, DE, GB.", "default": "US" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```