Python API

The distribution name is shareofsearch. The existing public import prefix is src; it is retained in this release. Avoid installing another distribution that also owns this generic namespace in the same environment.

Offline calculation

This complete example requires no credentials or provider calls.

from src.processing.transformer import DataTransformer
from src.processing.calculator import MetricsCalculator

response = {"interest_over_time": {"timeline_data": [
    {"date": "2024-01-01", "values": [
        {"query": "A", "extracted_value": 60},
        {"query": "B", "extracted_value": 40}]},
    {"date": "2024-02-01", "values": [
        {"query": "A", "extracted_value": 50},
        {"query": "B", "extracted_value": 50}]},
    {"date": "2024-03-01", "values": [
        {"query": "A", "extracted_value": 40},
        {"query": "B", "extracted_value": 60}]},
]}}
transformer = DataTransformer()
frame = transformer.transform_interest_data(response, {"A": "Brand A", "B": "Brand B"})
calculator = MetricsCalculator()
result = calculator.calculate_all_metrics(frame, smoothing_window=2)
print(calculator.calculate_period_metrics(result))

To reuse a retained provider_timeline.json, load it with json.load and wrap it as {"interest_over_time": timeline}. Use the original query-to-label mapping and the settings in run_metadata.json. calculate_all_metrics does not add value_ma; call transformer.add_moving_average separately if needed.

Live pipeline

This complete example loads the YAML and credentials and can incur provider calls.

from pathlib import Path
from src.pipeline.orchestrator import run_pipeline

results = run_pipeline(config_path=Path("config.yaml"))
print(results["period_metrics"])
print(results["ai_status"])

ShareOfSearchPipeline(config_path).run() provides the same lifecycle. Reusing an instance resets the returned results before each run. Paths passed to these APIs should be pathlib.Path objects. See output contracts.

Configuration and retrieval

fetch_trends(queries, geo, date_range, **kwargs) retrieves one to five queries together. The concrete provider accepts the optional tz request parameter; other extra keywords are not applied. validate_connection() makes a live test request and can consume account quota.

The nested settings classes in src.config.schema are Settings, ProjectConfig, DataSourceConfig, QueryConfig, ParametersConfig, InsightsConfig, TrendThresholdsConfig, AnalysisConfig, VisualizationConfig and OptionsConfig. Their fields appear in the configuration table.

Transformation and metrics

The core calculation expects a complete panel with date, query and value. Temporal methods accept calculated shares and sort by date. These are fixed observations, not uncertainty draws. normalize_to_100 scales against the global maximum; it adds <column>_normalized and is not part of the standard pipeline. See metric definitions for units and boundary cases.

Charts and reports

src.visualization.charts.ChartGenerator(theme="professional", dpi=300) provides generate_line_chart, generate_area_chart, generate_bar_chart, generate_pie_chart and generate_all_charts. Individual methods accept a frame, output path and optional title. Line and area use the time-series frame; bar and pie use period metrics. generate_all_charts(df, metrics_df, output_dir) returns four paths. Create parent directories before calling an individual chart method. Only the professional theme is implemented.

src.reporting.powerpoint.PowerPointGenerator().generate_presentation takes project_name, executive_summary, competitive_insights, metrics_df, chart_paths, market_concentration and output_path as keyword arguments. chart_paths maps bar, line and area to PNG paths. Create a new generator per deck. The deck includes a title, summary, available charts, comparative narrative, limitations and metric table. Long text is truncated to fit the existing layout; use insights.txt for the retained full text. The pipeline catches chart/deck failures and continues with CSV output; inspect logs for partial artefacts.

src.analysis.ai_insights.AIInsightEngine exposes generate_executive_summary, explain_anomalies, generate_competitive_insights and generate_recommendations. The AI page documents inputs, fallbacks and call behaviour.

Utilities and errors

src.utils.logging provides setup_logging and get_logger, with a ColoredFormatter for console messages. src.utils.progress provides print_header, print_summary and create_progress for Rich terminal output. src.cli.main returns process codes 0 on completion, 1 for a handled library error and 130 for interruption. Unexpected exceptions remain visible.

All defined library errors are in src.utils.errors and derive from ShareOfSearchError: ConfigurationError, InvalidConfigError, MissingAPIKeyError, DataError, APIError, RateLimitError, InvalidResponseError, ProcessingError, TransformError, CalculationError, VisualizationError and ReportError. Low-level methods may also raise argument or filesystem errors. The version is exposed as src.__version__.