ECDB

Get the current user's ECDB API credit balance. Use this when the user asks about their remaining credits, account balance.

Get market data for one or more regions and a category. REQUIRED: `metric` must be set to one of the values listed below. Do NOT call this tool with metric=null or omitted — pick a specific metric first. Supports batch queries: pass a list of regions to compare multiple markets in one call. Example: region=["DEU", "FRA", "GBR"] returns data for all three countries. Optional argument defaults (use when user doesn't specify): - region: "WOR" (Worldwide) - don't ask, just use it - category: "all" - for aggregate queries - currency: "USD" - time window: omit start/end to get the default window ending at ECDB's current data year; some metrics/entities have data from 2014 and forecasts several years ahead Valid `metric` values (use start/end in YYYY for yearly, YYYY-MM for monthly where available): - revenue, revenue_growth: Market revenue and growth (yearly + monthly) - aov, aov_gross, aov_growth: Average order value metrics (yearly only) - conversion_rate, add_to_cart_rate, cart_abandonment_rate: Funnel metrics - orders_total, buyers, purchase_frequency: Volume metrics - discount_rate, return_rate: Transaction metrics - subcategory_shares: Revenue split by subcategories (no currency) - online_share: eCommerce share of total retail - gdp, population, internet_penetration, vat: Macro indicators (no category needed) - cross_border_split: Domestic vs import sales percentage (no time params, no category) - import_share: Breakdown of imports by source country (no time params, no category) Use get_regions and get_category_filters first to find valid region/category values. Response includes "Explore more" links to ECDB web tool market reports.

Get rankings for stores, retailers, companies, countries, categories, or target shopper groups. Entity types: - store: Top online stores (domains). Filter by region AND category. - retailer: Top retailer brands (aggregated across domains). Filter by region AND category. - company: Top eCommerce companies. Filter by region AND category. - country: Largest eCommerce countries. Filter by category only (no region). - category: Largest product categories. Filter by region only (no category). - shopper: Top stores among a target shopper group ("where do 20-29-year-old high-income Germans shop?"). REQUIRES region as an ISO alpha-3 country (no worldwide aggregate); takes age_group/income_group/year, no category/sort. age_group, income_group, and year are ONLY valid for this entity. For broad worldwide rankings, OMIT region instead of passing "WOR". For unfiltered rankings, OMIT category instead of passing "all". Valid sort fields: - store, retailer: filtered_total_gmv, global_total_gmv, global_1p_net_sales, global_3p_gmv, growth - company: filtered_revenue, global_revenue - country, category: filtered_revenue, total_revenue, online_share, growth "global" = the entity's total worldwide figure across all categories; "filtered" = the share of it allocated to the region/category filters you pass (ECDB's "filtered revenue"). With no region and no category the two are identical. Use the default sort when users ask for the "largest" or "top" entities. Do not use sort="revenue" for store/retailer rankings; those entities do not expose a generic revenue sort. Rankings CANNOT filter by: shop software, payment providers, shipping providers, revenue thresholds, or store type (1P/3P/Hybrid). Response includes "Explore more" links to ECDB web tool ranking pages.

Get region/country CODES for use in other tools (get_market, get_ranking, etc.). Returns codes like DEU (Germany), USA, E27 (EU), WOR (Worldwide), APA (Asia-Pacific). IMPORTANT defaults when user doesn't specify: - Use "WOR" (Worldwide) for global/unspecified market queries - Use "E27" for European Union, "APA" for Asia-Pacific, "GE7" for G7 Types: - countries: Individual countries with their group memberships - regions: Region groups (continents, economic blocs) with member counts - all: Both (default)

Get retailer data for one or more retailers. REQUIRED: both `retailer` and `metric` must be provided. Do NOT call this tool with metric=null or omitted — pick a specific metric first. Valid `metric` values (use start/end in YYYY for yearly, YYYY-MM for monthly where available): - gmv, gmv_growth: Total GMV and growth (yearly + monthly) - aov_gross: Gross average order value (yearly only) - buyers, conversion_rate, purchase_frequency: Customer metrics - orders_total, orders_1p, orders_3p: Order volume metrics - revenue_net_1p, revenue_gross_3p, vat_amount_1p: Revenue breakdown - gmv_source: 1P vs 3P GMV split in one call - gmv_by_category, gmv_by_country: Share percentages by dimension (NOT absolute GMV - use calculate_gmv_breakdown for absolute values) - aov_components: AOV breakdown including discounts, returns, shipping, and VAT (use for discount/return questions) - info, store_type, payment_providers, shipping_providers, mobile_apps: Retailer info (retailer only). Use mobile_apps for app ratings/reviews/downloads. Supports batch queries: pass a list of retailers to compare multiple retailers. Response includes "Explore more" links to ECDB web tool retailer profiles.

