# SimilarWeb API Matrix

## Endpoint Mapping

| CLI `--api` value | API name | Default window |
| --- | --- | --- |
| `global-rank` | `SimilarWeb/get_global_rank` | 6 months |
| `visits-total` | `SimilarWeb/get_visits_total` | 6 months |
| `unique-visit` | `SimilarWeb/get_unique_visit` | 6 months |
| `bounce-rate` | `SimilarWeb/get_bounce_rate` | 6 months |
| `traffic-sources-desktop` | `SimilarWeb/get_traffic_sources_desktop` | 3 months |
| `traffic-sources-mobile` | `SimilarWeb/get_traffic_sources_mobile` | 3 months |
| `traffic-by-country` | `SimilarWeb/get_total_traffic_by_country` | 3 months |

## Parameters

Required:
- `domain`
- `api`

Optional shared parameters:
- `start_date` (`YYYY-MM`)
- `end_date` (`YYYY-MM`)
- `main_domain_only` (`true` or omitted)

Optional API-specific parameters:
- `visits-total`, `bounce-rate`, `traffic-sources-desktop`, `traffic-sources-mobile`:
  - `country` (default `world`)
  - `granularity` (default `monthly`)
- `traffic-by-country`:
  - `limit` (default `10`, max `10`)

## Limits

- Maximum lookback: 12 months
- `traffic-by-country`: max 3 months range
- Granularity: monthly
- Latest dependable month: last complete month

## Data Persistence Rule

Write every call to a JSON file immediately to avoid data loss when credits deplete or calls fail mid-run.

## Runtime Adapter Notes

Runtime file:
- `/opt/.manus/.sandbox-runtime/data_api.py`

Provisioning command:
- `/root/.codex/skills/similarweb-analytics/scripts/install_runtime_adapter.sh`

Credential modes:
- Preferred: `SIMILARWEB_API_KEY` for official Similarweb API
- Fallback: `RAPIDAPI_KEY` and optional `RAPIDAPI_SIMILARWEB_HOST` (default `similarweb13.p.rapidapi.com`)