API Reference

search_products

Resolve loose product wording to catalogued product names.

Call this first whenever a user names a product informally. The pricing and distribution tools match on the exact catalogued product name; querying them with a user's phrasing is the most common cause of a spurious “no stores carry this” answer. Resolve the wording here, then pass the returned productName or gtin onward.

storeCount follows the province argument: with a province it counts stores in that province only (matching get_product_distribution for the same GTIN); without it the count is national. The applied scope is echoed in lineage.filters.storeCountScope.

{"name": "search_products", "arguments": {"query": "pink kush 3.5g", "province": "AB", "limit": 3}}

{
  "items": [
    {"productName": "Pink Kush Dried Flower (7g)", "brand": "Pure Sunfarms", "gtin": "628188000133", "storeCount": 406},
    {"productName": "Pink Kush Dried Flower (28g)", "brand": "Pure Sunfarms", "gtin": "628188000935", "storeCount": 300}
  ],
  "lineage": {
    "source": "Neobi retail menu catalogue",
    "filters": {"province": "Alberta", "query": "pink kush 3.5g", "storeCountScope": "Alberta"},
    "asOf": "2026-08-23T13:22:25",
    "sourceClass": "observed_menu",
    "basis": "Directly observed retail menu listings — what stores publish, not what they sell."
  }
}

get_product_distribution

Count the retail stores carrying a product.

Supply gtin when known. A loosely-worded product name will under-count.

get_product_pricing

Get shelf-price position for a product: the average observed retail price plus the stores currently listing it cheapest.

The cheapest-store list is only returned when a product name is given (it resolves stores by catalogued name). Prices are observed retail menu prices — not wholesale, landed, or promotional cost.

Known data artefact: a handful of listings carry placeholder prices a dollar or two above zero. They clear the sanity floor and can top the cheapest list; treat a shelf price far below the average as an artefact, not a deal.

find_stores_carrying_brand

List the retail stores carrying a brand, with store name, city, and province.

Works for any brand in the catalogue, not only your own — this is public market observation, so it is the right tool for competitor footprint questions. Returns at most 500 stores. The store rows include a store identifier usable as producerId in get_store_assortment.

get_store_assortment

Describe what one retail store stocks: assortment by product category, and how its pricing sits against the provincial average for those categories.

Note the naming: producerId is a store identifier, not a licensed-producer id.

get_brand_distribution_share

Get a brand's shelf presence, product by product.

Returns the brand's products with their store counts and each product's share of observed shelf presence (sharePct).

This is share of shelf presence, not sales — it measures how many stores carry a listing and says nothing about units or revenue. Do not describe the result as market share.

get_market_size

Get a headline market count, served from a pre-computed daily market summary.

Use it to establish the denominator before quoting any penetration or coverage percentage.

{"name": "get_market_size", "arguments": {"metric": "stores", "province": "Alberta"}}

{
  "metric": "stores",
  "count": 539,
  "lineage": {
    "source": "Neobi market summary",
    "filters": {"province": "Alberta"},
    "asOf": "2026-08-23T13:26:57",
    "sourceClass": "derived_rollup",
    "basis": "Counts rolled up from observed retail menus."
  }
}

rank_by_distribution

Rank the biggest players in a market by how widely they are stocked.

Ranking by licensed producer is deliberately unavailable — the underlying data records the retailer operating the store, not the cannabis producer, so a “producer” ranking would return retail banners. Rank by brand instead. Asking for an unsupported dimension returns dimension_unsupported with that explanation. A cache-miss on a large province can take ~20 seconds; repeat calls are instant.

This is a shelf-presence ranking, not a sales ranking; the response is labelled rankedBy: "distribution" for exactly that reason.

{"name": "rank_by_distribution", "arguments": {"dimension": "brand", "province": "Alberta", "category": "pre-roll", "limit": 5}}

{
  "items": [
    {"label": "Back Forty", "value": 519},
    {"label": "General Admission", "value": 512},
    {"label": "SHRED", "value": 509}
  ],
  "lineage": {"filters": {"province": "Alberta", "category": "pre-roll", "dimension": "brand", "rankedBy": "distribution"}, "...": "..."}
}

analyze_brand_pod_share

Analyze a brand's share of available points of distribution (PODs) in a province.

A POD is one SKU listed at one retail store: a brand with 100 SKUs in 300 stores occupies far more PODs than one with 5 SKUs everywhere.

Two frameworks are returned, and they are not the same thing: the observed block counts real distinct store–SKU pairs in Neobi's data; the brandMetrics block runs the classic napkin calculation using Neobi-derived inputs unless you override them. A large divergence between the two usually means the assumed inputs don't match the market. Counting rules: a SKU counts once per store however often it is listed; delisted history is excluded; a listed product momentarily out of stock still occupies its POD; accessories and non-cannabis items are excluded. A cache-miss can take ~30 seconds; repeat calls are instant.

Supply salesMarketSharePct to get a distribution efficiency index (sales share ÷ POD share; above 1 means sales share exceeds shelf share). Neobi holds no point-of-sale data, so that figure can only come from you and is always labelled caller_supplied. Without it, the comparison block is omitted entirely.