Get started

Use an authorised checkout or wheel and Python 3.10 or later. A SerpAPI key is required for live retrieval. An OpenAI key is optional.

Install

From the repository root:

python -m venv .venv
source .venv/bin/activate
python -m pip install .
shareofsearch --help

Alternatively install the authorised wheel with python -m pip install ./shareofsearch-4.0.0-py3-none-any.whl.

Configure

Save this complete example as config.yaml. It uses the default geography, GB. The pipeline retains the time resolution returned by the provider.

project:
  name: Sports search comparison
  output_dir: ./outputs/sports
queries:
  - query: Nike
    label: Nike
  - query: Adidas
    label: Adidas
  - query: Puma
    label: Puma
parameters:
  date_range: "2024-01-01 2024-12-31"
  smoothing_period: 3
analysis:
  insights:
    enabled: false

Create .env beside config.yaml and set SERPAPI_KEY to your credential. Keep this file private. An existing environment variable takes precedence over .env. Output paths are relative to the working directory, not the YAML directory.

Run

shareofsearch --config config.yaml

From a source checkout, python runme.py --config config.yaml is equivalent. Each invocation requests one comparison series from SerpAPI. Failed requests can be retried. The library has no local response cache.

Inspect outputs/sports/data/metrics.csv, the four PNG charts and outputs/sports/run_metadata.json. With AI disabled, the pipeline writes no narrative or PowerPoint. Use a fresh output directory for each run; optional files from earlier runs are not removed automatically.

Continue

Use the workflow for a reproducible comparison. Read the metric definitions before interpreting the results. For an offline example, use the Python API.