Use the workflow

Define the comparison

Specify the decision, selected queries, geography and date window before retrieval. Use consistent term definitions. Disambiguate names that also refer to unrelated products or concepts. The comparison set defines the denominator of every share. A one-query analysis yields 100% share whenever interest is positive; it cannot measure competitive position.

Fetch compared terms together. Do not combine independently normalised query series as if they shared a scale. A changed comparison set, location or window creates a different analysis.

Run and retain evidence

Use a fixed date range when the same period must be reproduced. Relative windows such as today 12-m move with retrieval time. Choose a new output directory for each run. Keep the YAML, data/provider_timeline.json, run_metadata.json, CSVs, charts and any narration together.

The metadata records the validated settings, package and dependency versions, timeline hash and AI call status. The retained timeline excludes provider request metadata and URLs. Keep your own retrieval date and analyst decision record with the run. Re-fetching the same request can yield different sampled values.

Inspect before interpreting

Check the returned dates, interval spacing, label mapping, small interest values and unusually large changes. The pipeline rejects missing queries within a returned date, duplicate date/query rows, negative or non-finite values and all-zero dates. It does not detect an entire missing date or guarantee that the last provider interval is complete. Resolve these issues before comparing periods.

Review the four charts against full_data.csv. The pie chart uses whole-period average shares even though its retained filename is pie_current.png. Examine raw interest as well as shares; one query can gain share because another falls.

Assess a pattern

Use trend labels and anomaly flags to prioritise checks. They are descriptive rules. Inspect calendar structure, query ambiguity, low-volume suppression and retrieval sensitivity before interpreting a change. This pipeline does not fit a seasonal model or control for events.

A product launch comparison describes before-and-after search patterns. It does not identify campaign incrementality or cannibalisation. A decision about spend requires additional outcome evidence and a credible causal design.

Reproduce calculations

Use the offline Python example with a retained timeline to repeat the calculations. Retained inputs and settings make the deterministic calculation reviewable. LLM wording and fresh provider retrievals are not guaranteed to reproduce. The output reference explains AI status and optional artefacts.