skills/similarweb-analytics/SKILL.md

---
name: similarweb-analytics
description: Analyze website and domain traffic with SimilarWeb APIs through a Docker sandbox. Use for visits, unique visitors, rank, bounce rate, traffic sources, traffic by country, and domain comparison research.
---

# SimilarWeb Analytics

## Overview

Use this skill to run SimilarWeb analytics in an isolated Docker container and save every API response to JSON immediately.
Use it when the user asks about domain traffic, popularity ranking, engagement quality, channel mix, or country-level traffic split.

## Trigger Cues

Use this skill when the request includes one or more of these cues:
- Domain inputs such as `google.com`, `amazon.com`, `openai.com`
- Traffic words such as `visits`, `unique visitors`, `traffic trend`
- Ranking words such as `global rank`, `website rank`
- Engagement words such as `bounce rate`, `pages per visit`, `visit duration`
- Source words such as `organic`, `paid`, `direct`, `social`, `referrals`
- Geography words such as `top countries`, `country split`, `regional traffic`
- Comparison words such as `compare`, `vs`, `benchmark`

## Workflow

1. Parse user intent into API call inputs:
   - `domain` (required)
   - `api` (required)
   - Optional: `start_date`, `end_date`, `country`, `granularity`, `limit`, `main_domain_only`
2. Build image when needed:
   - Run `scripts/run_in_docker.sh --build -- --self-test`
3. Execute query in Docker sandbox:
   - Run `scripts/run_in_docker.sh -- --api <api> --domain <domain> ...`
4. Persist output on every call:
   - Always pass `--output /data/<file>.json` or let auto filename run in `/data`
   - Never keep API output only in terminal output
5. For comparisons:
   - Execute one call per domain with the same time window
   - Save each domain response as a separate JSON file for reproducible analysis

## Command Entry Points

- Main host wrapper: `scripts/run_in_docker.sh`
- Container entrypoint: `scripts/docker/entrypoint.py`
- Image definition: `scripts/docker/Dockerfile`
- Runtime adapter installer: `scripts/install_runtime_adapter.sh`
- Runtime adapter source: `scripts/runtime/data_api.py`
- Test runner: `scripts/test_docker_workflow.sh`

## Quick Start

Install runtime adapter to expected host path:

```bash
/root/.codex/skills/similarweb-analytics/scripts/install_runtime_adapter.sh
```

Build image and verify runtime:

```bash
/root/.codex/skills/similarweb-analytics/scripts/run_in_docker.sh --build -- --self-test
```

Dry run without consuming API credits:

```bash
/root/.codex/skills/similarweb-analytics/scripts/run_in_docker.sh -- \
  --api visits-total \
  --domain amazon.com \
  --country world \
  --dry-run
```

Real call and save data immediately:

```bash
/root/.codex/skills/similarweb-analytics/scripts/run_in_docker.sh -- \
  --api traffic-by-country \
  --domain amazon.com \
  --start-date 2025-12 \
  --end-date 2026-02 \
  --limit 10 \
  --output /data/amazon-country.json
```

## Supported APIs

- `global-rank` -> `SimilarWeb/get_global_rank`
- `visits-total` -> `SimilarWeb/get_visits_total`
- `unique-visit` -> `SimilarWeb/get_unique_visit`
- `bounce-rate` -> `SimilarWeb/get_bounce_rate`
- `traffic-sources-desktop` -> `SimilarWeb/get_traffic_sources_desktop`
- `traffic-sources-mobile` -> `SimilarWeb/get_traffic_sources_mobile`
- `traffic-by-country` -> `SimilarWeb/get_total_traffic_by_country`

For parameter matrix and defaults, see `references/api-matrix.md`.

## Sandbox Rules

`scripts/run_in_docker.sh` runs with:
- Non-root container user
- Read-only root filesystem
- `tmpfs` only for `/tmp` and `/var/tmp`
- Dropped Linux capabilities (`--cap-drop ALL`)
- `no-new-privileges` enabled
- CPU, memory, and PID limits

Runtime dependency mount:
- Must mount host runtime path into container at `/opt/.manus/.sandbox-runtime`
- Default host path is `/opt/.manus/.sandbox-runtime`
- You can override with `--runtime-dir <path>`
- `data_api.py` must exist in that runtime directory

Credential pass-through:
- `SIMILARWEB_API_KEY` for official Similarweb API mode
- Optional fallback: `RAPIDAPI_KEY` and `RAPIDAPI_SIMILARWEB_HOST`
- Runner auto-forwards these env vars into container when present

## Data Constraints

- Historical data window is at most 12 months
- `traffic-by-country` is limited to at most 3 months
- Latest reliable month is the last complete month
- Default date range:
  - 6 months: `global-rank`, `visits-total`, `unique-visit`, `bounce-rate`
  - 3 months: `traffic-sources-desktop`, `traffic-sources-mobile`, `traffic-by-country`

## Validation Record

Last validated on `2026-03-05`:
- Docker image build succeeded
- Container self-test succeeded
- End-to-end fixture call succeeded and wrote JSON output
- Skill structure validation succeeded with `quick_validate.py`
- Runtime adapter installed to `/opt/.manus/.sandbox-runtime/data_api.py` and imported successfully
- Official mode live call attempted and failed fast with explicit credential error when `SIMILARWEB_API_KEY` is unset
- Live network call attempted via RapidAPI fallback; request reached provider and returned `403 not subscribed` (credential/subscription issue, not runtime failure)

## Troubleshooting

- Error `data_api import failed`:
  - Check that runtime path exists on host and is mounted to `/opt/.manus/.sandbox-runtime`
- Error about date range:
  - Use `YYYY-MM` format and keep range inside API limits
- No output file:
  - Ensure output points to `/data/...` inside container or mounted output directory from host

## Resources

- `scripts/docker/Dockerfile`: container image for sandbox runtime
- `scripts/docker/entrypoint.py`: SimilarWeb API caller inside container
- `scripts/run_in_docker.sh`: host wrapper for build and secure execution
- `scripts/install_runtime_adapter.sh`: install runtime adapter into `/opt/.manus/.sandbox-runtime`
- `scripts/runtime/data_api.py`: `ApiClient` adapter implementation
- `scripts/test_docker_workflow.sh`: reproducible smoke test script
- `references/api-matrix.md`: endpoint and parameter matrix