Tembi Intelligence

Assess checkout-health across the caller's webshop base (read-only) Read-only dashboard: *how healthy is our checkout footprint?* for the caller's own provider (from ``UserContext.delivery_providers`` — not overridable). Country scope: ``country_codes`` must sit inside ``UserContext.access_markets``; omit for all accessible markets. Time scope: ``use_latest_snapshot`` defaults **true** — every number is pinned to the latest available scrape date for each source table (the *right-now* view). Set false to roll up over the trailing ``activity_months`` instead (``activity_months`` is ignored when true). Signals scored (each ``include_*`` defaults true; max score = 3): ``include_brand_visibility`` (1 pt if provider is named), ``include_method_clarity`` (1 pt if ``delivery_method`` is a real value), ``include_time_clarity`` (1 pt if ``delivery_time`` is not null). Disabled signals drop from the score, coverage, and their ``checkout_missing_*`` count. Noise-row toggles — TWO separate scopes: (1) Base dashboard: ``include_unknown_providers`` (default true = keep unknown-provider rows and ``'collect_yourself'`` method rows in base counts; false = strip). ``include_unknown_delivery_method`` (default true = keep ``'unknown'`` method rows; false = strip). ``'multiple_providers'`` always kept. (2) Competitor comparison: ``include_unknown_in_competitors`` (default false = strip unknown-provider / ``'collect_yourself'`` rows from ``competitor_leads`` + ``healthier_competitor_examples``, since neither is a real competitor; true keeps them). Independent of the base flags. T&Cs base: ``total_webshops_in_scope`` = every T&Cs mention of the caller's provider in scope, whether or not we've scraped a checkout for the shop. The T&C-only bucket splits into ``tandc_only_with_checkout`` (we HAVE their checkout, caller isn't at it) and ``tandc_only_no_checkout`` (we've never scraped their checkout — status unverifiable). Score distribution scores every shop in the base; no-checkout shops land in the brand-only bucket. Don't ask the user to confirm settings — pick them from the question and invoke. Answer from the returned ``counts``, ``category_coverage``, ``competitor_leads``, examples, and ``summary_for_llm``; quote the numbers and state ``settings_applied`` so the user can reconfigure. For richer segment slicing chain to ``calculate_delivery_market_share`` / ``assess_competitor_copresence``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "access_denied": true, "category_coverage": [ { "category": "Category", "label": "Label", "webshops_meeting": 1, "webshops_missing": 1 } ], "score_distribution": [ { "score": 1, "webshops": 1 } ], "competitor_leads": [ { "delivery_provider": "Delivery Provider", "webshops": 1, "avg_score_gap": 1.0 } ], "tandc_only_with_checkout_examples": [ { "domain_id": "Domain Id", "domain": "Domain" } ], "tandc_only_no_checkout_examples": [ { "domain_id": "Domain Id", "domain": "Domain" } ], "missing_method_examples": [ { "domain_id": "Domain Id", "domain": "Domain" } ], "missing_time_examples": [ { "domain_id": "Domain Id", "domain": "Domain" } ], "healthier_competitor_examples": [ { "domain_id": "Domain Id", "domain": "Domain" } ], "settings_applied": { "delivery_provider": "Delivery Provider", "country_codes": [ "string" ], "use_latest_snapshot": true, "activity_months": 1, "min_health_gap": 1.0, "top_n_examples": 1, "assessed_categories": [ "string" ], "include_unknown_providers": true, "include_unknown_delivery_method": true, "include_unknown_in_competitors": true }, "summary_for_llm": "Summary For Llm", "timestamp": "2023-01-01T00:00:00Z" } ``` **Output Schema:** ```json { "properties": { "access_denied": { "type": "boolean", "title": "Access Denied", "description": "True when the tool could not run because the caller lacks a delivery provider on their profile, or requested country codes outside their ``UserContext.access_markets``. Fact blocks are omitted; ``summary_for_llm`` explains the denial.", "default": false }, "counts": { "description": "Aggregate dashboard counts. Omitted when ``access_denied=true``." }, "category_coverage": { "items": { "properties": { "category": { "type": "string", "title": "Category", "description": "Signal identifier: 'brand_visibility' | 'method_clarity' | 'time_clarity'." }, "label": { "type": "string", "title": "Label", "description": "Human-readable label for the signal." }, "webshops_meeting": { "type": "integer", "minimum": 0.0, "title": "Webshops Meeting", "description": "Number of caller-provider webshops in the window that satisfy this signal for the caller's provider specifically." }, "webshops_missing": { "type": "integer", "minimum": 0.0, "title": "Webshops Missing", "description": "Number of caller-provider webshops in the window where the signal is absent (e.g. brand shown but method NULL for 'method_clarity')." } }, "type": "object", "required": [ "category", "label", "webshops_meeting", "webshops_missing" ], "title": "HealthCategoryCoverage", "description": "Per-category coverage counts for the caller's provider.\n\nOnly the categories the caller opted into (via the ``include_*`` request\nflags) appear here \u2014 disabled categories are omitted entirely." }, "type": "array", "title": "Category Coverage", "description": "Per-signal coverage counts for the categories the caller opted into. Empty when ``access_denied=true``." }, "score_distribution": { "items": { "properties": { "score": { "type": "integer", "minimum": 1.0, "title": "Score", "description": "Sum of criteria met (1..max_score)." }, "webshops": { "type": "integer", "minimum": 0.0, "title": "Webshops", "description": "Distinct caller-provider shops with this score." } }, "type": "object", "required": [ "score", "webshops" ], "title": "ScoreBucket", "description": "One point of the caller-provider webshop score distribution.\n\n``score`` is the sum of enabled criteria a webshop satisfies (1 up to the\nnumber of enabled ``include_*`` flags \u2014 the zero bucket is dropped since a\n\"provider not observed\" score is not actionable). ``webshops`` is the\ndistinct-domain count of caller-provider shops at checkout with that exact\nscore in the window. Every possible score in ``[1, max_score]`` is present\nso the widget can render a full distribution with zeroed empty buckets." }, "type": "array", "title": "Score Distribution", "description": "Distribution of caller-provider shops at checkout by composite score (sum of enabled criteria met, 1..N \u2014 score 0 is intentionally omitted). Always covers every bucket in ``[1, len(assessed_categories)]`` \u2014 empty buckets carry ``webshops=0`` so the widget can render a stable set of segments." }, "competitor_leads": { "items": { "properties": { "delivery_provider": { "type": "string", "title": "Delivery Provider", "description": "Competitor provider slug (canonical stored form)." }, "webshops": { "type": "integer", "minimum": 0.0, "title": "Webshops", "description": "Webshops where BOTH the caller and this competitor are at checkout, the competitor's checkout-health score is higher than the caller's, and the gap meets ``min_health_gap``." }, "avg_score_gap": { "type": "number", "title": "Avg Score Gap", "description": "Mean (competitor \u2212 caller) score gap across those shops." } }, "type": "object", "required": [ "delivery_provider", "webshops", "avg_score_gap" ], "title": "CompetitorHealthLead", "description": "One competitor slug the caller lags behind, ranked by webshop count." }, "type": "array", "title": "Competitor Leads", "description": "Competitor slugs the caller is losing to, ranked by count of shared webshops where the competitor's checkout-health score is higher than the caller's by at least ``min_health_gap``." }, "tandc_only_with_checkout_examples": { "items": { "properties": { "domain_id": { "type": "string", "title": "Domain Id", "description": "ULID primary key of the webshop." }, "domain": { "type": "string", "title": "Domain", "description": "Canonical host (e.g. 'acme.dk')." }, "country_code": { "title": "Country Code" }, "detail": { "title": "Detail", "description": "Free-form context for the bucket \u2014 e.g. the competitor's slug + score gap for a 'healthier competitor' row." } }, "type": "object", "required": [ "domain_id", "domain" ], "title": "CheckoutHealthExample", "description": "Concrete example of a webshop falling into a specific health bucket." }, "type": "array", "title": "Tandc Only With Checkout Examples", "description": "Concrete webshops mentioning the caller in T&Cs, with a scraped checkout row (any provider) in scope, but where the caller isn't at that checkout. Capped by ``top_n_examples``." }, "tandc_only_no_checkout_examples": { "items": { "properties": { "domain_id": { "type": "string", "title": "Domain Id", "description": "ULID primary key of the webshop." }, "domain": { "type": "string", "title": "Domain", "description": "Canonical host (e.g. 'acme.dk')." }, "country_code": { "title": "Country Code" }, "detail": { "title": "Detail", "description": "Free-form context for the bucket \u2014 e.g. the competitor's slug + score gap for a 'healthier competitor' row." } }, "type": "object", "required": [ "domain_id", "domain" ], "title": "CheckoutHealthExample", "description": "Concrete example of a webshop falling into a specific health bucket." }, "type": "array", "title": "Tandc Only No Checkout Examples", "description": "Concrete webshops mentioning the caller in T&Cs but with no scraped checkout row of any kind in scope \u2014 status at checkout cannot be verified. Capped by ``top_n_examples``." }, "missing_method_examples": { "items": { "properties": { "domain_id": { "type": "string", "title": "Domain Id", "description": "ULID primary key of the webshop." }, "domain": { "type": "string", "title": "Domain", "description": "Canonical host (e.g. 'acme.dk')." }, "country_code": { "title": "Country Code" }, "detail": { "title": "Detail", "description": "Free-form context for the bucket \u2014 e.g. the competitor's slug + score gap for a 'healthier competitor' row." } }, "type": "object", "required": [ "domain_id", "domain" ], "title": "CheckoutHealthExample", "description": "Concrete example of a webshop falling into a specific health bucket." }, "type": "array", "title": "Missing Method Examples", "description": "Concrete webshops showing the caller at checkout with no ``delivery_method`` (capped by ``top_n_examples``). Always empty when ``include_method_clarity`` is disabled on the request." }, "missing_time_examples": { "items": { "properties": { "domain_id": { "type": "string", "title": "Domain Id", "description": "ULID primary key of the webshop." }, "domain": { "type": "string", "title": "Domain", "description": "Canonical host (e.g. 'acme.dk')." }, "country_code": { "title": "Country Code" }, "detail": { "title": "Detail", "description": "Free-form context for the bucket \u2014 e.g. the competitor's slug + score gap for a 'healthier competitor' row." } }, "type": "object", "required": [ "domain_id", "domain" ], "title": "CheckoutHealthExample", "description": "Concrete example of a webshop falling into a specific health bucket." }, "type": "array", "title": "Missing Time Examples", "description": "Concrete webshops showing the caller at checkout with no ``delivery_time`` (capped by ``top_n_examples``). Always empty when ``include_time_clarity`` is disabled on the request." }, "healthier_competitor_examples": { "items": { "properties": { "domain_id": { "type": "string", "title": "Domain Id", "description": "ULID primary key of the webshop." }, "domain": { "type": "string", "title": "Domain", "description": "Canonical host (e.g. 'acme.dk')." }, "country_code": { "title": "Country Code" }, "detail": { "title": "Detail", "description": "Free-form context for the bucket \u2014 e.g. the competitor's slug + score gap for a 'healthier competitor' row." } }, "type": "object", "required": [ "domain_id", "domain" ], "title": "CheckoutHealthExample", "description": "Concrete example of a webshop falling into a specific health bucket." }, "type": "array", "title": "Healthier Competitor Examples", "description": "Concrete webshops where a competitor's checkout-health score exceeds the caller's by ``min_health_gap`` (capped by ``top_n_examples``)." }, "settings_applied": { "description": "Effective settings this response was built with \u2014 echoed for the UI.", "properties": { "delivery_provider": { "type": "string", "title": "Delivery Provider", "description": "Slug of the caller's provider (from ``UserContext.delivery_providers``). This tool never accepts an override for the provider \u2014 the value is always the caller's own." }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Country codes actually used to scope the query \u2014 the intersection of the request and ``UserContext.access_markets``." }, "use_latest_snapshot": { "type": "boolean", "title": "Use Latest Snapshot", "description": "Echo of the request flag \u2014 true means every checkout/T&Cs number was computed as-of the latest scrape date on each source table; false means the trailing ``activity_months`` window was used." }, "activity_months": { "type": "integer", "title": "Activity Months" }, "min_health_gap": { "type": "number", "title": "Min Health Gap" }, "top_n_examples": { "type": "integer", "title": "Top N Examples" }, "assessed_categories": { "items": { "type": "string" }, "type": "array", "title": "Assessed Categories", "description": "Signal identifiers the caller opted into for this run (subset of ``brand_visibility`` / ``method_clarity`` / ``time_clarity``). Drives both the health score and which coverage rows appear in the response." }, "include_unknown_providers": { "type": "boolean", "title": "Include Unknown Providers", "description": "Echo of the request flag (scope: base dashboard). True (default) means unknown-provider rows and ``'collect_yourself'`` method rows were kept in base counts; false strips them." }, "include_unknown_delivery_method": { "type": "boolean", "title": "Include Unknown Delivery Method", "description": "Echo of the request flag (scope: base dashboard). True (default) means ``'unknown'`` method rows were kept in base counts; false strips them." }, "include_unknown_in_competitors": { "type": "boolean", "title": "Include Unknown In Competitors", "description": "Echo of the request flag (scope: competitor comparison only). False (default) means unknown-provider rows and ``'collect_yourself'`` method rows were excluded from ``competitor_leads`` and ``healthier_competitor_examples`` \u2014 leaderboard hygiene, independent of the base setting." } }, "type": "object", "required": [ "delivery_provider", "use_latest_snapshot", "activity_months", "min_health_gap", "top_n_examples", "include_unknown_providers", "include_unknown_delivery_method", "include_unknown_in_competitors" ], "title": "CheckoutHealthSettings" }, "summary_for_llm": { "type": "string", "title": "Summary For Llm", "description": "Pre-rendered narrative the LLM can quote verbatim. Contains the dashboard counts, the top competitor leads, and which criteria were assessed." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Server-side UTC invocation timestamp." } }, "type": "object", "required": [ "settings_applied", "summary_for_llm", "timestamp" ], "title": "AssessCheckoutHealthResponse", "description": "Full response for the *assess_checkout_health* tool.\n\n``access_denied`` short-circuits every fact block when the caller either has\nno delivery provider on their profile or asked for a country code outside\ntheir ``UserContext.access_markets``." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

