# Demand Forecast (ListeningMind)

> Demand forecast and season calendar. From category seed keywords it collects related queries, groups them into segments, forecasts the next 3 or 6 months and the change versus last year from 48 months of monthly search volume, and derives prep, campaign, launch and peak months. Product planners, merchandisers and campaign owners use it to set season timing. Data comes from the ListeningMind Data API (intent_finder, keyword_info). Markets: Korea, Japan, US.

Korean: 앞으로 3~6개월 카테고리 수요와 출시·캠페인 타이밍은 언제인가 · Japanese: 今後3~6か月のカテゴリ需要と発売・キャンペーンのタイミング

## Use it as an agent
- [MCP server](https://daas-forecast.listeningmind.ai/mcp): Streamable HTTP, JSON-RPC. 15 app tools plus app_guide, result store tools (results_sync, results_list, results_get, results_compare, results_export) and settings sweeps (plan_batch, batch_status)
- WebMCP: every page of this app registers the same tools in `document.modelContext` for a browser agent; calls that spend credits ask the person on the page
- [OpenAPI](https://daas-forecast.listeningmind.ai/.well-known/openapi.json): the same tools as a REST contract (operationId = tool name)
- [agents.md](https://daas-forecast.listeningmind.ai/agents.md): step-by-step guide · [API catalog](https://daas-forecast.listeningmind.ai/.well-known/api-catalog) · [MCP server card](https://daas-forecast.listeningmind.ai/.well-known/mcp/server-card.json)
- Every page answers `Accept: text/markdown` with a markdown version
- Tools of kind run or delete spend credits or delete data: over MCP the call returns confirm_url for a person, then call confirmation_status
- Accounts: reading results and history is open. Starting a run or changing data needs a ListeningMind member: the person approving confirm_url signs in or [signs up](https://daas-forecast.listeningmind.ai/_lm/auth/signup); other changes over MCP need the member's agent key (LM-User-Key header, created at https://daas-forecast.listeningmind.ai/_lm/account)

## What you give and what you get
- Inputs: Seed keywords (up to 5, e.g. sunscreen), market (kr/jp/us), horizon (3 or 6 months), scope (standard/wide), segment mode (auto/seed/custom with your own segments), gender and age (Korea only), credit cap.
- Outputs: Category outlook (next-period total, change vs last year, where the months sit in the season), forecast per segment with prep, campaign, launch and peak months, keyword list and excluded list, written brief, evidence. Report as HTML or Markdown, forecast CSV, keywords CSV, timing ICS calendar, result JSON.
- Cost: With defaults (1 seed, standard) about 400-500 Data API credits and 1-3 minutes. More seeds, wide scope, custom segments and demography add credits. Server cap 5,000. LLM calls are used for filtering, segments and the brief. Seed suggestions cost up to 600 credits.

## How a result is made (in order)
1. `get_config`: Get example seeds per market and the timing rules.
2. `suggest_seeds`: With one seed, get companion seeds.
3. `estimate_credits`: Check expected credits and tell the person.
4. `start_run`: Start the forecast.
5. `get_run`: Poll until done and read the result.
6. `get_report_markdown`: Get the full report as text.
7. `download_timing_ics`: Export the timing windows as a calendar.
8. `download_forecast_csv`: Export monthly forecast numbers.

Run stages reported by the app: universe → filter → series → segments → forecast → demography → brief → done

## Method (how the analysis works)
1. Build a keyword universe from the seed keywords with intent_finder.
2. Remove off-topic keywords with an LLM.
3. Fetch 48 months of monthly search volume with keyword_info and group the keywords into segments.
4. Forecast the next 3 or 6 months and the change versus last year, per segment and for the whole category.
5. Derive prep, campaign, launch and peak months from the timing rules, add gender and age share (Korea only) and write the brief.

## Reading the result
- category.rec.horizon_total and horizon_yoy are next-period demand and its change versus last year; momentum and regime are recorded with them.
- category.plan.peak and launch_from are the timing answer; download_timing_ics puts the prep, campaign, launch and peak windows into a calendar.
- segments holds the forecast and timing per segment, so you can see which part of the category moves first.
- category.rec.backtest_error is the forecast error tested on past data; segments with a very small base may show no year-over-year value.
- keywords and excluded show what was counted and what was dropped.

## Requests this app answers well
- How will sunscreen demand move over the next 6 months, and when should the campaign start
- Give me the peak month and the best launch timing for humidifiers in Japan as a calendar
- Forecast swimwear demand in the US for the next 3 months, split by segment
- Forecast whether padded jacket demand in Korea will be higher or lower than last year, with the gender and age share

## Continue in another app
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt) (MCP `https://daas-cep.listeningmind.ai/mcp`): When the timing is set and you need the situations and messages to use in those months. Carry: The category seed keyword and market; read CEP Finder's time series and seasonality against the peak and launch months.
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt) (MCP `https://daas-pulse.listeningmind.ai/mcp`): When you want to know which specific things are rising for a gender and age segment within the category. Carry: The seed keywords and market, and in Korea the segment (gender and age).

## Using the screens (browser agents)
- `describe_screen`: menus, tabs, fields and buttons of the current screen, and what the page is for
- `go_to`: open a menu or page of this app by its label or path
- `fill_field`: type a value into a field by its label (never presses run; runs go through the run tools, which ask the person)
- `read_this_page`: the text and ids of what the person is looking at

## Tools
- `get_config` (read, GET /api/config): Returns markets, example seed topics per category for the market, the timing rules (ramp, prep lead, launch window, peak thresholds), the default credit cap, whether the LLM is available and the account credit balance. Free.
- `suggest_seeds` (run, POST /api/suggest_seeds): Proposes companion seed keywords for one category keyword: related queries from intent_finder, ranked by 12-month volume from keyword_info, then picked by an LLM. Returns {seeds, credits}. Up to 600 Data API credits (usually about 200-300), 10-30 seconds.
- `estimate_credits` (read, POST /api/estimate): Returns the expected Data API credits for the inputs: {harvest, series, demography, total, pool}. Computed locally, no API calls; cached calls in the real run are free.
- `start_run` (run, POST /api/runs): Starts a background run: builds a keyword universe from the seeds, filters off-topic keywords with an LLM, pulls 48 months of volume, groups keywords into segments, forecasts the next 3 or 6 months per segment and for the category, and derives prep, campaign, launch and peak months. Returns {run_id}. Poll get_run. About 400-1,800 Data API credits with defaults, 1-3 minutes.
- `get_run` (read, GET /api/runs/{run_id}): Returns one run: status (running, done, error), progress {stage, pct, steps}, credits, params, error and, when done, the result (meta, stats, months, category forecast and plan, segments, keywords, excluded, rules, brief, evidence). Repeat until status is done or error.
- `list_runs` (read, GET /api/runs): Lists recent runs with run_id, status, params, credits, created_at, updated_at, error and, for finished runs, a summary {segments, keywords, latest_month}.
- `get_report_markdown` (read, GET /api/runs/{run_id}/report.md): Returns the full forecast report as Markdown text (category outlook, segment plans, timing, keywords). Free. 404 until the run is done.
- `get_report_html` (read, GET /runs/{run_id}/report.html): Returns the full report as a self-contained HTML page. download=1 (default) sends it as a file, 0 shows it inline. Free.
- `download_forecast_csv` (read, GET /runs/{run_id}/forecast.csv): Downloads monthly actual and forecast values (with lo/hi range, model and regime) per segment and for the whole category as CSV. Free.
- `download_keywords_csv` (read, GET /runs/{run_id}/keywords.csv): Downloads the keyword list with segment, volume and forecast as CSV. Free.
- `download_timing_ics` (read, GET /runs/{run_id}/timing.ics): Downloads the prep, campaign, launch and peak windows as an iCalendar (.ics) file to import into a calendar. Free.
- `download_run_json` (read, GET /runs/{run_id}/run.json): Returns the raw result object of a finished run as JSON. Free.
- `rerun_run` (run, POST /api/runs/{run_id}/rerun): Starts a new run with the same parameters as an earlier run. Returns {run_id}. Same cost as start_run minus cached calls.
- `delete_run` (delete, DELETE /api/runs/{run_id}): Deletes a run and its result. Cannot be undone.
- `get_report_robots` (read, GET /_lm/report-robots/{run_id}): Returns whether search engines may index this report page (index or noindex), and why: a company member's run or one set by hand is index; a customer's run, and any run that is still going, failed or came back empty, is noindex. Read only; no credits.

## Pages
- [Demand Forecast home](https://daas-forecast.listeningmind.ai/): Forecast input form.
- [Run history](https://daas-forecast.listeningmind.ai/runs): Past forecasts, re-run and delete.
- [Method and rules](https://daas-forecast.listeningmind.ai/method): Forecast model and timing rules. ?lang=ko|ja|en

## Limits
- Up to 5 seeds and up to 12 custom segments. Gender and age only for gl=kr. Data is monthly; the forecast starts after the latest measured month. Segments with a very small base may show no year-over-year value. Languages ko/ja/en.

## The ListeningMind apps (same account, same tools, call any of them)
Each app has `/mcp`, `/llms.txt`, `/agents.md` and WebMCP on its pages. `family_apps` and `recommend_app` return this list with addresses.
- [ACO](https://daas-aco.listeningmind.ai/llms.txt): Diagnoses whether a product detail page can be cited by AI answers and used by shopping agents (MCP `https://daas-aco.listeningmind.ai/mcp`)
- [AOO](https://daas-aoo.listeningmind.ai/llms.txt): Measures whether AI agents can get real tasks done on a website (MCP `https://daas-aoo.listeningmind.ai/mcp`)
- [Brand Finder](https://daas-brand.listeningmind.ai/llms.txt): Which brands lead search by generation or field, and what their brand assets are (MCP `https://daas-brand.listeningmind.ai/mcp`)
- [Brand Naming Agent](https://daas-naming.listeningmind.ai/llms.txt): Creates and checks brand name candidates grounded in search data (MCP `https://daas-naming.listeningmind.ai/mcp`)
- [Brand Wiki](https://daas-wiki.listeningmind.ai/llms.txt): Turns a brand website into the entities, wiki pages and evidence AI assistants read (MCP `https://daas-wiki.listeningmind.ai/mcp`)
- [CEP Finder](https://daas-cep.listeningmind.ai/llms.txt): In which situations do people start looking for this category (category entry point map) (MCP `https://daas-cep.listeningmind.ai/mcp`)
- [Creative Finder](https://daas-creative.listeningmind.ai/llms.txt): Finds purchase situations (CEP) in search data and drafts a creative, an image and a video for each (MCP `https://daas-creative.listeningmind.ai/mcp`)
- [Funnel Leak Finder](https://daas-funnel.listeningmind.ai/llms.txt): Where category search journeys leak to competitors (MCP `https://daas-funnel.listeningmind.ai/mcp`)
- [GEO Audit](https://daas-geo.listeningmind.ai/llms.txt): Checks whether a web page is ready to be read and cited by search engines and AI answer engines (MCP `https://daas-geo.listeningmind.ai/mcp`)
- [ICSS](https://daas-icss.listeningmind.ai/llms.txt): Synthetic consumer panel conditioned on search intent, for surveys and FGDs (MCP `https://daas-icss.listeningmind.ai/mcp`)
- [Intent KG](https://daas-intent.listeningmind.ai/llms.txt): What people look for about a topic, why, and how they choose (Intent Knowledge Graph) (MCP `https://daas-intent.listeningmind.ai/mcp`)
- [Prompt Builder](https://daas-prompt.listeningmind.ai/llms.txt): Finds what consumers ask AI and builds managed brand prompts with AI visibility (MCP `https://daas-prompt.listeningmind.ai/mcp`)
- [Pulse Finder](https://daas-pulse.listeningmind.ai/llms.txt): What is rising in search for a gender and age segment right now (MCP `https://daas-pulse.listeningmind.ai/mcp`)
- [Smart Store Suite](https://daas-store.listeningmind.ai/llms.txt): Which Smart Store products to grow, and how to rewrite their titles and detail pages in searchers' words (MCP `https://daas-store.listeningmind.ai/mcp`)
- [Taste Finder](https://daas-taste.listeningmind.ai/llms.txt): In what sensory and emotional words do people choose this (consumer taste report from search data) (MCP `https://daas-taste.listeningmind.ai/mcp`)
- [ListeningMind Data API](https://daas.listeningmind.ai/llms.txt): the search data behind every app (MCP `https://daas.listeningmind.ai/mcp`) · [glossary](https://daas.listeningmind.ai/en/glossary) · [all apps](https://daas.listeningmind.ai/en/apps)

## Optional
- ListeningMind data and other apps: https://www.listeningmind.com · contact m-support@listeningmind.com