> For the complete documentation index, see [llms.txt](https://docs.growthfactor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growthfactor.ai/guides/market-query.md). # Market Query *** {% hint style="info" %} Market query is in **early access beta**. {% endhint %} Market query is how you ask one question across a whole area instead of checking locations one at a time. You draw the area you're planning against, tell the **GrowthFactor Agent** what you're looking for, and every location in that area is evaluated at once. What comes back is a ranked shortlist on your map. This happens inside a study. See [Studies Overview](/study/overview.md) to start one. *** ## What it's good for Questions about a whole market rather than a specific address: * "Find the 20 best spots in S1 for a drive-thru." * "How many of my deals are in markets with median household income above $85,000?" * "Which of my stores have the weakest demographics in their trade area?" * "Show me every location in this boundary with population over 12,000 and no Starbucks within half a mile." * "Compare my Dallas areas to my Houston areas on daytime population." Single-address questions are faster through the site tools. Ask for a score, demographics, or foot traffic on one location and the agent goes straight there. See [GrowthFactor Agent](/study/growthfactor-agent.md). *** ## What you can screen on | What you can bring in | What it covers | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Candidate locations** | An even grid of locations covering the area you drew. This is what you get back when you ask for spots, sites, or places to consider. Ask for a finer grid when you want smaller locations. | | **Your stores and deals** | Everything in your portfolio and pipeline. Use them as the thing you're ranking, or as a constraint on candidates. | | **Demographics** | The demographic metrics your workspace is configured for. See [Demographics](/data-and-analytics/demographics.md). | | **Competitors** | Locations of a brand or category you name. See [Competitors and Complements](/data-and-analytics/competitors-and-complements.md). | | **Shapes in the study** | Any area or trade zone drawn in the open study, referred to by its label. See [Shapes](/study/shapes.md). | | **Major roads** | Highways and trunk roads running through the area. | | **Drive-time and walk-time areas** | Routed service areas around a point. See [Trade Zones](/data-and-analytics/trade-zones.md). | You can combine any of these in one question. "Locations in S1 with population over 12,000, within a 10-minute drive of the interstate, at least 500 meters from my nearest store" is a single search. *** ## Telling it what you're ranking on A search comes back ranked, and the ranking follows the criteria you give it. Ask for "the 20 best spots" on its own and a measure gets chosen for you, usually the largest population. That's a reasonable starting point. It's rarely the measure you would have picked. Say what "best" means and you get your ranking instead: * "Find the 20 locations in S1 with the highest median household income." * "Rank locations in this area by daytime population, at least half a mile from my existing stores." * "Best 20 for a drive-thru: population over 10,000, income over $75,000, ranked by income." Check what a search ranked on before you act on the order. Ask if the answer doesn't say. {% hint style="info" %} A search ranks on data that can be pulled for every location at once. The GrowthFactor Score is calculated one location at a time, so it isn't what a search ranks by. Score the shortlist afterwards to get it. See [GrowthFactor Score](/data-and-analytics/growthfactor-score.md). {% endhint %} *** ## Describing the area A search needs a bounded area to work in. Three ways to give it one: * **A shape you drew** — "in S1", or "inside the North Austin boundary". Refer to it by its label. * **A distance from a point** — "within two miles of 500 5th Ave". * **A drive time** — "within a 15-minute drive of my flagship". "Anywhere in Texas" is too broad to run. Narrow it to a market first. *** ## What comes back * **A ranked table** in the chat, showing the measures you asked about. * **A layer on the study map** with the locations that qualified, each labeled by rank or by a name you asked for. Locations are drawn as cells, so you can see the area each one covers, with a point at the center. They behave like anything else on your map. Drop a pin on the ones worth pursuing, draw a trade zone, or create a deal. A search returns up to 1,000 locations, or 10,000 if you ask for more. The top 200 are summarized in the chat and the full set lands on the map. *** ## Limits worth knowing * **Demographics come from your workspace configuration.** A single search covers up to 25 metrics across 500 areas. Ask for fewer metrics or a smaller area if you hit that. * **Name competitors exactly.** "Starbucks" bounds the search. "Coffee shops, roughly" doesn't. * **One routed drive-time or walk-time area per search.** "Everything within a 15-minute drive of my flagship" works. Routing out from thirty candidates at once doesn't. Straight-line distances have no such limit, so ask for a radius when a ring will do. * **A search runs for up to a minute.** Too broad and it times out, with a suggestion to narrow the area. * **One correction.** If a request can't be assembled into a search, the agent gets a single retry and then tells you what went wrong rather than guessing. *** ## What a search can't change Market query only reads. It doesn't drop pins, draw zones, or touch your portfolio. Acting on a result is a separate thing you ask for, and creating or updating anything still pauses for your approval first. See [Approving sensitive actions](/study/growthfactor-agent.md#approving-sensitive-actions). Results are scoped to your own access. If you can't see a store, deal, or study in the app, it isn't in them. *** ## Where it fits A search is the fastest way through step 2 of [Market Planning](/guides/market-planning.md). Instead of placing candidate pins one at a time, screen the market first and pin the shortlist that comes back. From there the rest of the workflow is unchanged: draw trade zones, read the data, and compare. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.growthfactor.ai/guides/market-query.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.