assess_checkout_health

Which carriers share a delivery provider's webshop checkouts Analyses which competing carriers appear at the *same webshop checkouts* as a target provider — the clearest point-of-sale signal of head-to-head competition. Runs on the checkout-observed population (``webshop_checkout_history``), a tighter subset than the market-share tools' provider history. **Co-presence:** ``copresence_pct`` is the share of the target's webshops that also offer a given competitor; ``reverse_copresence_pct`` is the reverse, so you can see dependency asymmetry. ``penetration_pct`` grounds how big each rival is overall. **Contested base:** the response reports how much of the target's base is *exclusive* (it is the only carrier at checkout) versus *contested* (a rival is also present). **Method-aware:** set ``breakdown_by_method`` to require the competitor to share the same delivery method (rows become per (competitor, method)). **Position:** with ``include_position`` (default on) each row reports the average checkout positions and how often the target is listed above the competitor. Segment filters (``cross_border``, size, growth, main-product-category, ``export_markets``, ``uses_delivery_*``) apply as elsewhere. Returns a pre-rendered ``summary_for_llm``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "country_codes": [ "string" ], "provider_resolved": true, "candidate_providers": [ "string" ], "delivery_provider": "Delivery Provider", "period_months": 1, "data_as_of": "2023-01-01", "breakdown_by_method": true, "include_position": true, "filters_summary": "Filters Summary", "population_shops": 1, "target_shops": 1, "exclusive_shops": 1, "exclusive_pct": 1.0, "contested_shops": 1, "contested_pct": 1.0, "competitors": [ { "rank": 1, "delivery_provider": "Delivery Provider", "competitor_shops": 1, "copresence_shops": 1, "copresence_pct": 1.0, "reverse_copresence_pct": 1.0, "penetration_pct": 1.0 } ], "total_competitors_available": 1, "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Resolved market scope as ISO codes (empty = all markets, no market filter)." }, "provider_resolved": { "type": "boolean", "title": "Provider Resolved", "description": "False when the requested provider has no data in this market. In that case the metric fields are empty/zero and 'candidate_providers' lists real carriers.", "default": true }, "candidate_providers": { "items": { "type": "string" }, "type": "array", "title": "Candidate Providers", "description": "Suggested canonical provider slugs to retry with when provider_resolved is False (closest name matches, else the market's largest carriers)." }, "delivery_provider": { "type": "string", "title": "Delivery Provider", "description": "The target provider analysed." }, "period_months": { "type": "integer", "title": "Period Months" }, "data_as_of": { "type": "string", "format": "date", "title": "Data As Of", "description": "Latest month with checkout data anchoring the window." }, "breakdown_by_method": { "type": "boolean", "title": "Breakdown By Method" }, "include_position": { "type": "boolean", "title": "Include Position" }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable summary of segment filters." }, "population_shops": { "type": "integer", "title": "Population Shops", "description": "Total checkout-observed webshops in the segment (the co-presence universe). Contrast with target_shops to judge coverage; it is also the penetration_pct base." }, "target_shops": { "type": "integer", "title": "Target Shops", "description": "Distinct checkout-observed webshops offering the target provider." }, "exclusive_shops": { "type": "integer", "title": "Exclusive Shops", "description": "Target webshops where it is the ONLY carrier at checkout (uncontested)." }, "exclusive_pct": { "type": "number", "title": "Exclusive Pct", "description": "exclusive_shops as a percentage of target_shops." }, "contested_shops": { "type": "integer", "title": "Contested Shops", "description": "Target webshops that also offer at least one competing carrier." }, "contested_pct": { "type": "number", "title": "Contested Pct", "description": "contested_shops as a percentage of target_shops." }, "competitors": { "items": { "properties": { "rank": { "type": "integer", "title": "Rank", "description": "1-based rank by shared-webshop count with the target." }, "delivery_provider": { "type": "string", "title": "Delivery Provider", "description": "The competing carrier." }, "delivery_method": { "title": "Delivery Method", "description": "The shared delivery method (only when breakdown_by_method is true)." }, "competitor_shops": { "type": "integer", "title": "Competitor Shops", "description": "Distinct checkout-observed webshops offering this competitor." }, "copresence_shops": { "type": "integer", "title": "Copresence Shops", "description": "Webshops offering BOTH the target and this competitor at checkout." }, "copresence_pct": { "type": "number", "title": "Copresence Pct", "description": "Percentage of the target's webshops that ALSO offer this competitor. The headline 'how much of my base does this carrier contest' metric." }, "reverse_copresence_pct": { "type": "number", "title": "Reverse Copresence Pct", "description": "Percentage of THIS competitor's webshops that also offer the target. Contrast with copresence_pct to see dependency asymmetry (who relies on the shared base more)." }, "penetration_pct": { "type": "number", "title": "Penetration Pct", "description": "This competitor's share of all checkout-observed webshops in the segment \u2014 how big the carrier is overall (checkout basis, distinct from the market-share tools)." }, "avg_target_position": { "title": "Avg Target Position", "description": "The target's mean checkout position among the shops it shares with this competitor (lower = nearer the top). Null when include_position is false." }, "avg_competitor_position": { "title": "Avg Competitor Position", "description": "This competitor's mean checkout position on the shared shops." }, "target_ahead_pct": { "title": "Target Ahead Pct", "description": "Percentage of shared shops where the target is listed above this competitor (ties count as half). >50 means the target usually appears first; <50 means it trails." } }, "type": "object", "required": [ "rank", "delivery_provider", "competitor_shops", "copresence_shops", "copresence_pct", "reverse_copresence_pct", "penetration_pct" ], "title": "CompetitorCopresenceRow", "description": "One competitor's checkout co-presence with the target provider." }, "type": "array", "title": "Competitors", "description": "Competitors ranked by shared-webshop count with the target." }, "total_competitors_available": { "type": "integer", "title": "Total Competitors Available", "description": "Co-present entries clearing the min_copresence_shops floor \u2014 distinct competitors, or competitor\u00d7method rows when breakdown_by_method is set (matching the grain of 'competitors'). Counted after the floor; may exceed those returned when > top_n.", "default": 0 }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "delivery_provider", "period_months", "data_as_of", "breakdown_by_method", "include_position", "filters_summary", "population_shops", "target_shops", "exclusive_shops", "exclusive_pct", "contested_shops", "contested_pct", "competitors", "summary_for_llm" ], "title": "CompetitorCopresenceResponse", "description": "Response from the *assess_competitor_copresence* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

