# qequals

> Google autocomplete suggestions and live Google search results, as an API. Built so an agent can start without an account. The [catalog](https://www.qequals.com/catalog) is the public proof of the suggestion data.

This file is the API. There is no docs site and no OpenAPI spec. Read it once, mint a key, make a call.

Humans: [www.qequals.com](https://www.qequals.com) · [catalog](https://www.qequals.com/catalog) · [account](https://www.qequals.com/account) · [help@qequals.com](mailto:help@qequals.com)

---

## Start

1. Mint an anonymous key. No email, no account.

```
POST https://api.qequals.com/v1/keys
```

```json
{
  "key": "qe_anon_7f3a9c2e5b8d41f0",
  "tier": "anonymous",
  "quota": {
    "suggestions": { "limit": 10, "remaining": 10, "period": "day" },
    "search": null
  }
}
```

2. Call suggestions with that key. That is the first call.

```
GET https://api.qequals.com/v1/suggestions?q=serp%20api
Authorization: Bearer qe_anon_7f3a9c2e5b8d41f0
```

3. If a call returns `quota_exceeded`, tell your operator. They register at [https://www.qequals.com/account](https://www.qequals.com/account). Registration upgrades **this** key. Do not mint a second one.
4. A registered key triples the daily suggestion quota and adds a small monthly allowance of live search results. Pro is $9 / month: 300 suggestions / day and 300 search results / month, bought on the same account page. Pro is more quota, metered, not unlimited. Unused quota dies at period end.

---

## Keys and quotas

One key per caller. Signup upgrades it in place. Send it on every call as `Authorization: Bearer {key}`.

| | Suggestions | Search results |
|---|---|---|
| Anonymous | 10 / day | — |
| Registered (free) | 30 / day | 10 / month |
| Pro | 300 / day | 300 / month |

Every `/v1/suggestions` and `/v1/search` response includes quota headers (including errors except `invalid_key`):

```
RateLimit-Limit: 10
RateLimit-Remaining: 8
RateLimit-Reset: 1692403200
```

`RateLimit-Reset` is the Unix time of the next UTC midnight (suggestions) or the next UTC month start (search).

When quota is exhausted, the call fails. Do not retry as if it succeeded. If Google itself fails, the call fails. There is no invented list. A cache hit still burns quota.

---

## Suggestions

Anonymous keys welcome.

```
GET https://api.qequals.com/v1/suggestions?q={seed}
Authorization: Bearer {key}
```

`q` is the seed, URL-encoded. Required.

```
GET https://api.qequals.com/v1/suggestions?q=serp%20api
Authorization: Bearer qe_anon_7f3a9c2e5b8d41f0
```

```json
{
  "q": "serp api",
  "suggestions": [
    "serp api python",
    "serp api javascript",
    "google serp api official",
    "serp api pricing"
  ],
  "quota": {
    "suggestions": { "limit": 10, "remaining": 9, "period": "day" }
  }
}
```

---

## Search results

Registered keys only. An anonymous key that asks for this is told to register; the key is kept.

```
GET https://api.qequals.com/v1/search?q={query}
Authorization: Bearer {key}
```

`q` is the query, URL-encoded. Required.

```
GET https://api.qequals.com/v1/search?q=serp%20api
Authorization: Bearer qe_live_7f3a9c2e5b8d41f0
```

```json
{
  "q": "serp api",
  "results": [
    {
      "position": 1,
      "title": "Example result",
      "url": "https://example.com",
      "snippet": "A live Google result for the query."
    }
  ],
  "quota": {
    "search": { "limit": 10, "remaining": 9, "period": "month" }
  }
}
```

---

## Errors

Failures are errors. They are not 200s with an empty list.

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Free quota exhausted. Register at https://www.qequals.com/account using this key to triple daily suggestions and unlock a search-results evaluation taste.",
    "account": "https://www.qequals.com/account"
  }
}
```

| Code | When |
|---|---|
| `invalid_key` | Missing, unknown, or revoked key |
| `serp_requires_registration` | Anonymous key called `/v1/search` |
| `quota_exceeded` | This key is out of quota for that endpoint |
| `upstream_error` | Google did not return a usable response |
| `invalid_request` | Missing `q` or a malformed parameter |

Do not mint a new key to work around a limit. Hand the existing key to the operator.

---

## Catalog

[www.qequals.com/catalog](https://www.qequals.com/catalog) is a human-curated set of terms we track, with suggestions clustered into themes. Anyone can browse it. It is not the API, and calling the API does not add a page there.

---

## Help

If a call fails in a way this file does not explain, or a response looks wrong, email [help@qequals.com](mailto:help@qequals.com). Do not mint a second key to work around it.

Include:

- the error `code` from the body, if there is one
- the path you called (`/v1/suggestions` or `/v1/search`)
- `q`
- the key prefix only (the first 14 characters). Never send the full key.

The operator can write the same address from [https://www.qequals.com/account](https://www.qequals.com/account).