Get shopper-behavior data (loyalty, churn, CLV, buyer overlap, segments) for one or more store domains. REQUIRED: `domain`, `metric`, AND `country` must all be provided. Do NOT call this tool with metric=null or omitted. `country` is an ISO alpha-3 code and there is NO worldwide aggregate — shopper data is per-country panel data (mostly European coverage). If the user doesn't name a country, use the store's main market (the domain TLD is a good guide: zalando.de -> DEU; get_store metric=main_markets can confirm). A "not found" response usually means no shopper panel for that domain/country combination. domain="all" returns the market-wide benchmark for the country (e.g. average churn rate of German online shoppers). Valid `metric` values (all yearly, YYYY for start/end): - aov, lifetime_revenue: Monetary per-shopper metrics - retention_rate, churn_rate, repeat_rate, reactivation_rate: Loyalty rates - new_buyers, returning_buyers: New vs returning buyer split (shares, sum to 100%) - stable_share, upgrader_share, downgrader_share: Repeat buyers whose AOV stayed/increased/decreased - buyer_share, spent_share: Buyer/spend split by age and income segment (query with age_group=all, income_group=all for the full breakdown) - revenue_concentration: Spend share per spending decile 1-10 (4 credits) - purchase_frequency, purchase_interval, time_to_second_purchase: Purchase cadence (frequency in orders/buyer, the others in days) - aov_distribution: Order value buckets with shares (4 credits) - cohort_retention: Monthly cohort retention curve, month offset 0-11 (4 credits, ignores start/end) - cohort_retention_annual: Cohort retention triangle per year (4 credits) - overlap: Buyer overlap between `domain` and `domain_b` (REQUIRES domain_b). Use for "how many X customers also shop at Y". age_group/income_group filter to one segment; default "all" aggregates. Supports batch queries: pass a list of domains to compare stores. Use describe_shopper_metrics for detailed metric definitions. Response includes "Explore more" links to ECDB web tool store profiles.

Get store data for one or more domains. REQUIRED: both `domain` and `metric` must be provided. Do NOT call this tool with metric=null or omitted — pick a specific metric first. Valid `metric` values (use start/end in YYYY for yearly, YYYY-MM for monthly where available): - gmv, gmv_growth: Total GMV and growth (yearly + monthly) - aov: Average order value (yearly only) - buyers, conversion_rate, purchase_frequency: Customer metrics - orders_total, orders_1p, orders_3p: Order volume metrics - revenue_net_1p, revenue_gross_3p, vat_amount_1p: Revenue breakdown - customer_age, customer_income: Customer demographics - gmv_source: 1P vs 3P GMV split in one call - gmv_by_category, gmv_by_country: Share percentages by dimension (NOT absolute GMV - use calculate_gmv_breakdown for absolute values) - aov_components: AOV breakdown including discounts, returns, shipping, and VAT (use for discount/return questions) - store_type, payment_providers, shipping_providers, shop_software: Store info (domain only) - relations, retailer, mobile_apps, main_markets: Additional info (domain only). Use mobile_apps for app ratings/reviews/downloads. - competitors: Most similar stores, ranked by a 0-1 similarity score (domain only). Use for "who competes with X" / "stores like X". Returns whatever number of peers ECDB has for that domain — it cannot be filtered by region or category, and it is not a size ranking (use get_ranking for largest stores). - top_brands: The 10 product brands with the most revenue allocated to the store (domain + currency; no time params). Use for "which brands sell most on amazon.com". Rows carry brand_name, revenue and a brand_slug for follow-up get_brand calls; the API returns no share field. Supports batch queries: pass a list of domains to compare multiple stores. Response includes "Explore more" links to ECDB web tool store profiles.

Search the ECDB catalogue by name or domain to discover entities and their slugs. Use this FIRST when you don't know the exact identifier another tool needs: - retailer slugs for get_retailer (e.g. "nike", "lounge-by-zalando") - store domains for get_store (e.g. "nike.com", "zalando.de") - company slugs for get_company — derived from the legal entity name (e.g. "nike-inc", "amazon-com-inc", "alibaba-group-holding-ltd"), so the exact form is hard to guess; always resolve them here - brand slugs for get_brand (e.g. "nike", "nvidia-geforce", "coca-cola-other-brands") - product-category slugs for get_category — the ~18,000-category Category Explorer taxonomy (e.g. "electric-toothbrushes"), searchable only here Also use it when a get_store/get_retailer/get_company/get_brand call returned "not found". Matching is prefix/substring only, NOT fuzzy: a misspelling returns zero results. If a search comes back empty, retry with a shorter prefix or the domain instead of the brand name. Optional entity_type restricts the search to "retailer", "store", "company", "brand", or "category"; omit it to see all types (useful for disambiguation). Returns up to 20 matches per entity type. Many names exist as BOTH a retailer and a brand (e.g. "nike"): the retailer is the seller and its own shops (get_retailer), the brand is the products sold anywhere online (get_brand). IMPORTANT: category results are Category Explorer slugs for get_category ONLY. They are NOT valid for the `category` filter of get_market/get_ranking/ calculate_gmv_breakdown — that filter uses the separate get_category_filters taxonomy. Each result includes slug, display name, entity_type, and a link to its ECDB web profile (category results also carry level and parent; brand results carry the brand's category). This tool consumes no API credits.

Search ECDB's FAQ and glossary: how ECDB defines, measures, sources and forecasts its data, plus eCommerce and region-group vocabulary. Use this BEFORE answering methodology questions from memory, e.g.: - definitions: GMV, 1P vs 3P, marketplace, hybrid marketplace, pure player, eCommerce activity revenue, global vs filtered revenue, AOV, conversion rate - methodology: data sources (card transaction panels etc.), accuracy, quality indicator (A/B/C), forecasting techniques, why past years' figures change between updates, currency rates and inflation handling, update frequency - region groups: what DACH, Benelux, MENA, EU27, Nordics, LATAM etc. contain `query` is a term ("GMV", "DACH") or a question ("how accurate is the data"). An exact term match returns that entry (plus a directly related FAQ entry if one exists); otherwise the top 5 matches. Omit `query` to get the title index (25 FAQ questions by group, ~110 glossary terms) and pick from it. `source` narrows to "faq" or "glossary" (default "all"). This is NOT for a specific tool metric — use describe_market_metrics / describe_store_metrics / describe_retailer_metrics / describe_shopper_metrics / describe_brand_metrics for those. Costs no API credits. Entries carry a link to the public FAQ or glossary page.