assess_competitor_copresence

Rank delivery providers/methods by market share at a point in time Calculates a point-in-time ranking of delivery providers (or delivery methods) by the share of webshops using each, over a trailing window ending at the latest month with data. The snapshot sibling of ``calculate_delivery_market_share_trend`` — same segment filters and baseline, but a ranked table rather than a time series. **Dimension:** rank by 'delivery_provider' (default) or 'delivery_method'. **Market scope:** ``domestic`` (default) ranks webshops' own-market delivery usage. ``cross_border`` ranks what webshops offer consumers in OTHER markets: ``country_code`` scopes the source webshops' market(s) and ``target_country`` the destination(s) — e.g. carriers dominant on the Italy→Spain lane = market_scope='cross_border', country_code='IT', target_country='ES'. Cross-border data is a single current snapshot (``period_months`` is ignored; the response sets ``snapshot_only``); provider/method classification coverage is lower than domestic. (Two segment filters are related but distinct, and apply in either scope: ``cross_border`` — whether a shop exports at all — and ``export_markets`` — declared export destinations, as country names. Neither selects the lane rows analysed; only ``target_country`` does.) **Subject:** pass ``subject`` (or, for providers, rely on the caller's own provider from their Tembi context) to also get that value's rank and share alongside the table. The true number of distinct providers/methods is always returned as ``total_active_values`` (independent of ``top_n``). **Baseline (denominator):** ``denominator_basis`` works exactly as in the trend tool; the response echoes the resolved basis and a plain-English ``denominator_explanation`` — surface it to the user, since it changes what the percentage means. In cross-border scope 'auto'/'checkout' measure against export-checkout-observed webshops in the lane slice and 'market' against all webshops in the segment ('delivery' is domestic-only). **Filters (segment):** ``cross_border``, size, growth, main-product-category, ``export_markets``, and ``uses_delivery_provider`` / ``uses_delivery_method``. Resolve exact values with ``get_queryable_values``. Returns the ranked table plus a ``summary_for_llm``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "dimension": "DeliveryShareDimension", "market_scope": "MarketScope", "country_codes": [ "string" ], "target_countries": [ "string" ], "snapshot_only": true, "period_months": 1, "denominator_basis": "DenominatorBasis", "denominator_explanation": "Denominator Explanation", "filters_summary": "Filters Summary", "excluded_values": [ "string" ], "subject_resolved": true, "candidate_values": [ "string" ], "webshop_count": 1, "market_share_pct": 1.0, "rank": 1, "total_active_values": 1, "total_market_webshops": 1, "rankings": [ { "rank": 1, "series_value": "Series Value", "webshop_count": 1, "market_share_pct": 1.0 } ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "dimension": { "type": "string", "enum": [ "delivery_provider", "delivery_method" ], "title": "DeliveryShareDimension", "description": "What a delivery-share calculation is split by." }, "market_scope": { "description": "Which delivery dataset a scope-aware tool analyses.\n\n* ``domestic`` \u2013 webshops' own-market delivery data (monthly history).\n* ``cross_border`` \u2013 what webshops offer consumers in *other* markets\n (source webshop \u2192 target market pathways). Currently a single snapshot:\n month/window addressing is not yet supported for this scope.\n\nNot to be confused with the *entitlement* market scope (``MarketScopeEcho``,\nISO country codes) or the ``cross_border`` segment filter (a webshop\nattribute: whether the shop exports at all).", "default": "domestic", "type": "string", "enum": [ "domestic", "cross_border" ], "title": "MarketScope" }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Markets analysed (source markets for cross_border)." }, "target_countries": { "items": { "type": "string" }, "type": "array", "title": "Target Countries", "description": "cross_border: target markets analysed (empty = all)." }, "snapshot_only": { "type": "boolean", "title": "Snapshot Only", "description": "True when the scope's data source is a single undated snapshot (cross_border today): data_as_of is null and window addressing is unavailable.", "default": false }, "period_months": { "type": "integer", "title": "Period Months" }, "data_as_of": { "title": "Data As Of", "description": "Latest month with data anchoring the window (null when the data source is a single undated snapshot)." }, "denominator_basis": { "description": "The population a delivery-share percentage is measured *against* (baseline).\n\n* ``delivery`` \u2013 webshops with a known delivery provider\n (``webshop_delivery_provider_history``; derived from checkout + T&C signals).\n* ``checkout`` \u2013 webshops with a known delivery method at checkout\n (``webshop_checkout_history``).\n* ``market`` \u2013 all webshops in the segment (``webshop_history``), i.e. the\n provider/method's penetration of the whole market.\n* ``auto`` \u2013 pick the fact table that owns the pivot dimension\n (provider \u2192 ``delivery``, method \u2192 ``checkout``). This is the default.", "type": "string", "enum": [ "auto", "delivery", "checkout", "market" ], "title": "DenominatorBasis" }, "denominator_explanation": { "type": "string", "title": "Denominator Explanation", "description": "Plain-English statement of what the percentages are measured against." }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable summary of segment filters." }, "excluded_values": { "items": { "type": "string" }, "type": "array", "title": "Excluded Values", "description": "Dimension values excluded from this calculation (echoed so the % is clear)." }, "subject": { "title": "Subject", "description": "The provider/method that was highlighted, if any." }, "subject_resolved": { "type": "boolean", "title": "Subject Resolved", "description": "False when a subject was requested but has no data in this segment; 'candidate_values' then lists real options to retry with.", "default": true }, "candidate_values": { "items": { "type": "string" }, "type": "array", "title": "Candidate Values", "description": "Largest values in this segment to retry with when subject_resolved is False." }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Webshops using the highlighted subject in the window.", "default": 0 }, "market_share_pct": { "type": "number", "title": "Market Share Pct", "description": "The highlighted subject's share of the baseline.", "default": 0.0 }, "rank": { "type": "integer", "title": "Rank", "description": "The highlighted subject's rank (0 if none).", "default": 0 }, "total_active_values": { "type": "integer", "title": "Total Active Values", "description": "True count of distinct providers/methods in the market (pre-top_n)." }, "total_market_webshops": { "type": "integer", "title": "Total Market Webshops", "description": "Distinct webshops in the baseline population for the window." }, "rankings": { "items": { "properties": { "rank": { "type": "integer", "title": "Rank", "description": "1-based rank by webshop count in this market." }, "series_value": { "type": "string", "title": "Series Value", "description": "The provider/method this row describes." }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Distinct webshops actively using this value." }, "market_share_pct": { "type": "number", "title": "Market Share Pct", "description": "Share of the baseline population." } }, "type": "object", "required": [ "rank", "series_value", "webshop_count", "market_share_pct" ], "title": "DeliveryMarketShareRow", "description": "One row in the full provider/method-ranking table." }, "type": "array", "title": "Rankings", "description": "Ranked table of providers/methods by share (up to top_n)." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm", "description": "Pre-rendered human-readable summary of the market position. Suitable for direct inclusion in an LLM answer." } }, "type": "object", "required": [ "dimension", "period_months", "denominator_basis", "denominator_explanation", "filters_summary", "total_active_values", "total_market_webshops", "rankings", "summary_for_llm" ], "title": "DeliveryMarketShareResponse", "description": "Response from the *calculate_delivery_market_share* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

