# Local Market Saturation & Competitor Density Analyzer (`shelvick/local-market-saturation`) Actor Analyze how saturated a local market is. Give a business category and a location; get an aggregated Google Maps competitive landscape: competitor count, rating/review/price distributions, incumbent strength, and a 0-1 saturation score. Aggregate stats, not a lead list. - **URL**: https://apify.com/shelvick/local-market-saturation.md - **Developed by:** [Scott Helvick](https://apify.com/shelvick) (community) - **Categories:** Developer tools, AI - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $127.50 / 1,000 market analyzeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Local Market Saturation & Competitor Density Analyzer How crowded is a local market? Give a business category and a location and get back an aggregated competitive-landscape read from Google Maps local listings — how many competitors there are, how good and how established they are, what they charge, and a single 0-1 saturation score — instead of a raw dump of map pins you have to analyze yourself. ### What this does - **Category + location in, a saturation report out** — pass markets like `{"category": "coffee shops", "location": "Austin, TX"}`; get one aggregated report per market. Built for the question "how saturated is this market / where is it underserved" when sizing up competition or deciding where to open. - **Competitor count + density** — how many businesses match the category in that location (deduplicated across result pages), with a flag when the sample is capped. - **Rating distribution** — mean, median, and a bucketed spread of star ratings, so you can see whether incumbents are strong or mediocre. - **Review-volume distribution** — total and median review counts plus a bucketed spread, a proxy for how established and entrenched the field is. - **Price-tier mix** — how the market splits across `$`–`$$$$`. - **Incumbent strength** — the fraction of competitors rated ≥ 4.5, the fraction with ≥ 1,000 reviews, and a count of strong incumbents (well-rated *and* review-deep). - **A transparent saturation score (0-1)** — `low` / `moderate` / `high`, with its component signals (density, incumbent entrenchment, review depth) and the exact formula returned alongside it. Not a black box. - **Aggregate-only by design** — the report is statistics plus a short most-reviewed-incumbents sample (name, rating, review count). It is **not** a per-business lead list: no addresses, phone numbers, or review text. Use cases: - An AI agent assessing "should my user open a bakery in this neighborhood" or "which of these five metros is least saturated for HVAC." - Market research / site selection: compare competitor density and incumbent strength across candidate locations. - Competitive landscape sizing for a category in a city without manually counting pins on a map. - Feeding a downstream model clean, aggregated market structure instead of tens of thousands of tokens of raw listings. ### Why an aggregate-first design The raw data — local business listings — is already widely scraped. The problem this solves isn't *access* to pins; it's that a list of 60 businesses with ratings and review counts is not, by itself, an answer to "how saturated is this market." Someone still has to aggregate it: bucket the ratings, sum the reviews, judge how entrenched the incumbents are, and turn that into a comparable read across locations. This Actor does that aggregation deterministically and returns the *answer shape* — distributions, fractions, a saturation score — not the raw inputs. The saturation score is a transparent, documented composite (weighted density + incumbent entrenchment + review depth) with its components exposed, so you can audit how the number was produced and re-weight it yourself if you disagree. It is explicitly a Maps-derived heuristic, not a population-based index — there's no census join here. ### How it compares | Approach | Output | Aggregated | Saturation score | Per-business PII | Built for agents | |---|---|---|---|---|---| | Raw Maps/places scraper | list of pins | No — you aggregate | No | often yes | partial | | Manual counting on a map | a number in your head | by hand | No | n/a | No | | Enterprise location-intelligence platform | dashboards + forecasts | Yes | proprietary | varies | No (seat-based SaaS) | | **This Actor** | aggregate report per market | Yes | Yes, transparent | No (aggregate-only) | Yes | A raw scraper hands you the soup; an enterprise platform is a seat-licensed dashboard. This is the middle: a cheap, callable, aggregate market read with a transparent score. ### Input | Field | Type | Required | Default | Description | |---|---|---|---|---| | `markets` | array | yes | — | Markets to analyze. Each item is `{"category": "...", "location": "..."}`: category is the business type to count (e.g. `coffee shops`, `plumbers`, `dentists`); location is a city/area (e.g. `Austin, TX`). 1–20 per run; each becomes one report. | | `maxPlaces` | integer | — | `60` | How many local results to aggregate per market (paginated ~20/page). Higher = more representative distributions but slower. 10–80. | | `language` | string | — | `en` | Google interface language code (`hl`). | | `country` | string | — | `us` | Two-letter Google country code (`gl`), e.g. `us`, `gb`, `ca`. | ### Output One dataset record per market. ```json { "market": "coffee shops in Austin, TX", "category": "coffee shops", "location": "Austin, TX", "status": "completed", "competitorCount": 58, "resultsCapped": false, "rating": { "mean": 4.42, "median": 4.5, "distribution": { "<3.0": 1, "3.0-3.9": 6, "4.0-4.4": 19, "4.5-5.0": 32 } }, "reviews": { "total": 184320, "median": 410, "distribution": { "<10": 4, "10-99": 14, "100-999": 22, "1000+": 18 } }, "priceMix": { "$": 7, "$$": 28, "$$$": 11, "$$$$": 2, "unknown": 10 }, "incumbentStrength": { "fractionRatingGe45": 0.552, "fractionReviewsGe1000": 0.31, "strongIncumbents": 16 }, "topCompetitors": [ { "name": "Mozart's Coffee Roasters", "rating": 4.5, "reviewCount": 11000 }, { "name": "Cosmic Pickle", "rating": 4.7, "reviewCount": 4300 } ], "saturation": { "score": 0.74, "band": "high", "components": { "density": 1.0, "entrenchment": 0.276, "reviewDepth": 0.41 }, "formula": "0.5*density + 0.3*entrenchment + 0.2*reviewDepth (densityRef=50)" }, "notice": "Aggregated from public Google Maps local business listings at request time; ... not advice.", "error": null } ```` | Field | Type | Description | |---|---|---| | `market` / `category` / `location` | string | The analyzed market and its echoed inputs. | | `status` | string | `completed` (report produced, charged) or `failed` (no usable results; see `error`; not charged). | | `competitorCount` | integer | null | Distinct businesses aggregated; a lower bound when `resultsCapped` is true. | | `resultsCapped` | boolean | null | True if the `maxPlaces` cap was hit (more competitors likely exist). | | `rating` / `reviews` | object | null | Mean/median + bucketed distributions for star ratings and review counts. | | `priceMix` | object | null | Count of competitors per price tier (`$`–`$$$$`, plus `unknown`). | | `incumbentStrength` | object | null | Fractions rated ≥ 4.5 and with ≥ 1,000 reviews, plus the strong-incumbent count. | | `topCompetitors` | array | Up to 5 most-reviewed incumbents (name, rating, review count only). | | `saturation` | object | null | 0-1 score, band, component signals, and the formula. | | `notice` | string | Standing data-source + disclaimer note on every record. | | `error` | string | null | Reason when `status` is `failed`; `null` on success. | ### Example ```json { "markets": [{ "category": "coffee shops", "location": "Austin, TX" }, { "category": "coffee shops", "location": "Portland, OR" }], "maxPlaces": 60 } ``` ```bash curl -X POST "https://api.apify.com/v2/acts/shelvick~local-market-saturation/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"markets":[{"category":"coffee shops","location":"Austin, TX"}]}' ``` ### Calling from an AI agent #### Apify MCP server The Actor is a callable tool on `mcp.apify.com`. The input schema is self-documenting — an LLM can build a correct call from the field names and descriptions alone. Pay per call via x402 USDC on Base or Skyfire managed tokens. #### Apify SDK (Python) ```python from apify_client import ApifyClient client = ApifyClient("YOUR_TOKEN") run = client.actor("shelvick/local-market-saturation").call( run_input={"markets": [{"category": "coffee shops", "location": "Austin, TX"}]} ) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["market"], item["competitorCount"], item["saturation"]["score"], item["saturation"]["band"]) ``` #### REST API ``` POST https://api.apify.com/v2/acts/shelvick~local-market-saturation/run-sync-get-dataset-items?token=YOUR_TOKEN ``` ### Pricing Pay-per-event, billed only on success: one charge per market (category × location) successfully analyzed, after the report is pushed — never for a market that returns no usable results. Multi-market runs are billed per completed market; cap a whole run with `maxTotalChargeUsd`. The **Pricing** tab on this Store page is authoritative for the current per-market rate and any subscriber discounts. ### Behavior **Run-level failures (rare):** invalid input fails the run before any work — empty `markets`, more than 20, a blank `category`/`location`, or `maxPlaces` out of range (10–80). Nothing is charged. **Per-market outcomes:** - `completed` — an aggregated report was produced (charged). Check `competitorCount`, `resultsCapped`, and the `saturation` components for confidence. - `failed` — `no-results` (the location/category returned nothing usable) or a fetch error. Never charged. **Performance:** each market paginates the local listings (~20 results/page) up to `maxPlaces`; markets are processed concurrently. A handful of markets complete in well under a minute; large batches stay within the run timeout. ### FAQ **Is the saturation score a real index?** It's a transparent heuristic, not a population-based saturation index. The score combines competitor density, incumbent entrenchment, and review depth with documented weights, and every component is returned so you can audit or re-weight it. There's no census/population join. **How many competitors does it actually see?** Up to `maxPlaces` (default 60, max 80), drawn from the top-ranked local results — a representative sample of the competitive set, not a guaranteed census of every business. `resultsCapped` tells you when there are likely more. **Does it return business contact details?** No. The output is aggregate statistics plus a small most-reviewed-incumbents sample (name, rating, reviews). No addresses, phones, or review text — it's a market-research tool, not a lead list. **Can I compare several locations at once?** Yes — pass multiple markets in one run (e.g. the same category across five cities) and get one comparable report each. ### What this doesn't do - **No per-business lead lists** — no addresses, phone numbers, emails, or websites; aggregate statistics only. - **No review text** — review *counts* and ratings, never the review content. - **No foot-traffic, demographics, or revenue forecasting** — this is competitive structure from listings, not a location-intelligence platform. - **No historical trend** — a point-in-time snapshot at request time, not a time series. - **No guaranteed census** — a top-ranked sample, capped at `maxPlaces`. Use a raw places/Maps scraper if you actually want the per-business list with contact details. Use an enterprise location-intelligence platform if you need foot-traffic panels or revenue forecasts. Use this when you want a cheap, callable, aggregate read on how crowded and how entrenched a local market is. *** Design notes: [www.scotthelvick.com/tools/local-market-saturation](https://www.scotthelvick.com/tools/local-market-saturation) # Actor input Schema ## `markets` (type: `array`): Markets to analyze. Each item is a {"category", "location"} object: category is the business type to count (e.g. "coffee shops", "plumbers", "dentists"); location is a city/area (e.g. "Austin, TX", "Brooklyn, NY"). 1-20 markets per run. Each market becomes one aggregated saturation report. ## `maxPlaces` (type: `integer`): How many local results to aggregate per market (the local finder returns ~20 per page; this paginates up to the cap). Higher = more representative distributions but slower. 10-80. ## `language` (type: `string`): Google interface language code (hl), e.g. "en". Affects result language/formatting. ## `country` (type: `string`): Two-letter Google country code (gl), e.g. "us", "gb", "ca". Biases results to that country. ## Actor input object example ```json { "markets": [ { "category": "coffee shops", "location": "Austin, TX" } ], "maxPlaces": 60, "language": "en", "country": "us" } ``` # Actor output Schema ## `results` (type: `string`): Aggregated saturation reports for this run (one per market). # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "markets": [ { "category": "coffee shops", "location": "Austin, TX" } ], "maxPlaces": 60, "language": "en", "country": "us" }; // Run the Actor and wait for it to finish const run = await client.actor("shelvick/local-market-saturation").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "markets": [{ "category": "coffee shops", "location": "Austin, TX", }], "maxPlaces": 60, "language": "en", "country": "us", } # Run the Actor and wait for it to finish run = client.actor("shelvick/local-market-saturation").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "markets": [ { "category": "coffee shops", "location": "Austin, TX" } ], "maxPlaces": 60, "language": "en", "country": "us" }' | apify call shelvick/local-market-saturation --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=shelvick/local-market-saturation", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Local Market Saturation & Competitor Density Analyzer", "description": "Analyze how saturated a local market is. Give a business category and a location; get an aggregated Google Maps competitive landscape: competitor count, rating/review/price distributions, incumbent strength, and a 0-1 saturation score. Aggregate stats, not a lead list.", "version": "0.0", "x-build-id": "biwrtoS4SB1rmF9wC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/shelvick~local-market-saturation/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-shelvick-local-market-saturation", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/shelvick~local-market-saturation/runs": { "post": { "operationId": "runs-sync-shelvick-local-market-saturation", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/shelvick~local-market-saturation/run-sync": { "post": { "operationId": "run-sync-shelvick-local-market-saturation", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "markets" ], "properties": { "markets": { "title": "Markets", "type": "array", "description": "Markets to analyze. Each item is a {\"category\", \"location\"} object: category is the business type to count (e.g. \"coffee shops\", \"plumbers\", \"dentists\"); location is a city/area (e.g. \"Austin, TX\", \"Brooklyn, NY\"). 1-20 markets per run. Each market becomes one aggregated saturation report." }, "maxPlaces": { "title": "Max places per market", "minimum": 10, "maximum": 80, "type": "integer", "description": "How many local results to aggregate per market (the local finder returns ~20 per page; this paginates up to the cap). Higher = more representative distributions but slower. 10-80.", "default": 60 }, "language": { "title": "Language", "type": "string", "description": "Google interface language code (hl), e.g. \"en\". Affects result language/formatting.", "default": "en" }, "country": { "title": "Country", "type": "string", "description": "Two-letter Google country code (gl), e.g. \"us\", \"gb\", \"ca\". Biases results to that country.", "default": "us" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```