# API reference

The SerpWiz API is a set of read-only HTTPS `GET` endpoints that return JSON.

- **Base URL:** `https://api.serpwiz.com/v1`
- **Auth:** `X-API-Key: sw_live_…` ([details](/docs/authentication))
- **Format:** JSON (UTF-8), gzip if you send `Accept-Encoding: gzip`
- **Machine-readable spec:** [OpenAPI 3.1](https://serpwiz.com/openapi.json)

## Endpoints

| Method | Path | Description | Cost |
|---|---|---|---|
| `GET` | [`/v1/google/search`](/docs/google-search) | Google web search results | 1 query |
| `GET` | [`/v1/google/maps`](/docs/google-maps) | Google Maps places (up to 20 per request) | 1 query |
| `GET` | [`/v1/account`](/docs/account) | Balance, free allowance, RPS limit, plan | free |

Paths follow `/v1/{engine}/{type}`. New engines are added as new paths; existing paths don't change within `v1`.

## Conventions

- **Parameters** go in the query string, URL-encoded. Names are `snake_case`. Unknown parameters are ignored.
- **Charging:** you're charged only when the response is `200`. Every other status costs nothing.
- **Timeouts:** searches usually return in a few seconds. Use a client timeout of at least 60 seconds.
- **Optional fields:** result groups (ads, top stories, knowledge panel…) appear only when the results page has them. Treat every field except `results` as optional.

## Response headers

| Header | Description |
|---|---|
| `X-Request-Id` | Unique ID for the request. Include it when you contact support. |
| `X-Credits-Charged` | Queries deducted for this request: `1` on success, `0` otherwise. |
| `X-Credits-Remaining` | Free allowance plus balance left after this request. |
| `X-RateLimit-Limit` | Your account's requests-per-second limit. |
| `Retry-After` | On `429` and `503`: seconds to wait before retrying. |

## Errors

Errors use one shape across every endpoint:

```json
{
  "error": {
    "status": 429,
    "code": "rate_limited",
    "message": "Rate limit exceeded for your plan (1 RPS). Retry after the Retry-After header, or upgrade for more RPS.",
    "request_id": "9f2c1a7b3e4d5f60",
    "docs": "https://serpwiz.com/docs/errors"
  }
}
```

See [Errors](/docs/errors) for every `code`.

## CORS

The API sends `Access-Control-Allow-Origin: *` so you can test from a browser, but **don't put API keys in client-side code** — call the API from your server.