calculate_delivery_market_share

Monthly market-share trend by delivery provider or method, with filters Returns a multi-series monthly market-share trend for the top delivery providers (or delivery methods) in a market. The trend sibling of``calculate_delivery_market_share``. Domestic (own-market) data only — for cross-border/export analysis use the snapshot tool with market_scope='cross_border' (that data has no monthly history yet). **Series:** the top ``top_n`` providers/methods by webshop count in the most recent month, plus any explicit ``series_values``. Set ``dimension`` to 'delivery_provider' (default) or 'delivery_method'. ``total_series_available`` reports how many exist so you can tell when the chart is truncated. **Baseline (denominator):** controlled by ``denominator_basis``. 'auto' (default) uses webshops with delivery data for the chosen dimension; 'market' expresses penetration of all webshops in the segment. The response echoes the resolved basis and a plain-English ``denominator_explanation`` — **surface this to the user**, because it changes what the percentage means. When unsure which baseline the user wants, ask. **Filters (segment):** ``cross_border``, ``size_categories`` / ``size_indication_min`` / ``size_indication_max``, ``growth_categories``, ``product_categories``, ``export_markets``, and ``uses_delivery_provider`` / ``uses_delivery_method`` — all narrow both numerator and denominator. Resolve exact filter and series values with ``get_queryable_values``. Returns one series per provider/method (each a monthly point list), plus a pre-rendered ``summary_for_llm``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "dimension": "DeliveryShareDimension", "country_codes": [ "string" ], "months": 1, "data_as_of": "2023-01-01", "denominator_basis": "DenominatorBasis", "denominator_explanation": "Denominator Explanation", "filters_summary": "Filters Summary", "excluded_values": [ "string" ], "series": [ { "series_value": "Series Value", "points": [ { "month": "Month", "webshop_count": 1, "total_webshops": 1, "market_share_pct": 1.0 } ] } ], "total_series_available": 1, "unresolved_series": [ "string" ], "candidate_values": [ "string" ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "dimension": { "type": "string", "enum": [ "delivery_provider", "delivery_method" ], "title": "DeliveryShareDimension", "description": "What a delivery-share calculation is split by." }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes" }, "months": { "type": "integer", "title": "Months" }, "data_as_of": { "type": "string", "format": "date", "title": "Data As Of", "description": "Latest month with data anchoring the window." }, "denominator_basis": { "description": "The population a delivery-share percentage is measured *against* (baseline).\n\n* ``delivery`` \u2013 webshops with a known delivery provider\n (``webshop_delivery_provider_history``; derived from checkout + T&C signals).\n* ``checkout`` \u2013 webshops with a known delivery method at checkout\n (``webshop_checkout_history``).\n* ``market`` \u2013 all webshops in the segment (``webshop_history``), i.e. the\n provider/method's penetration of the whole market.\n* ``auto`` \u2013 pick the fact table that owns the pivot dimension\n (provider \u2192 ``delivery``, method \u2192 ``checkout``). This is the default.", "type": "string", "enum": [ "auto", "delivery", "checkout", "market" ], "title": "DenominatorBasis" }, "denominator_explanation": { "type": "string", "title": "Denominator Explanation", "description": "Plain-English statement of what the percentages are measured against." }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable summary of segment filters." }, "excluded_values": { "items": { "type": "string" }, "type": "array", "title": "Excluded Values", "description": "Dimension values excluded from this calculation (echoed so the % is clear)." }, "series": { "items": { "properties": { "series_value": { "type": "string", "title": "Series Value", "description": "The provider/method/attribute value for this line." }, "points": { "items": { "properties": { "month": { "type": "string", "title": "Month", "description": "Year-month label, e.g. '2026-03'." }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Webshops in this series for the month (numerator)." }, "total_webshops": { "type": "integer", "title": "Total Webshops", "description": "Webshops in the baseline for the month (denominator)." }, "market_share_pct": { "type": "number", "title": "Market Share Pct", "description": "webshop_count / total_webshops \u00d7 100." } }, "type": "object", "required": [ "month", "webshop_count", "total_webshops", "market_share_pct" ], "title": "ShareDataPoint", "description": "One month's figures in a share series (numerator, denominator and percentage)." }, "type": "array", "title": "Points", "description": "Monthly points, oldest first." } }, "type": "object", "required": [ "series_value", "points" ], "title": "ShareSeries", "description": "One series (a single provider/method/attribute value) across the months." }, "type": "array", "title": "Series", "description": "One entry per included provider/method, each a monthly series." }, "total_series_available": { "type": "integer", "title": "Total Series Available", "description": "Distinct providers/methods in the segment (may exceed the returned series).", "default": 0 }, "unresolved_series": { "items": { "type": "string" }, "type": "array", "title": "Unresolved Series", "description": "Requested 'series_values' that had no data in this segment/market." }, "candidate_values": { "items": { "type": "string" }, "type": "array", "title": "Candidate Values", "description": "Largest values in this segment to retry with when some were unresolved." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "dimension", "months", "data_as_of", "denominator_basis", "denominator_explanation", "filters_summary", "series", "summary_for_llm" ], "title": "DeliveryMarketShareTrendResponse", "description": "Response from the *calculate_delivery_market_share_trend* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

calculate_delivery_market_share_trend

Share of the webshop population by attribute (e.g. % exporting), trend or snapshot Returns what proportion of the webshop population carries a given attribute, as a monthly trend or a current-composition snapshot — the data behind population charts like "cross-border retailers' market share" (proportion of webshops that export). Unlike the delivery tools, this is a **population** metric: the denominator is always all webshops in the segment (``webshop_history``), not the delivery-tracked subset. **Attribute:** ``cross_border`` (default) tracks the single 'exporting' share; 'webshop_size', 'growth', and 'country' split the population into one series per value; 'product_category' splits by each webshop's single main product category (top ``top_n`` ∪ explicit ``attribute_values``). **Snapshot:** set ``latest_only`` to return just the most recent month (current composition) instead of the full trend. **Break down a provider's base:** combine the ``uses_delivery_provider`` (or ``uses_delivery_method``) segment filter with an attribute — e.g. ``uses_delivery_provider='gls'`` + ``attribute='product_category'`` gives the main-category mix of GLS's webshops. **Filters (segment):** ``cross_border``, size, growth, main-product-category, ``export_markets``, and ``uses_delivery_*``. Resolve exact values with ``get_queryable_values``. Returns a pre-rendered ``summary_for_llm``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "attribute": "PopulationAttribute", "country_codes": [ "string" ], "months": 1, "latest_only": true, "data_as_of": "2023-01-01", "filters_summary": "Filters Summary", "series": [ { "series_value": "Series Value", "points": [ { "month": "Month", "webshop_count": 1, "total_webshops": 1, "market_share_pct": 1.0 } ] } ], "total_series_available": 1, "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "attribute": { "type": "string", "enum": [ "cross_border", "webshop_size", "growth", "product_category", "country" ], "title": "PopulationAttribute", "description": "The webshop attribute whose share of the total population is tracked.\n\nThese are *population* metrics: the denominator is always all webshops in the\nsegment, and the series measure what proportion carry each attribute value." }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes" }, "months": { "type": "integer", "title": "Months" }, "latest_only": { "type": "boolean", "title": "Latest Only", "description": "True when the response is a single-month snapshot.", "default": false }, "data_as_of": { "type": "string", "format": "date", "title": "Data As Of", "description": "Latest month with data anchoring the window." }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable summary of segment filters." }, "series": { "items": { "properties": { "series_value": { "type": "string", "title": "Series Value", "description": "The provider/method/attribute value for this line." }, "points": { "items": { "properties": { "month": { "type": "string", "title": "Month", "description": "Year-month label, e.g. '2026-03'." }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Webshops in this series for the month (numerator)." }, "total_webshops": { "type": "integer", "title": "Total Webshops", "description": "Webshops in the baseline for the month (denominator)." }, "market_share_pct": { "type": "number", "title": "Market Share Pct", "description": "webshop_count / total_webshops \u00d7 100." } }, "type": "object", "required": [ "month", "webshop_count", "total_webshops", "market_share_pct" ], "title": "ShareDataPoint", "description": "One month's figures in a share series (numerator, denominator and percentage)." }, "type": "array", "title": "Points", "description": "Monthly points, oldest first." } }, "type": "object", "required": [ "series_value", "points" ], "title": "ShareSeries", "description": "One series (a single provider/method/attribute value) across the months." }, "type": "array", "title": "Series", "description": "One entry per attribute value, each a monthly series of its share of all webshops in the segment. For 'cross_border' a single 'exporting' series; with latest_only, each series carries a single point." }, "total_series_available": { "type": "integer", "title": "Total Series Available", "description": "Distinct attribute values in the segment (may exceed the returned series).", "default": 0 }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "attribute", "months", "data_as_of", "filters_summary", "series", "summary_for_llm" ], "title": "WebshopPopulationShareResponse", "description": "Response from the *calculate_webshop_population_share* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

calculate_webshop_population_share

Checkout positions, breadth and delivery terms (price, time) — snapshot Analyses how delivery providers (or delivery methods) are placed across checkout positions in one monthly snapshot — who holds position 1, how presence spreads across slots, how broad checkouts are, and what delivery terms apply per position: price, free-delivery threshold, and promised delivery time. The snapshot sibling of ``compare_checkout_positions_trend``. **Market scope:** ``domestic`` (default) analyses webshops' own-market checkouts. ``cross_border`` analyses what webshops offer consumers in OTHER markets: ``country_code`` scopes the source webshops' market(s) and ``target_country`` the destination(s) — e.g. Italy→Spain delivery terms = market_scope='cross_border', country_code='IT', target_country='ES', view='delivery_terms_by_position'. Cross-border data is currently a single snapshot (no ``snapshot_month``/``compare_month``); a ``target_country`` stratification is available for pathway cross-tabs. (Two segment filters are related but distinct, and apply in either scope: ``cross_border`` — whether a shop exports at all — and ``export_markets`` — declared export destinations, as country names. Neither selects the lane rows analysed; only ``target_country`` does.) **Views** (pick one per call): ``share_by_position`` – % split of providers/methods within each position (each position sums to 100%); ``position_distribution`` – per provider/method spread across positions plus best-position stats (median/avg, count at #1); ``provider_breadth`` – webshops bucketed by how many distinct real providers their checkout offers (1..5+); ``delivery_terms_by_position`` – delivery price, free-delivery-threshold and delivery-time stats per method × position, each with coverage percentages (delivery time is partially published — quote the coverage). **Time:** ``snapshot_month`` ('YYYY-MM', default latest snapshot) and optional ``compare_month`` add per-row deltas (e.g. '2026-01' for 'since the start of the year'). The response echoes the exact snapshot dates used. **Slicing:** ``positions`` (default 1–6), ``delivery_methods``, provider-count band, ``stratify_by`` (country, webshop_size, growth, product_category) for cross-tabs, plus the shared segment filters. Webshops count once per provider/method at their best position. Resolve exact filter values with ``get_queryable_values``. **Subject grounding:** ``subject`` defaults to the caller's own provider; ``subject_context`` reports its rank among providers above a materiality floor, the leader, and the immediate neighbours with webshop gaps — and those neighbours are always included in the rows regardless of ``top_n``. Returns rows for the chosen view plus a ``summary_for_llm``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "snapshot_resolved": true, "candidate_months": [ "string" ], "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "view": "CheckoutPositionsView", "dimension": "CheckoutDimension", "market_scope": "MarketScope", "country_codes": [ "string" ], "target_countries": [ "string" ], "snapshot_only": true, "positions": [ 1 ], "filters_summary": "Filters Summary", "excluded_providers": [ "string" ], "subject_resolved": true, "candidate_values": [ "string" ], "total_values_available": 1, "position_rows": [ { "series_value": "Series Value", "position": 1, "webshop_count": 1, "position_total": 1, "value_total": 1, "share_of_position_pct": 1.0, "share_of_value_pct": 1.0 } ], "value_stats": [ { "series_value": "Series Value", "webshop_count": 1, "first_position_count": 1, "avg_best_position": 1.0, "median_best_position": 1.0, "p25_best_position": 1.0, "p75_best_position": 1.0 } ], "breadth_rows": [ { "providers_in_checkout": 1, "webshop_count": 1, "share_pct": 1.0 } ], "terms_rows": [ { "delivery_method": "Delivery Method", "position": 1, "webshop_count": 1, "price_coverage_pct": 1.0, "delivery_time_coverage_pct": 1.0 } ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "snapshot_date": { "title": "Snapshot Date", "description": "Exact snapshot date the snapshot resolved to (null when unresolved or when the data source is a single undated snapshot)." }, "compare_date": { "title": "Compare Date", "description": "Exact snapshot date the comparison resolved to (null when no comparison)." }, "snapshot_resolved": { "type": "boolean", "title": "Snapshot Resolved", "description": "False when a requested month has no snapshot (or time addressing is unsupported for the scope). No data was queried in that case; 'candidate_months' lists months to retry with.", "default": true }, "candidate_months": { "items": { "type": "string" }, "type": "array", "title": "Candidate Months", "description": "Months ('YYYY-MM') with snapshots, newest first \u2014 retry options." }, "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "view": { "type": "string", "enum": [ "share_by_position", "position_distribution", "provider_breadth", "delivery_terms_by_position" ], "title": "CheckoutPositionsView", "description": "Which calculation the snapshot tool runs.\n\n* ``share_by_position`` \u2013 % split of providers/methods **within each\n position** (each position's shares sum to 100).\n* ``position_distribution`` \u2013 per provider/method: spread **across\n positions** plus best-position stats (median/avg, share at #1).\n* ``provider_breadth`` \u2013 webshops bucketed by how many distinct real\n providers their checkout offers (1..5+).\n* ``delivery_terms_by_position`` \u2013 delivery price, free-delivery-threshold\n and delivery-time stats per method \u00d7 position (per-metric coverage)." }, "dimension": { "type": "string", "enum": [ "delivery_provider", "delivery_method" ], "title": "CheckoutDimension", "description": "What the position analysis is split by." }, "market_scope": { "description": "Which delivery dataset a scope-aware tool analyses.\n\n* ``domestic`` \u2013 webshops' own-market delivery data (monthly history).\n* ``cross_border`` \u2013 what webshops offer consumers in *other* markets\n (source webshop \u2192 target market pathways). Currently a single snapshot:\n month/window addressing is not yet supported for this scope.\n\nNot to be confused with the *entitlement* market scope (``MarketScopeEcho``,\nISO country codes) or the ``cross_border`` segment filter (a webshop\nattribute: whether the shop exports at all).", "default": "domestic", "type": "string", "enum": [ "domestic", "cross_border" ], "title": "MarketScope" }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Markets analysed (source markets for cross_border)." }, "target_countries": { "items": { "type": "string" }, "type": "array", "title": "Target Countries", "description": "cross_border: target markets analysed (empty = all)." }, "snapshot_only": { "type": "boolean", "title": "Snapshot Only", "description": "True when the scope's data source is a single undated snapshot (cross_border today): snapshot_date is null and month addressing is unavailable.", "default": false }, "positions": { "items": { "type": "integer" }, "type": "array", "title": "Positions", "description": "Positions included in the analysis." }, "stratify_by": { "description": "Stratification applied to the rows (echo)." }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable one-liner of the active filters.", "default": "" }, "excluded_providers": { "items": { "type": "string" }, "type": "array", "title": "Excluded Providers", "description": "Non-carrier provider slugs excluded throughout." }, "subject": { "title": "Subject", "description": "Resolved subject (lower-cased): the request's, or the caller's own provider." }, "subject_resolved": { "type": "boolean", "title": "Subject Resolved", "description": "False when the requested subject has no data here; candidate_values lists alternatives.", "default": true }, "subject_context": { "description": "League-table standing of the subject (share/distribution views): rank among material providers/methods, plus the leader and the immediate neighbours with gaps. Ground provider-perspective answers in this." }, "candidate_values": { "items": { "type": "string" }, "type": "array", "title": "Candidate Values", "description": "Largest values in this segment \u2014 retry options when the subject is unresolved." }, "total_values_available": { "type": "integer", "title": "Total Values Available", "description": "Distinct providers/methods in the segment before top_n slicing.", "default": 0 }, "position_rows": { "items": { "properties": { "stratum": { "title": "Stratum", "description": "Stratification bucket (null when not stratified)." }, "series_value": { "type": "string", "title": "Series Value", "description": "Provider or method (canonical stored form)." }, "position": { "type": "integer", "title": "Position" }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Distinct webshops with this value at this position." }, "position_total": { "type": "integer", "title": "Position Total", "description": "All-values webshop total at this position (denominator of share_of_position_pct)." }, "value_total": { "type": "integer", "title": "Value Total", "description": "This value's webshop total across positions (denominator of share_of_value_pct)." }, "share_of_position_pct": { "type": "number", "title": "Share Of Position Pct", "description": "This value's share of position_total (%)." }, "share_of_value_pct": { "type": "number", "title": "Share Of Value Pct", "description": "This position's share of the value's own total (%)." }, "delta_webshop_count": { "title": "Delta Webshop Count", "description": "Change vs compare_month (snapshot minus comparison); null without comparison." }, "delta_share_of_position_pct": { "title": "Delta Share Of Position Pct" } }, "type": "object", "required": [ "series_value", "position", "webshop_count", "position_total", "value_total", "share_of_position_pct", "share_of_value_pct" ], "title": "PositionShareRow", "description": "One (value \u00d7 position) cell of the share/distribution views.\n\n``delta_*`` fields are snapshot minus compare_month (null without a comparison)." }, "type": "array", "title": "Position Rows", "description": "share_by_position and position_distribution views." }, "value_stats": { "items": { "properties": { "stratum": { "title": "Stratum" }, "series_value": { "type": "string", "title": "Series Value" }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Distinct webshops where the value appears at checkout." }, "first_position_count": { "type": "integer", "title": "First Position Count", "description": "Webshops where the value holds position 1." }, "avg_best_position": { "type": "number", "title": "Avg Best Position" }, "median_best_position": { "type": "number", "title": "Median Best Position" }, "p25_best_position": { "type": "number", "title": "P25 Best Position" }, "p75_best_position": { "type": "number", "title": "P75 Best Position" }, "delta_webshop_count": { "title": "Delta Webshop Count" }, "delta_first_position_count": { "title": "Delta First Position Count" }, "delta_avg_best_position": { "title": "Delta Avg Best Position" } }, "type": "object", "required": [ "series_value", "webshop_count", "first_position_count", "avg_best_position", "median_best_position", "p25_best_position", "p75_best_position" ], "title": "PositionStatsRow", "description": "Best-position statistics for one provider/method (position_distribution view).\n\n``delta_*`` fields are snapshot minus compare_month (null without a comparison)." }, "type": "array", "title": "Value Stats", "description": "position_distribution view only." }, "breadth_rows": { "items": { "properties": { "stratum": { "title": "Stratum" }, "providers_in_checkout": { "type": "integer", "title": "Providers In Checkout", "description": "Distinct real providers in the checkout (5 = '5 or more')." }, "webshop_count": { "type": "integer", "title": "Webshop Count" }, "share_pct": { "type": "number", "title": "Share Pct", "description": "Share of the stratum's webshops in this bucket." }, "delta_webshop_count": { "title": "Delta Webshop Count" } }, "type": "object", "required": [ "providers_in_checkout", "webshop_count", "share_pct" ], "title": "ProviderBreadthRow", "description": "One breadth bucket: webshops offering N distinct real providers." }, "type": "array", "title": "Breadth Rows", "description": "provider_breadth view only." }, "terms_rows": { "items": { "properties": { "stratum": { "title": "Stratum" }, "delivery_method": { "type": "string", "title": "Delivery Method" }, "position": { "type": "integer", "title": "Position" }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Distinct webshops with offers in this cell." }, "avg_price_eur": { "title": "Avg Price Eur" }, "median_price_eur": { "title": "Median Price Eur" }, "p25_price_eur": { "title": "P25 Price Eur" }, "p75_price_eur": { "title": "P75 Price Eur" }, "price_coverage_pct": { "type": "number", "title": "Price Coverage Pct", "description": "Share of the cell's offers with a published price." }, "free_delivery_pct": { "title": "Free Delivery Pct", "description": "Share of priced offers at \u20ac0 (null when nothing is priced)." }, "median_free_threshold_eur": { "title": "Median Free Threshold Eur", "description": "Median free-delivery spend threshold where published." }, "median_delivery_time_min_days": { "title": "Median Delivery Time Min Days", "description": "Median of the promised delivery-window start (days)." }, "median_delivery_time_max_days": { "title": "Median Delivery Time Max Days", "description": "Median of the promised delivery-window end (days)." }, "delivery_time_coverage_pct": { "type": "number", "title": "Delivery Time Coverage Pct", "description": "Share of the cell's offers with a published delivery time." }, "delta_median_price_eur": { "title": "Delta Median Price Eur" } }, "type": "object", "required": [ "delivery_method", "position", "webshop_count", "price_coverage_pct", "delivery_time_coverage_pct" ], "title": "DeliveryTermsRow", "description": "Delivery-terms statistics for one method \u00d7 position cell.\n\nTerms columns have partial coverage in the data, so every metric is\ncomputed over its published subset and paired with a coverage percentage \u2014\nquote the coverage when generalising from a metric." }, "type": "array", "title": "Terms Rows", "description": "delivery_terms_by_position view only." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm", "description": "Pre-rendered narrative of the result, with absolute counts \u2014 quote from this.", "default": "" } }, "type": "object", "required": [ "view", "dimension" ], "title": "CompareCheckoutPositionsResponse", "description": "Response from *compare_checkout_positions*. Only the requested view's rows are populated." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

compare_checkout_positions

Monthly checkout position trend by provider or method Tracks checkout positions month by month: per provider (or delivery method), the number of webshops where it appears at checkout, how many list it first, and its average/median best position. Domestic checkout data only. The trend sibling of ``compare_checkout_positions`` — same filters and dedupe convention, monthly series instead of one snapshot. Series are the top ``top_n`` providers/methods by latest-month presence, plus the caller's own provider (always included as a series and summarised — ``subject``), plus any ``series_values`` (resolve exact values with ``get_queryable_values``). For a head-to-head against your immediate rivals, take ``ahead``/``behind`` from ``compare_checkout_positions``' ``subject_context`` and pass them as ``series_values``. Window is the trailing ``months`` (default 12) anchored on the latest snapshot. ``positions``, ``delivery_methods``, provider-count band, and the shared segment filters apply. Returns per-series monthly points with start-to-end changes and a ``summary_for_llm``. For month-vs-month position share deltas, prefer the snapshot tool with ``compare_month``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "dimension": "CheckoutDimension", "country_codes": [ "string" ], "months": 1, "positions": [ 1 ], "filters_summary": "Filters Summary", "excluded_providers": [ "string" ], "subject_resolved": true, "series": [ { "series_value": "Series Value", "points": [ { "month": "Month", "webshop_count": 1, "first_position_count": 1, "avg_best_position": 1.0, "median_best_position": 1.0 } ], "change_webshop_count": 1, "change_first_position_count": 1, "change_avg_best_position": 1.0 } ], "total_series_available": 1, "unresolved_series": [ "string" ], "candidate_values": [ "string" ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "dimension": { "type": "string", "enum": [ "delivery_provider", "delivery_method" ], "title": "CheckoutDimension", "description": "What the position analysis is split by." }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes" }, "months": { "type": "integer", "title": "Months", "default": 12 }, "data_as_of": { "title": "Data As Of", "description": "Latest month present ('yyyy-MM')." }, "positions": { "items": { "type": "integer" }, "type": "array", "title": "Positions" }, "filters_summary": { "type": "string", "title": "Filters Summary", "default": "" }, "excluded_providers": { "items": { "type": "string" }, "type": "array", "title": "Excluded Providers" }, "subject": { "title": "Subject", "description": "Resolved subject (lower-cased): the request's, or the caller's own provider." }, "subject_resolved": { "type": "boolean", "title": "Subject Resolved", "description": "False when the subject has no checkout data in this segment; candidate_values lists alternatives.", "default": true }, "series": { "items": { "properties": { "series_value": { "type": "string", "title": "Series Value" }, "points": { "items": { "properties": { "month": { "type": "string", "title": "Month", "description": "Month label 'yyyy-MM'." }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Distinct webshops where the value appears at checkout." }, "first_position_count": { "type": "integer", "title": "First Position Count" }, "avg_best_position": { "type": "number", "title": "Avg Best Position" }, "median_best_position": { "type": "number", "title": "Median Best Position" } }, "type": "object", "required": [ "month", "webshop_count", "first_position_count", "avg_best_position", "median_best_position" ], "title": "CheckoutPositionsTrendPoint", "description": "One month of a positions trend series." }, "type": "array", "title": "Points" }, "change_webshop_count": { "type": "integer", "title": "Change Webshop Count", "description": "Last minus first point." }, "change_first_position_count": { "type": "integer", "title": "Change First Position Count" }, "change_avg_best_position": { "type": "number", "title": "Change Avg Best Position" } }, "type": "object", "required": [ "series_value", "points", "change_webshop_count", "change_first_position_count", "change_avg_best_position" ], "title": "CheckoutPositionsTrendSeries", "description": "Monthly positions series for one provider/method.\n\n``change_*`` fields are the last point minus the first (the window's net move)." }, "type": "array", "title": "Series" }, "total_series_available": { "type": "integer", "title": "Total Series Available", "default": 0 }, "unresolved_series": { "items": { "type": "string" }, "type": "array", "title": "Unresolved Series", "description": "Requested series_values with no data in this segment." }, "candidate_values": { "items": { "type": "string" }, "type": "array", "title": "Candidate Values", "description": "Largest values in this segment \u2014 retry options for unresolved series/subject." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm", "description": "Pre-rendered narrative of the result, with absolute counts \u2014 quote from this.", "default": "" } }, "type": "object", "required": [ "dimension" ], "title": "CompareCheckoutPositionsTrendResponse", "description": "Response from *compare_checkout_positions_trend*." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

compare_checkout_positions_trend

Compare delivery prices by provider and method at a point in time Compares the delivery prices webshops display at checkout, by delivery provider and method, over a trailing window ending at the latest month with data. The point-in-time sibling of ``compare_delivery_pricing_trend``. **Per-webshop method:** each shop contributes its latest in-band price (weighted once), matching the dashboards — not a raw row average. Returns a robust distribution per group: mean, **median**, p25/p75, min/max, and **free-delivery %**. **Market scope:** ``domestic`` (default) prices webshops' own-market checkouts. ``cross_border`` prices what webshops charge consumers in OTHER markets: ``country_code`` scopes the source webshops' market(s) and ``target_country`` the destination(s) — e.g. Italy→Spain checkout prices = market_scope='cross_border', country_code='IT', target_country='ES'. A ``target_country`` stratification gives per-lane cross-tabs. Cross-border data is a single current snapshot (``period_months`` is ignored; the response sets ``snapshot_only``); classification and free-threshold coverage are lower than domestic, and lanes are thinner — consider lowering ``min_webshops`` for narrow lanes. (Two segment filters are related but distinct, and apply in either scope: ``cross_border`` — whether a shop exports at all — and ``export_markets`` — declared export destinations, as country names. Neither selects the lane rows analysed; only ``target_country`` does.) **Grain:** price is method-specific, so groups are ``(provider, delivery_method)`` by default. Set ``breakdown_by_method=false`` for a method-blind provider average; narrow with ``delivery_methods``; add a ``stratify_by`` segment (size, country, cross_border, …) for deeper comparison. **Subject:** pass ``subject`` (or rely on the caller's own provider) to get its prices vs the market median. **Outliers:** prices above ``max_price_eur`` (default 20) are dropped; groups below ``min_webshops`` are excluded. Segment filters (``cross_border``, size, growth, main-product-category, ``export_markets``, ``uses_delivery_*``) apply as elsewhere. Returns a ``summary_for_llm``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "market_scope": "MarketScope", "country_codes": [ "string" ], "target_countries": [ "string" ], "snapshot_only": true, "period_months": 1, "breakdown_by_method": true, "price_band": "Price Band", "min_webshops": 1, "filters_summary": "Filters Summary", "subject_resolved": true, "candidate_values": [ "string" ], "rows": [ { "delivery_provider": "Delivery Provider", "avg_price_eur": 1.0, "median_price_eur": 1.0, "p25_price_eur": 1.0, "p75_price_eur": 1.0, "min_price_eur": 1.0, "max_price_eur": 1.0, "free_delivery_pct": 1.0, "free_threshold_pct": 1.0, "webshop_count": 1 } ], "total_groups_available": 1, "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "market_scope": { "description": "Which delivery dataset a scope-aware tool analyses.\n\n* ``domestic`` \u2013 webshops' own-market delivery data (monthly history).\n* ``cross_border`` \u2013 what webshops offer consumers in *other* markets\n (source webshop \u2192 target market pathways). Currently a single snapshot:\n month/window addressing is not yet supported for this scope.\n\nNot to be confused with the *entitlement* market scope (``MarketScopeEcho``,\nISO country codes) or the ``cross_border`` segment filter (a webshop\nattribute: whether the shop exports at all).", "default": "domestic", "type": "string", "enum": [ "domestic", "cross_border" ], "title": "MarketScope" }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Markets analysed (source markets for cross_border)." }, "target_countries": { "items": { "type": "string" }, "type": "array", "title": "Target Countries", "description": "cross_border: target markets analysed (empty = all)." }, "snapshot_only": { "type": "boolean", "title": "Snapshot Only", "description": "True when the scope's data source is a single undated snapshot (cross_border today): data_as_of is null and window addressing is unavailable.", "default": false }, "period_months": { "type": "integer", "title": "Period Months" }, "data_as_of": { "title": "Data As Of", "description": "Latest month with data anchoring the window (null when the data source is a single undated snapshot)." }, "breakdown_by_method": { "type": "boolean", "title": "Breakdown By Method" }, "stratify_by": {}, "price_band": { "type": "string", "title": "Price Band", "description": "The applied outlier price band, e.g. '\u20ac0\u2013\u20ac20'." }, "min_webshops": { "type": "integer", "title": "Min Webshops" }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable summary of segment filters." }, "subject": { "title": "Subject", "description": "The highlighted provider, if any." }, "subject_resolved": { "type": "boolean", "title": "Subject Resolved", "description": "False when a subject was requested but has no eligible pricing data.", "default": true }, "candidate_values": { "items": { "type": "string" }, "type": "array", "title": "Candidate Values", "description": "Providers with eligible pricing data to retry with when unresolved." }, "rows": { "items": { "properties": { "delivery_provider": { "type": "string", "title": "Delivery Provider" }, "delivery_method": { "title": "Delivery Method", "description": "Null when breakdown_by_method is false (method-blind average)." }, "stratum": { "title": "Stratum", "description": "The stratify_by value, when stratified." }, "checkout_position": { "title": "Checkout Position", "description": "Checkout position bucket (1/2/3/4+) when by_checkout_position is set." }, "avg_price_eur": { "type": "number", "title": "Avg Price Eur", "description": "Per-webshop mean delivery price (EUR)." }, "median_price_eur": { "type": "number", "title": "Median Price Eur", "description": "Per-webshop median \u2014 the robust headline." }, "p25_price_eur": { "type": "number", "title": "P25 Price Eur" }, "p75_price_eur": { "type": "number", "title": "P75 Price Eur" }, "min_price_eur": { "type": "number", "title": "Min Price Eur" }, "max_price_eur": { "type": "number", "title": "Max Price Eur" }, "free_delivery_pct": { "type": "number", "title": "Free Delivery Pct", "description": "Share of webshops in this group offering free delivery (price \u20ac0)." }, "free_threshold_pct": { "type": "number", "title": "Free Threshold Pct", "description": "Share of webshops publishing a free-delivery spend threshold (free above \u20acX)." }, "median_free_threshold_eur": { "title": "Median Free Threshold Eur", "description": "Median free-delivery spend threshold among shops that publish one (EUR)." }, "webshop_count": { "type": "integer", "title": "Webshop Count", "description": "Distinct webshops contributing to this group." } }, "type": "object", "required": [ "delivery_provider", "avg_price_eur", "median_price_eur", "p25_price_eur", "p75_price_eur", "min_price_eur", "max_price_eur", "free_delivery_pct", "free_threshold_pct", "webshop_count" ], "title": "DeliveryPricingRow", "description": "Per-webshop price distribution for one (provider, method[, stratum]) group." }, "type": "array", "title": "Rows", "description": "Per-group price distributions, ordered cheapest average first." }, "total_groups_available": { "type": "integer", "title": "Total Groups Available", "description": "Eligible groups in the segment (may exceed the returned rows).", "default": 0 }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "period_months", "breakdown_by_method", "price_band", "min_webshops", "filters_summary", "rows", "summary_for_llm" ], "title": "DeliveryPricingResponse", "description": "Response from the *compare_delivery_pricing* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

compare_delivery_pricing

Monthly delivery-price trend by provider and method Returns a monthly per-webshop average delivery-price series per provider (or provider × delivery method) — the data behind the Market Intelligence 'Average delivery price' line charts. The trend sibling of ``compare_delivery_pricing``. Domestic (own-market) prices only — for cross-border/export prices use the snapshot tool with market_scope='cross_border' (that data has no monthly history yet). Each shop contributes its latest in-band price per month (weighted once). Series are the top ``top_n`` providers by latest-month webshop count plus any ``series_values``; ``breakdown_by_method`` and ``delivery_methods`` control the method split (narrow the methods to keep the number of lines readable). Outlier band (``max_price_eur`` default 20) and the shared segment filters (``cross_border``, size, growth, main-product-category, ``export_markets``, ``uses_delivery_*``) apply. Returns a ``summary_for_llm``. For distributions / subject-vs-market comparison, use ``compare_delivery_pricing``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "country_codes": [ "string" ], "months": 1, "data_as_of": "2023-01-01", "breakdown_by_method": true, "price_band": "Price Band", "filters_summary": "Filters Summary", "series": [ { "delivery_provider": "Delivery Provider", "points": [ { "month": "Month", "avg_price_eur": 1.0, "webshop_count": 1 } ], "start_price_eur": 1.0, "end_price_eur": 1.0, "change_eur": 1.0, "change_pct": 1.0 } ], "total_series_available": 1, "unresolved_series": [ "string" ], "candidate_values": [ "string" ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes" }, "months": { "type": "integer", "title": "Months" }, "data_as_of": { "type": "string", "format": "date", "title": "Data As Of", "description": "Latest month with data anchoring the window." }, "breakdown_by_method": { "type": "boolean", "title": "Breakdown By Method" }, "price_band": { "type": "string", "title": "Price Band", "description": "The applied outlier price band, e.g. '\u20ac0\u2013\u20ac20'." }, "filters_summary": { "type": "string", "title": "Filters Summary", "description": "Human-readable summary of segment filters." }, "series": { "items": { "properties": { "delivery_provider": { "type": "string", "title": "Delivery Provider" }, "delivery_method": { "title": "Delivery Method", "description": "Null when breakdown_by_method is false." }, "points": { "items": { "properties": { "month": { "type": "string", "title": "Month", "description": "Year-month label, e.g. '2026-03'." }, "avg_price_eur": { "type": "number", "title": "Avg Price Eur" }, "webshop_count": { "type": "integer", "title": "Webshop Count" } }, "type": "object", "required": [ "month", "avg_price_eur", "webshop_count" ], "title": "PricingTrendPoint", "description": "One monthly point: the per-webshop average price for a series." }, "type": "array", "title": "Points", "description": "Monthly points, oldest first." }, "start_price_eur": { "type": "number", "title": "Start Price Eur", "description": "Average price in the earliest month shown." }, "end_price_eur": { "type": "number", "title": "End Price Eur", "description": "Average price in the latest month shown." }, "change_eur": { "type": "number", "title": "Change Eur", "description": "end_price_eur \u2212 start_price_eur." }, "change_pct": { "type": "number", "title": "Change Pct", "description": "Percentage change from start to end (0 if start is 0)." } }, "type": "object", "required": [ "delivery_provider", "points", "start_price_eur", "end_price_eur", "change_eur", "change_pct" ], "title": "PricingTrendSeries", "description": "One series \u2014 a provider, or a (provider, method) pair \u2014 across the months." }, "type": "array", "title": "Series", "description": "One monthly average-price series per provider (or provider\u00d7method)." }, "total_series_available": { "type": "integer", "title": "Total Series Available", "description": "Distinct series in the segment (may exceed those returned).", "default": 0 }, "unresolved_series": { "items": { "type": "string" }, "type": "array", "title": "Unresolved Series", "description": "Requested providers with no priced data in this segment." }, "candidate_values": { "items": { "type": "string" }, "type": "array", "title": "Candidate Values", "description": "Providers with priced data to retry with when some were unresolved." }, "summary_for_llm": { "type": "string", "title": "Summary For Llm" } }, "type": "object", "required": [ "months", "data_as_of", "breakdown_by_method", "price_band", "filters_summary", "series", "summary_for_llm" ], "title": "DeliveryPricingTrendResponse", "description": "Response from the *compare_delivery_pricing_trend* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

compare_delivery_pricing_trend

List or search the queryable values for an analytics dimension Returns the real, queryable values that exist in the analytics data for a dimension, so you can resolve a user's free-text reference to the exact token the other tools expect — always prefer this over guessing a value. **Two modes, selected by dimension:** - Enumerate — `delivery_provider`, `delivery_method`, `country`, `platform`, `product_category`, `webshop_size`, `growth`, `export_market` (country names of declared export destinations — the values the `export_markets` segment filter takes), `target_country` (ISO codes of cross-border checkout destinations — the values the market-intelligence tools' `target_country` parameter takes), `product_dimension`: returns the full (or top-N) set of values, ranked by webshop count. - Search — `brand`, `company`, `domain` (high cardinality): a `query` term is **required**; returns ranked name matches. **Each value** carries a `canonical_value` to pass verbatim to other tools, a `label`, and—where meaningful—a `webshop_count` for materiality. Id-keyed dimensions (`product_category`, `product_dimension`, `brand`, `company`, `domain`) also return a `value_id`. Ordinal dimensions (`webshop_size`, `growth`, `product_dimension`) include an `order` (low→high), and `webshop_size` a `score_range`, so comparative phrasing such as 'above-average size' resolves to a contiguous set. Non-selectable placeholders (e.g. 'unknown') are flagged with `is_sentinel: true`. **Scope:** market-specific dimensions (`delivery_provider`, `delivery_method`, `platform`, `product_category`, `webshop_size`, `growth`, `export_market`, `target_country`) default to the caller's home market and can be overridden with a single `country_code`; the `country` dimension lists all available markets. Enumerated values for dated dimensions reflect recent activity (the current market), not all history. **Filtering / example:** for enumerate dimensions, pass `query` to narrow by substring (e.g. 'postn' → 'postnord', 'postnl'). To answer a question about 'Royal Mail', call with dimension='delivery_provider' to find 'royal_mail', then pass that `canonical_value` to the market-intelligence tools. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "entitled_markets": [ "string" ], "unauthorized_markets": [ "string" ], "markets_resolved": true, "dimension": "DimensionName", "mode": "Mode", "country_codes": [ "string" ], "total_values": 1, "returned": 1, "values": [ { "canonical_value": "Canonical Value", "label": "Label", "is_sentinel": true } ], "summary_for_llm": "Summary For Llm" } ``` **Output Schema:** ```json { "properties": { "entitled_markets": { "items": { "type": "string" }, "type": "array", "title": "Entitled Markets", "description": "Markets the caller's account is entitled to query (empty = no restriction)." }, "unauthorized_markets": { "items": { "type": "string" }, "type": "array", "title": "Unauthorized Markets", "description": "Requested markets dropped because they are outside the caller's entitlement." }, "markets_resolved": { "type": "boolean", "title": "Markets Resolved", "description": "False when every explicitly requested market is outside the caller's entitlement. No data was queried in that case; 'entitled_markets' lists the markets to retry with.", "default": true }, "dimension": { "type": "string", "enum": [ "delivery_provider", "delivery_method", "country", "platform", "product_category", "webshop_size", "growth", "export_market", "target_country", "product_dimension", "brand", "company", "domain" ], "title": "DimensionName", "description": "Dimensions whose queryable values can be discovered." }, "mode": { "type": "string", "enum": [ "enumerate", "search" ], "title": "Mode", "description": "How values were resolved: full enumeration vs name search." }, "country_codes": { "items": { "type": "string" }, "type": "array", "title": "Country Codes", "description": "Market scope applied (empty = not scoped / all markets)." }, "total_values": { "type": "integer", "title": "Total Values", "description": "Total distinct values/matches for this dimension, scope, and filter." }, "returned": { "type": "integer", "title": "Returned", "description": "Number of values included in this response." }, "values": { "items": { "properties": { "canonical_value": { "type": "string", "title": "Canonical Value", "description": "The value to pass verbatim to other tools (the stored token for value-keyed dimensions; the canonical name for id-keyed ones like category/brand)." }, "label": { "type": "string", "title": "Label", "description": "Human-readable label for matching against user phrasing." }, "value_id": { "title": "Value Id", "description": "Underlying key for id-keyed dimensions (e.g. category_id, brand_id, domain_id). Use when a downstream tool filters on the id rather than the name." }, "webshop_count": { "title": "Webshop Count", "description": "Distinct webshops with this value \u2014 a measure of materiality. Null when not applicable (e.g. search results)." }, "order": { "title": "Order", "description": "1-based rank for ordinal dimensions (low \u2192 high), e.g. small=1 \u2026 very_large=4. Null for non-ordinal dimensions." }, "score_range": { "title": "Score Range", "description": "For 'webshop_size': the [min, max] of the underlying 0\u2013100 size score this bucket covers (e.g. 'large' \u2192 [50, 74]). Null otherwise." }, "is_sentinel": { "type": "boolean", "title": "Is Sentinel", "description": "True when the value is a non-selectable placeholder (e.g. 'unknown', 'collect_yourself') rather than a real carrier/option.", "default": false } }, "type": "object", "required": [ "canonical_value", "label" ], "title": "QueryableValue", "description": "A single queryable value for a dimension." }, "type": "array", "title": "Values" }, "summary_for_llm": { "type": "string", "title": "Summary For Llm", "description": "Pre-rendered narrative listing the most material values for direct LLM use." } }, "type": "object", "required": [ "dimension", "mode", "total_values", "returned", "values", "summary_for_llm" ], "title": "QueryableValuesResponse", "description": "Response from the *get_queryable_values* tool." } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type" } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_queryable_values