# Google Maps Geocoding Scraper (`crawlerbros/google-maps-geocoding`) Actor Bidirectional geocoding via Google Maps: convert addresses to coordinates (forward) or coordinates to addresses (reverse). Batch input supported with structured address components, place IDs, plus codes, and place categories. - **URL**: https://apify.com/crawlerbros/google-maps-geocoding.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Developer tools, Integrations, Automation - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Geocoding Scraper Bidirectional geocoding via Google Maps. Convert street addresses into latitude/longitude coordinates (forward geocoding), or convert coordinates back into a human-readable address (reverse geocoding). Supports batch input, multiple languages, and country bias for ambiguous queries. ### What it does - **Forward geocoding** — given an address, returns the resolved coordinates, place ID, structured address components, plus code, and a stable Google Maps URL. - **Reverse geocoding** — given a `{lat, lng}` pair, returns the nearest matched place name and address. Each input produces exactly one record in the dataset. Inputs that Google cannot resolve are still recorded (`"resolved": false`) so you can audit failures. ### Input | Field | Type | Description | |---|---|---| | `mode` | enum (`forward` \| `reverse`) | Which direction to geocode. Default: `forward`. | | `address` | string | A single address (forward mode). | | `addresses` | array of strings | Batch of addresses (forward mode). | | `location` | object `{lat, lng}` | A single coordinate (reverse mode). | | `locations` | array of `{lat, lng}` | Batch of coordinates (reverse mode). | | `language` | enum | Interface language (`en`, `es`, `fr`, `de`, `it`, `pt`, `ja`, `ko`, `zh`, `ar`, `ru`). Default: `en`. | | `country` | string | Optional ISO 3166-1 alpha-2 code (e.g. `US`, `GB`) used to bias results when an address is ambiguous. | | `proxyConfiguration` | proxy | Optional. By default the scraper runs without a proxy because Apify proxy frequently routes through regions that trigger Google's consent flow. | #### Example inputs **Forward (single):** ```json { "mode": "forward", "address": "1600 Amphitheatre Parkway, Mountain View, CA", "language": "en" } ```` **Forward (batch):** ```json { "mode": "forward", "addresses": [ "Eiffel Tower, Paris", "Big Ben, London", "Tokyo Tower, Tokyo" ], "language": "en" } ``` **Reverse (single):** ```json { "mode": "reverse", "location": {"lat": 40.7579, "lng": -73.9855} } ``` **Reverse (batch):** ```json { "mode": "reverse", "locations": [ {"lat": 48.8584, "lng": 2.2945}, {"lat": 35.6586, "lng": 139.7454}, {"lat": -33.8568, "lng": 151.2153} ] } ``` ### Output Each dataset record contains a subset of these fields (empty fields are omitted): | Field | Type | Description | |---|---|---| | `mode` | string | `"forward"` or `"reverse"`. | | `inputAddress` | string | Original address (forward mode only). | | `inputLocation` | object | Original coordinates (reverse mode only). | | `resolved` | boolean | Whether Google resolved the input to a place. | | `name` | string | Place name (h1 on the place page); often blank for pure street addresses. | | `formattedAddress` | string | Full address as Google formats it. | | `location` | object | `{lat, lng}` of the resolved place. | | `placeId` | string | Google's internal feature ID (hex:hex format). | | `plusCode` | string | Open Location Code if present. | | `addressComponents` | object | Structured `{streetNumber, street, city, state, postalCode, country, countryCode}`. | | `categoryName` | string | Google's category label when the resolved place is a business. | | `googleMapsUrl` | string | Stable `/maps/place/` URL. | | `scrapedAt` | string | UTC ISO-8601 timestamp. | | `error` | string | Present only when scraping failed. | #### Example output ```json { "mode": "forward", "inputAddress": "1600 Amphitheatre Parkway, Mountain View, CA", "resolved": true, "name": "Google Building 41", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "location": {"lat": 37.4224864, "lng": -122.0855962}, "placeId": "0x808fba02f1822489:0x37a9269fbae1c4f7", "plusCode": "CWC8+W4 Mountain View, California", "addressComponents": { "streetNumber": "1600", "street": "Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "postalCode": "94043", "country": "USA", "countryCode": "US" }, "categoryName": "Corporate office", "googleMapsUrl": "https://www.google.com/maps/place/...", "scrapedAt": "2026-06-16T12:00:00+00:00" } ``` ### FAQs **Q: Do I need an API key?** No. This scraper uses the public Google Maps web interface — no API key, no quota, no billing. **Q: How many results does it return per input?** One record per input. If an address is ambiguous, Google picks the highest-confidence match (the same one you would see at the top of `maps.google.com`). **Q: How accurate are the coordinates?** Coordinates are extracted directly from Google's resolved `/maps/place/…` URL with full precision (often 7 decimal places, sub-centimetre accuracy). **Q: Why does my batch of 10 addresses take 1–2 minutes?** The scraper navigates a real browser for each address with a small polite delay between requests to avoid rate-limiting. Throughput is roughly 5–8 addresses per minute. **Q: Should I use a proxy?** Usually no. The default no-proxy path is the most reliable because Apify proxy often routes through EU regions that trigger Google's consent screen. Use the optional `proxyConfiguration` only if you hit rate-limits. **Q: What languages are supported?** The `language` input controls the Google Maps interface language and the format of the returned address (e.g. street names, country names in the target language). Currently exposed: English, Spanish, French, German, Italian, Portuguese, Japanese, Korean, Chinese, Arabic, Russian. **Q: Can I bias results to a specific country?** Yes. Set `country` to an ISO 3166-1 alpha-2 code (e.g. `US`, `GB`, `FR`). The scraper appends the country name to ambiguous queries (e.g. `Big Ben` → `Big Ben, UK`). **Q: What happens for unresolvable inputs?** A record is still pushed with `"resolved": false` and the original input echoed back in `inputAddress` / `inputLocation`, so you can audit failures. ### Use cases - Convert a CSV of customer addresses to coordinates for mapping. - Enrich event logs with city/state/country from raw GPS pings. - Validate user-submitted addresses against Google's canonical form. - Reverse-geocode IoT device locations or photo EXIF coordinates. - Compare address-component parsing across multiple countries. ### Data source This actor scrapes Google Maps directly. It does not call the Google Maps Geocoding API, so no Google Cloud project, billing account, or API key is required. ### 🗺️ Complete Google Maps Scraper Suite This actor is part of a comprehensive Google Maps data extraction toolkit by **crawlerbros**. All actors run on the free Apify plan, use no proxy by default, and return clean, structured data. | Actor | What it does | |---|---| | 🏢 [Google Maps Business Scraper](https://apify.com/crawlerbros/google-maps-scraper) | Extract business data — name, address, phone, website, rating, reviews, hours, amenities | | ⭐ [Google Maps Reviews Scraper](https://apify.com/crawlerbros/google-maps-reviews-scraper) | Scrape reviews with reviewer Local Guide level, photos, mentioned items, owner replies | | 📸 [Google Maps Photos Scraper](https://apify.com/crawlerbros/google-maps-photos) | Extract all photos from any place — max-resolution URLs, contributor info, categories | | 🕐 [Google Maps Business Hours Scraper](https://apify.com/crawlerbros/google-maps-business-hours) | Full 7-day hours, timezone, current local time, next open/close, holiday hours | | 📊 [Google Maps Popular Times Scraper](https://apify.com/crawlerbros/google-maps-popular-times) | Busy hours histogram for all 7 days + current busyness + typical visit time | | 📧 [Google Maps Email Extractor](https://apify.com/crawlerbros/google-maps-email-extractor) | Find business emails + social media links by crawling websites | | 🗺️ [Google Maps Area Scanner](https://apify.com/crawlerbros/google-maps-area-scanner) | Geographic grid scanning — bypass the 120-place limit with bounding box / circle / polygon | | 💼 [Google Maps Leads Scraper](https://apify.com/crawlerbros/google-maps-leads) | B2B lead generation with email + phone enrichment, US states + global countries | | 🤖 [Google Maps MCP Server](https://apify.com/crawlerbros/google-maps-mcp) | Unified MCP server combining search + reviews for AI assistants | | 🧭 [Google Maps Directions Scraper](https://apify.com/crawlerbros/google-maps-directions) | A→B routing — distance, duration, traffic, route alternatives for driving/walking/transit | | 🔗 [Google Maps Similar Places Scraper](https://apify.com/crawlerbros/google-maps-similar-places) | "People also search for" / related place discovery — competitor & alternative finder | | 🍽️ [Google Maps Menu Scraper](https://apify.com/crawlerbros/google-maps-menu) | Restaurant menu items, prices, descriptions, photos | | 📌 [Google Maps Nearby Scraper](https://apify.com/crawlerbros/google-maps-nearby) | Find places near a coordinate point — lightweight POI search by category | | 📋 [Google Maps Place List Scraper](https://apify.com/crawlerbros/google-maps-place-list) | Extract Google's curated "Top X in Y" lists — best hotels/restaurants/things to do | | 🌍 [Google Maps Timezone Scraper](https://apify.com/crawlerbros/google-maps-timezone) | IANA timezone + current local time from coordinates | # Actor input Schema ## `mode` (type: `string`): forward = address -> coordinates. reverse = coordinates -> address. ## `address` (type: `string`): A single address for forward geocoding. Used when mode = forward. ## `addresses` (type: `array`): List of addresses for batch forward geocoding. Used when mode = forward. ## `location` (type: `object`): A single {lat, lng} coordinate for reverse geocoding. Used when mode = reverse. Example: {"lat": 40.7484, "lng": -73.9857} ## `locations` (type: `array`): List of {lat, lng} coordinates for batch reverse geocoding. Used when mode = reverse. Example: \[{"lat": 40.7484, "lng": -73.9857}] ## `language` (type: `string`): Language code for the Google Maps interface and result formatting. ## `country` (type: `string`): Optional ISO 3166-1 alpha-2 country code (e.g. "US", "GB", "FR") used to bias results toward that country when an address is ambiguous. ## `proxyConfiguration` (type: `object`): Optional proxy. Apify proxy may route through regions that trigger Google consent pages; the default no-proxy path is usually more reliable. ## Actor input object example ```json { "mode": "forward", "addresses": [ "1600 Amphitheatre Parkway, Mountain View, CA" ], "language": "en" } ``` # Actor output Schema ## `geocodingResults` (type: `string`): Dataset containing forward and reverse geocoding records. # 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 = { "mode": "forward", "addresses": [ "1600 Amphitheatre Parkway, Mountain View, CA" ], "language": "en" }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/google-maps-geocoding").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 = { "mode": "forward", "addresses": ["1600 Amphitheatre Parkway, Mountain View, CA"], "language": "en", } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/google-maps-geocoding").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 '{ "mode": "forward", "addresses": [ "1600 Amphitheatre Parkway, Mountain View, CA" ], "language": "en" }' | apify call crawlerbros/google-maps-geocoding --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/google-maps-geocoding", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Maps Geocoding Scraper", "description": "Bidirectional geocoding via Google Maps: convert addresses to coordinates (forward) or coordinates to addresses (reverse). Batch input supported with structured address components, place IDs, plus codes, and place categories.", "version": "0.3", "x-build-id": "Fg2WBHzOsz1s6GSu9" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~google-maps-geocoding/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-google-maps-geocoding", "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/crawlerbros~google-maps-geocoding/runs": { "post": { "operationId": "runs-sync-crawlerbros-google-maps-geocoding", "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/crawlerbros~google-maps-geocoding/run-sync": { "post": { "operationId": "run-sync-crawlerbros-google-maps-geocoding", "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", "properties": { "mode": { "title": "Mode", "enum": [ "forward", "reverse" ], "type": "string", "description": "forward = address -> coordinates. reverse = coordinates -> address.", "default": "forward" }, "address": { "title": "Address (single)", "type": "string", "description": "A single address for forward geocoding. Used when mode = forward." }, "addresses": { "title": "Addresses (batch)", "type": "array", "description": "List of addresses for batch forward geocoding. Used when mode = forward.", "items": { "type": "string" } }, "location": { "title": "Location (single)", "type": "object", "description": "A single {lat, lng} coordinate for reverse geocoding. Used when mode = reverse. Example: {\"lat\": 40.7484, \"lng\": -73.9857}" }, "locations": { "title": "Locations (batch)", "type": "array", "description": "List of {lat, lng} coordinates for batch reverse geocoding. Used when mode = reverse. Example: [{\"lat\": 40.7484, \"lng\": -73.9857}]", "items": { "type": "object" } }, "language": { "title": "Language", "enum": [ "en", "es", "fr", "de", "it", "pt", "ja", "ko", "zh", "ar", "ru" ], "type": "string", "description": "Language code for the Google Maps interface and result formatting.", "default": "en" }, "country": { "title": "Country bias (optional)", "type": "string", "description": "Optional ISO 3166-1 alpha-2 country code (e.g. \"US\", \"GB\", \"FR\") used to bias results toward that country when an address is ambiguous." }, "proxyConfiguration": { "title": "Proxy Configuration (optional)", "type": "object", "description": "Optional proxy. Apify proxy may route through regions that trigger Google consent pages; the default no-proxy path is usually more reliable." } } }, "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 } } } } } } } } } } ```