skills/similarweb-analytics/SKILL.md

name, description

name	description
similarweb-analytics	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:

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

Build image and verify runtime:

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

Dry run without consuming API credits:

/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:

/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