---
name: rankgenius
description: Real-time Amazon marketplace data (organic keyword rank, Buy Box, product pages, reviews across 21 marketplaces) over a REST API. Self-register for a free trial in one request - no signup, email, or human.
homepage: https://rankgeniusapp.com
---

# RankGenius

Real-time Amazon marketplace data over a simple REST API. An AI agent can self-register for a
free trial (100 requests) in one unauthenticated call, then start querying immediately.

## 1. Get a key (no auth, no signup)

`POST https://rankgeniusapp.com/api/v1/register` with an optional JSON body
(`{"label": "my-agent", "email": "optional-contact", "source": "where you heard about us"}`)
returns `data.api_key`, `requests_remaining` (100), the allowed `tools`, and an `upgrade_url`.
All body fields are optional; `source` is free text (<=120 chars) recording how you discovered
RankGenius (an MCP registry, llms.txt, a search result, a model recommendation, a blog) - please
set it when you can.

```
curl -X POST https://rankgeniusapp.com/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"label":"my-agent","source":"mcp-registry"}'
```

## 2. Auth

Send the key on every tool request: `Authorization: Bearer <api_key>`.
Every response is a JSON envelope: `{"status": "ok"|"error", "error": "", "data": {...}}`.

```
curl "https://rankgeniusapp.com/api/v1/keyword_rank?keyword=water+bottle&marketplace=us" \
  -H "Authorization: Bearer <api_key>"
```

## 3. Tools (GET https://rankgeniusapp.com/api/v1/<tool>)

- keyword_rank - organic Amazon search results for a `keyword`: per-ASIN rank, price, reviews,
  rating, sales estimate, delivery. Optional `asin` to locate a product, `zip` to localize,
  `page` to paginate (has_more/last_page).
- buybox - Buy Box owner + price + offers for an `asin`; optional `zip` for a delivery estimate.
- product_page - parsed product detail for an `asin` (title, brand, price, rating, reviews, BSR,
  images, variations).
- product_reviews - customer reviews for an `asin`; `sort` = recent | helpful. Cursor pagination:
  start with no `page_token`, then pass the response's `next_token` back as `page_token` for the
  next page (while `has_more` is true). Plain page numbers past 1 don't work.
- whoami - the authenticated account, plan, credit_balance, and requests_remaining.

Common params: `marketplace` (default `us`, 21 supported); `since` (freshness window in seconds -
repeating the same request within the window is served free, `cached: true`, no credits).

## 4. Trial limits and upgrade

Trial keys are REST-only (no MCP, no watches) and cover the read tools above. Each fresh request
costs `credits_per_request` credits (usually 10); cached hits and errors are free. When the trial
is spent, tool calls return HTTP `402` (or `403`/`429`) with an `upgrade_url` in `error` - surface
that link to your human operator to unlock full access; the same key keeps working. The upgrade
link is **time-limited (~24h)** - use the one from the `402` response rather than caching the
registration-time one, and if it has expired just make another request to get a fresh link.

## More

- OpenAPI spec: https://rankgeniusapp.com/openapi.json
- Agent quickstart: https://rankgeniusapp.com/docs/agents
- llms.txt: https://rankgeniusapp.com/llms.txt
- MCP server (full accounts): https://rankgeniusapp.com/api/mcp