# Google Maps Local Rank Monitor (`automation-lab/google-maps-local-rank-monitor`) Actor Track Google Maps local rankings for a target business across keywords, cities, and grid points. Export competitor rows for SEO reports. - **URL**: https://apify.com/automation-lab/google-maps-local-rank-monitor.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** SEO tools, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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 ## Google Maps Local Rank Monitor Track where a target business ranks in Google Maps for local keywords, locations, and optional grid points. ### What It Does Google Maps Local Rank Monitor checks bounded Google Maps result sets and returns the target position alongside competing local businesses. It is built for monitoring and reporting, not broad lead extraction. ### Use Cases - Local SEO rank tracking - Google Business Profile reporting - Competitor visibility monitoring - Franchise and multi-location checks - Weekly or daily scheduled rank snapshots - Local pack audit exports ### Input Provide a target business and the local searches to check. ### Target Business Use `targetName` for normal matching. Add `targetPlaceId` when you know the Google Maps CID or place ID and want stricter matching. ### Keywords The `keywords` field accepts a list such as: - pizza - emergency plumber - dentist - coffee shop - personal injury lawyer ### Locations The `locations` field accepts city, neighborhood, region, or address text. Each keyword is combined with each location. ### Grid Points Use `gridPoints` when you want rank checks from exact map coordinates. Each point accepts: - `label` - `lat` - `lng` - `zoom` ### Result Limit `maxResults` is capped at 20 per search. This keeps the actor focused on local rank monitoring and avoids exhaustive pagination. ### Competitor Rows When `includeCompetitors` is enabled, the dataset contains every ranked competitor row plus target rank metadata. ### Summary Mode When `includeCompetitors` is disabled, the actor outputs only the matched target row for each search. If the target is not found, it outputs a summary row with `targetMatched=false`. ### Output Fields The dataset includes: - checked time - keyword - location - grid point - search query - target name - target matched flag - target position - competitor rank - target row flag - business name - category - rating - address - neighborhood - website - phone - CID - place ID - map URL - latitude - longitude - competitor count ### Example Input ```json { "targetName": "Serious Pie Downtown", "keywords": ["pizza"], "locations": ["Seattle, WA"], "maxResults": 20, "includeCompetitors": true } ```` ### Example Grid Input ```json { "targetName": "Serious Pie Downtown", "keywords": ["pizza"], "locations": ["Seattle, WA"], "gridPoints": [ { "label": "Downtown", "lat": 47.6062, "lng": -122.3321, "zoom": 14 } ], "maxResults": 20 } ``` ### Output Example ```json { "keyword": "pizza", "location": "Seattle, WA", "targetMatched": true, "targetPosition": 2, "rank": 2, "isTarget": true, "businessName": "Serious Pie Downtown", "category": "Pizza restaurant, Italian restaurant, Pizza Takeout", "rating": 4.5, "address": "2001 4th Ave, Seattle, WA 98121", "mapUrl": "https://www.google.com/maps?cid=..." } ``` ### Scheduling Run the actor on an Apify schedule to build a rank history over time. ### Monitoring Workflow 1. Choose one target business. 2. Add the keywords that matter commercially. 3. Add city or neighborhood locations. 4. Optional: add exact grid points. 5. Export the dataset to compare rank changes. ### Matching Behavior Name matching is case-insensitive and ignores punctuation. CID or place ID matching is preferred when provided. ### Google Maps Data The actor extracts from the Google Maps web response. Available fields may vary by query, location, and Google response format. ### Limits This actor does not crawl every Google Maps page. It checks the top visible Maps results for the requested search combinations. ### Pricing The actor charges a small start event and a result event for output rows. Final tiered pricing is calculated after cloud validation. ### Reliability Notes Google Maps is dynamic and may change its internal response format. The actor keeps extraction bounded and validates output fields to reduce noisy results. ### Best Practices Use specific commercial keywords and realistic locations. For grid reports, keep the first run small and expand after verifying the target match. ### Troubleshooting If the target is not found, try adding the exact Google Maps CID or place ID, checking a narrower location, or increasing `maxResults` up to 20. ### Data Export The dataset can be exported as JSON, CSV, Excel, XML, RSS, or HTML through Apify. ### Recommended Columns For reporting dashboards, start with these columns: - keyword - location - gridLabel - targetPosition - rank - isTarget - businessName - rating - category - address - mapUrl ### API Usage Run the actor through the Apify API with the same JSON input used in the console. ### Privacy The actor works with public Google Maps search results. Do not submit private credentials or personal account data. ### Changelog Initial development version for APIA-1471. # Actor input Schema ## `targetName` (type: `string`): Business name to find in Google Maps results. Matching is case-insensitive and ignores punctuation. ## `targetPlaceId` (type: `string`): Optional Google Maps CID or place ID for exact matching when available. ## `keywords` (type: `array`): Search keywords to monitor. ## `locations` (type: `array`): Location names to combine with each keyword. ## `gridPoints` (type: `array`): Optional exact latitude/longitude points for local grid rank tracking. ## `maxResults` (type: `integer`): Maximum ranked Google Maps results to inspect per keyword/location. ## `includeCompetitors` (type: `boolean`): When enabled, output every ranked competitor row. When disabled, output one summary row per search. ## `countryCode` (type: `string`): Google country parameter used for local results. ## `languageCode` (type: `string`): Google interface language. ## `maxRequestRetries` (type: `integer`): Number of retry attempts for failed requests. ## Actor input object example ```json { "targetName": "Serious Pie Downtown", "keywords": [ "pizza" ], "locations": [ "Seattle, WA" ], "maxResults": 20, "includeCompetitors": true, "countryCode": "us", "languageCode": "en", "maxRequestRetries": 3 } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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 = { "targetName": "Serious Pie Downtown", "targetPlaceId": "", "keywords": [ "pizza" ], "locations": [ "Seattle, WA" ], "maxResults": 20, "includeCompetitors": true, "countryCode": "us", "languageCode": "en", "maxRequestRetries": 3 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/google-maps-local-rank-monitor").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 = { "targetName": "Serious Pie Downtown", "targetPlaceId": "", "keywords": ["pizza"], "locations": ["Seattle, WA"], "maxResults": 20, "includeCompetitors": True, "countryCode": "us", "languageCode": "en", "maxRequestRetries": 3, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/google-maps-local-rank-monitor").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 '{ "targetName": "Serious Pie Downtown", "targetPlaceId": "", "keywords": [ "pizza" ], "locations": [ "Seattle, WA" ], "maxResults": 20, "includeCompetitors": true, "countryCode": "us", "languageCode": "en", "maxRequestRetries": 3 }' | apify call automation-lab/google-maps-local-rank-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/google-maps-local-rank-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Maps Local Rank Monitor", "description": "Track Google Maps local rankings for a target business across keywords, cities, and grid points. Export competitor rows for SEO reports.", "version": "0.1", "x-build-id": "lPPHm9BS49dvtYHpa" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~google-maps-local-rank-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-google-maps-local-rank-monitor", "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/automation-lab~google-maps-local-rank-monitor/runs": { "post": { "operationId": "runs-sync-automation-lab-google-maps-local-rank-monitor", "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/automation-lab~google-maps-local-rank-monitor/run-sync": { "post": { "operationId": "run-sync-automation-lab-google-maps-local-rank-monitor", "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": [ "targetName", "keywords" ], "properties": { "targetName": { "title": "Target business name", "type": "string", "description": "Business name to find in Google Maps results. Matching is case-insensitive and ignores punctuation." }, "targetPlaceId": { "title": "Target Google place ID or CID", "type": "string", "description": "Optional Google Maps CID or place ID for exact matching when available." }, "keywords": { "title": "Keywords", "type": "array", "description": "Search keywords to monitor.", "default": [ "pizza" ], "items": { "type": "string" } }, "locations": { "title": "Locations", "type": "array", "description": "Location names to combine with each keyword.", "default": [ "Seattle, WA" ], "items": { "type": "string" } }, "gridPoints": { "title": "Grid points", "type": "array", "description": "Optional exact latitude/longitude points for local grid rank tracking.", "items": { "type": "object", "required": [ "lat", "lng" ], "properties": { "label": { "title": "Label", "type": "string", "description": "Human-readable point label.", "prefill": "Downtown" }, "lat": { "title": "Latitude", "type": "number", "description": "Latitude for the rank check point.", "prefill": 47.6062 }, "lng": { "title": "Longitude", "type": "number", "description": "Longitude for the rank check point.", "prefill": -122.3321 }, "zoom": { "title": "Zoom", "type": "integer", "description": "Google Maps zoom level used for this point.", "default": 14, "prefill": 14, "minimum": 10, "maximum": 18 } } } }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum ranked Google Maps results to inspect per keyword/location.", "default": 20 }, "includeCompetitors": { "title": "Include competitor rows", "type": "boolean", "description": "When enabled, output every ranked competitor row. When disabled, output one summary row per search.", "default": true }, "countryCode": { "title": "Country code", "type": "string", "description": "Google country parameter used for local results.", "default": "us" }, "languageCode": { "title": "Language code", "type": "string", "description": "Google interface language.", "default": "en" }, "maxRequestRetries": { "title": "Max request retries", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of retry attempts for failed requests.", "default": 3 } } }, "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 } } } } } } } } } } ```