# RankGenius

> Real-time Amazon marketplace data over a simple REST API: keyword search rank (organic +
> sponsored), Buy Box ownership, parsed product pages, and customer reviews across 21
> marketplaces. AI agents can self-register for a free trial in one request - no signup form,
> no email, no human.

Base URL: https://rankgeniusapp.com/api/v1
Auth: send your key as `Authorization: Bearer <api_key>` on every tool call.
Every response is a JSON envelope: `{ "status": "ok"|"error", "error": "", "data": {...} }`.

## Start here (agents): get a free trial key

Make one unauthenticated request and you get a key with 100 free requests:

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

The response `data` contains `api_key`, `requests_remaining` (100), the allowed `tools`, and an
`upgrade_url`. Use the key immediately on the tool endpoints below.

Trial keys are REST-only and cover the read tools. They cannot use the MCP server or create
watches - those require a full (human-claimed) account. When the trial is spent, tool calls
return HTTP 402 with the `upgrade_url`; a human opens it to unlock full access and the same key
keeps working.

## Tools (GET, Bearer auth)

- [keyword_rank](https://rankgeniusapp.com/api/v1/keyword_rank?keyword=water+bottle): Amazon search results for a keyword - per-ASIN rank (organic + sponsored), price, reviews, rating, sales estimate, delivery. Optional `asin` locates a specific product; optional `zip` localizes the SERP.
- [buybox](https://rankgeniusapp.com/api/v1/buybox?asin=B085DVHQ57): Buy Box owner, price, and offers for an ASIN. Optional `zip` for a delivery estimate.
- [product_page](https://rankgeniusapp.com/api/v1/product_page?asin=B085DVHQ57): Parsed product detail - title, brand, price, rating, reviews count, BSR, images, variations, badges.
- [product_reviews](https://rankgeniusapp.com/api/v1/product_reviews?asin=B085DVHQ57): Customer reviews for an ASIN.
- [whoami](https://rankgeniusapp.com/api/v1/whoami): the authenticated account, plan, and remaining credit balance.

Common params: `marketplace` (default `us`; 21 supported), and `since` (freshness window in
seconds - a repeat of the same request within the window returns a cached result for free,
`cached: true`, no credits charged).

## Errors

- `401` - invalid/missing API key.
- `402` - out of credits (trial spent); `error` includes the upgrade URL.
- `429` - rate/usage limit reached; `error` includes the upgrade URL.

## Docs

- [Agent quickstart](https://rankgeniusapp.com/docs/agents): the full self-serve trial + upgrade flow.
- [OpenAPI spec](https://rankgeniusapp.com/openapi.json): machine-readable API definition.
- [REST API reference](https://rankgeniusapp.com/docs/api): every endpoint, params, and example responses.
- [MCP integration](https://rankgeniusapp.com/docs/mcp): connect an MCP client (full accounts).