# Google Geocoding Scraper (`kaix/google-geocoding-scraper`) Actor 🔥 ~$0.1/1K addresses 🔥 Forward and reverse geocode with Google: addresses to coordinates, coordinates to addresses. Structured address components, place IDs, viewport, plus codes. No Google API key required. - **URL**: https://apify.com/kaix/google-geocoding-scraper.md - **Developed by:** [Kai](https://apify.com/kaix) (community) - **Categories:** Developer tools, Integrations, AI - **Stats:** 3 total users, 2 monthly users, 98.9% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.10 / 1,000 addresses This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 Geocoding Scraper Geocode addresses and reverse geocode coordinates using Google's Geocoding API. Forward geocoding turns an address into coordinates plus structured address components; reverse geocoding turns a coordinate into formatted addresses. Returns place IDs, location type, result types, recommended viewport, bounding box, and plus codes. No Google API key required: the actor ships with a self-rotating pool of working Google keys. ### Why use this scraper? - No Google API key needed: a built-in pool of 39 working keys rotates automatically, with health tracking and cooldown. - Forward geocoding: address or place description to latitude/longitude plus structured components. - Reverse geocoding: latitude/longitude to formatted addresses and components. - Structured address breakdown: street number, street, city, state and state code, country and country code, postal code, neighborhood, sublocality, plus the full raw component list. - Rich result metadata: Google Place ID, location type (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE), result types, recommended viewport, precise bounding box, and plus codes. - Component filtering: restrict forward results by country, postal code, locality, and more. - Region biasing: bias forward results toward a country's region (ccTLD). - Viewport biasing: bias forward results toward a bounding box. - Reverse filters: narrow reverse results by result type and location type. - Localization: return addresses in any supported language. - Concurrent batch processing with configurable concurrency. - One dataset record per query, with graceful per-query handling of empty and invalid inputs. ### Use cases - Bulk convert lists of addresses into coordinates for mapping and analytics. - Reverse geocode GPS traces or device coordinates into human-readable addresses. - Normalize and standardize messy address data into structured fields. - Enrich CRM, spreadsheet, or catalog records with lat/lng, place IDs, and postal codes. - Validate addresses and flag ambiguous or partial matches. - Localize place names across multiple languages. ### How to use #### Forward geocode an address ```json { "addresses": ["1600 Amphitheatre Parkway, Mountain View, CA"] } ```` #### Forward geocode multiple addresses ```json { "addresses": ["Eiffel Tower, Paris", "Sydney Opera House", "Brandenburg Gate, Berlin"] } ``` #### Reverse geocode coordinates ```json { "latlngs": ["40.748817,-73.985428", "48.8584,2.2945"] } ``` #### Restrict results to a country (components filter) ```json { "addresses": ["Paris"], "components": "country:US" } ``` #### Bias results toward a region ```json { "addresses": ["Toledo"], "region": "es" } ``` #### Localize the output language ```json { "addresses": ["Munich, Germany"], "language": "de" } ``` #### Bias forward results to a viewport (bounds) ```json { "addresses": ["Springfield"], "bounds": "39.0,-90.0|40.0,-89.0" } ``` #### Filter reverse results by type ```json { "latlngs": ["40.748817,-73.985428"], "resultType": "street_address", "locationType": "ROOFTOP" } ``` #### Forward and reverse in one run, with tuned concurrency ```json { "addresses": ["Times Square, New York"], "latlngs": ["34.0522,-118.2437"], "maxConcurrency": 20 } ``` ### Input | Field | Type | Default | Description | | -------------------- | -------- | ----------- | --------------------------------------------------------------------------------- | | `addresses` | string\[] | | Addresses or place descriptions to forward geocode into coordinates | | `latlngs` | string\[] | | Coordinates as `lat,lng` strings to reverse geocode into addresses | | `language` | string | | Response language (e.g. `en`, `ja`, `de`, `fr`) | | `region` | string | | ccTLD region bias for forward geocoding (e.g. `us`, `gb`, `de`) | | `components` | string | | Forward component filter, e.g. `country:US` or `country:US\|postal_code:94043` | | `bounds` | string | | Forward viewport bias as `swLat,swLng\|neLat,neLng` | | `resultType` | string | | Reverse result-type filter, e.g. `street_address\|locality` | | `locationType` | string | | Reverse location-type filter, e.g. `ROOFTOP\|APPROXIMATE` | | `maxConcurrency` | number | `10` | Maximum number of queries processed in parallel (1-50) | | `proxyConfiguration` | object | direct | Optional proxy. The official keyed API rarely needs one; leave disabled unless required | At least one of `addresses` or `latlngs` is required. The `language`, `region`, `components`, and `bounds` parameters apply to all forward queries; `resultType` and `locationType` apply to all reverse queries. ### Output One record per query in the default dataset. Each record: | Field | Type | Description | | -------------- | -------- | ---------------------------------------------------------------------- | | `query` | string | The input address (forward) or `lat,lng` (reverse) | | `mode` | string | `forward` or `reverse` | | `status` | string | `OK`, `ZERO_RESULTS`, `INVALID_REQUEST`, or `ERROR` | | `errorMessage` | string | Present only when the request failed or was rejected | | `results` | array | Matched results; empty for `ZERO_RESULTS` and error statuses | Each item in `results`: | Field | Type | Description | | -------------------- | -------- | -------------------------------------------------------------------------- | | `address` | string | Formatted address | | `placeId` | string | Google Place ID | | `lat` / `lng` | number | Coordinates | | `locationType` | string | `ROOFTOP`, `RANGE_INTERPOLATED`, `GEOMETRIC_CENTER`, or `APPROXIMATE` | | `types` | string\[] | Result types (e.g. `street_address`, `premise`, `locality`) | | `components` | object | Structured address parts (see below) | | `viewport` | object | Recommended map viewport with `ne` and `sw` corners | | `bounds` | object | Precise bounding box, when Google provides one | | `partialMatch` | boolean | `true` when Google returned an approximate or partial match | | `plusCode` | object | `globalCode` and `compoundCode`, when available | | `postcodeLocalities` | string\[] | Localities within a postal code, when available | `components` contains: `streetNumber`, `street`, `city`, `state`, `stateCode`, `country`, `countryCode`, `postalCode`, `neighborhood`, `sublocality`, `administrativeAreaLevel2`, and `raw` (every Google address component with `longName`, `shortName`, and `types`). Absent fields are omitted from the output. #### Forward output (live data) ```json { "query": "1600 Amphitheatre Parkway, Mountain View, CA", "mode": "forward", "status": "OK", "results": [ { "address": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc", "lat": 37.4224864, "lng": -122.0855962, "locationType": "ROOFTOP", "types": ["premise", "street_address"], "components": { "streetNumber": "1600", "street": "Amphitheatre Parkway", "city": "Mountain View", "state": "California", "stateCode": "CA", "country": "United States", "countryCode": "US", "postalCode": "94043", "raw": ["...full Google address_components..."] }, "viewport": { "ne": { "lat": 37.4238679802915, "lng": -122.0842176197085 }, "sw": { "lat": 37.4211700197085, "lng": -122.0869155802915 } }, "partialMatch": false } ] } ``` #### Reverse output (live data) Reverse geocoding returns multiple results from most specific to least specific (16 for the coordinate below). The first result, trimmed: ```json { "query": "40.748817,-73.985428", "mode": "reverse", "status": "OK", "results": [ { "address": "W 34 St & 5 Av, New York, NY 10001, USA", "lat": 40.7488509, "lng": -73.9852755, "types": ["intersection"], "components": { "city": "New York", "stateCode": "NY", "country": "United States", "countryCode": "US", "postalCode": "10001", "raw": ["...full Google address_components..."] } } ] } ``` #### Statuses - `OK`: one or more results returned. - `ZERO_RESULTS`: the query was valid but matched nothing (empty `results`). - `INVALID_REQUEST`: the query was malformed (e.g. an unparseable coordinate); `errorMessage` explains why. - `ERROR`: the request could not be completed after the key pool was exhausted; `errorMessage` has details. ### Development ```bash npm install npm test # unit tests (vitest) npm run typecheck # tsc --noEmit npm run dev # run locally with storage/key_value_stores/default/INPUT.json ``` # Actor input Schema ## `addresses` (type: `array`): Addresses or place descriptions to geocode into coordinates. ## `latlngs` (type: `array`): Coordinates as 'lat,lng' strings to reverse geocode into addresses. ## `language` (type: `string`): Response language (e.g. en, ja, de, fr). ## `region` (type: `string`): ccTLD region bias for forward geocoding (e.g. us, gb, de). ## `components` (type: `string`): Component filter, e.g. 'country:US|postal\_code:94043'. ## `bounds` (type: `string`): Viewport bias as 'swLat,swLng|neLat,neLng'. ## `resultType` (type: `string`): Filter reverse results by type, e.g. 'street\_address|locality'. ## `locationType` (type: `string`): Filter reverse results by location type, e.g. 'ROOFTOP|APPROXIMATE'. ## `maxConcurrency` (type: `integer`): Maximum number of queries processed in parallel. ## `proxyConfiguration` (type: `object`): Optional. The official keyed Geocoding API rarely needs a proxy; leave disabled unless required. ## Actor input object example ```json { "addresses": [ "1600 Amphitheatre Parkway, Mountain View, CA" ], "latlngs": [ "37.4224764,-122.0842499" ], "maxConcurrency": 10 } ``` # 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 = { "addresses": [ "1600 Amphitheatre Parkway, Mountain View, CA" ], "latlngs": [ "37.4224764,-122.0842499" ] }; // Run the Actor and wait for it to finish const run = await client.actor("kaix/google-geocoding-scraper").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 = { "addresses": ["1600 Amphitheatre Parkway, Mountain View, CA"], "latlngs": ["37.4224764,-122.0842499"], } # Run the Actor and wait for it to finish run = client.actor("kaix/google-geocoding-scraper").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 '{ "addresses": [ "1600 Amphitheatre Parkway, Mountain View, CA" ], "latlngs": [ "37.4224764,-122.0842499" ] }' | apify call kaix/google-geocoding-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kaix/google-geocoding-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Geocoding Scraper", "description": "🔥 ~$0.1/1K addresses 🔥 Forward and reverse geocode with Google: addresses to coordinates, coordinates to addresses. Structured address components, place IDs, viewport, plus codes. No Google API key required.", "version": "0.1", "x-build-id": "SG13j3HsF5ph9omFP" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kaix~google-geocoding-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kaix-google-geocoding-scraper", "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/kaix~google-geocoding-scraper/runs": { "post": { "operationId": "runs-sync-kaix-google-geocoding-scraper", "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/kaix~google-geocoding-scraper/run-sync": { "post": { "operationId": "run-sync-kaix-google-geocoding-scraper", "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": { "addresses": { "title": "Addresses (forward geocoding)", "type": "array", "description": "Addresses or place descriptions to geocode into coordinates.", "items": { "type": "string" } }, "latlngs": { "title": "Coordinates (reverse geocoding)", "type": "array", "description": "Coordinates as 'lat,lng' strings to reverse geocode into addresses.", "items": { "type": "string" } }, "language": { "title": "Language", "type": "string", "description": "Response language (e.g. en, ja, de, fr)." }, "region": { "title": "Region bias (forward)", "type": "string", "description": "ccTLD region bias for forward geocoding (e.g. us, gb, de)." }, "components": { "title": "Components filter (forward)", "type": "string", "description": "Component filter, e.g. 'country:US|postal_code:94043'." }, "bounds": { "title": "Bounds bias (forward)", "type": "string", "description": "Viewport bias as 'swLat,swLng|neLat,neLng'." }, "resultType": { "title": "Result type filter (reverse)", "type": "string", "description": "Filter reverse results by type, e.g. 'street_address|locality'." }, "locationType": { "title": "Location type filter (reverse)", "type": "string", "description": "Filter reverse results by location type, e.g. 'ROOFTOP|APPROXIMATE'." }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of queries processed in parallel.", "default": 10 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional. The official keyed Geocoding API rarely needs a proxy; leave disabled unless required." } } }, "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 } } } } } } } } } } ```