# Google Maps Geocoding Scraper (`googleapi/google-maps-geocoding-scraper`) Actor

Resolve public Google Maps places into source-backed business identity, location, contact, reputation, hours, profile attributes, and visible photo data.

- **URL**: https://apify.com/googleapi/google-maps-geocoding-scraper.md
- **Developed by:** [Google API](https://apify.com/googleapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 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.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Resolve public Google Maps searches, place URLs, addresses, or coordinate pairs into structured place records. Results can include business identity, coordinates, address, contact details, ratings, opening hours, services, and photos when Google Maps displays them.

Address and coordinate inputs search for the supplied place or location. They do not automatically find nearby businesses. A reverse coordinate result may contain only coordinates or a Plus Code when Maps does not show a street address.

### Quick start

Search for public Maps listings:

```json
{
  "queries": ["independent coffee shops in Seattle"],
  "maxItems": 10,
  "page": 1,
  "maxPages": 2
}
```

To resolve addresses or coordinates, use **addresses** or **coordinates** instead of a search phrase.

### Input

#### Search sources

| Input | Description |
| --- | --- |
| **startUrls** | Up to 25 public Google Maps search or place URLs. **placeUrls**, **sourceUrls**, **searchUrls**, and **urls** are aliases. |
| **queries** | Public Maps search phrases. **query** and **searchQuery** accept one phrase. |
| **addresses** | Up to 100 public addresses to search on Google Maps. |
| **coordinates** | Up to 100 coordinate pairs, each with latitude and longitude. Latitude must be -90 to 90; longitude -180 to 180. |

Place URLs are treated as the requested profile source. Supplied URLs take precedence over generated searches.

#### Results and filters

| Input | Description |
| --- | --- |
| **maxItems** | Maximum unique business records across the run (default 10; maximum 100). |
| **page / maxPages** | Starting result batch and maximum batches per search (defaults: 1 and 3). Page supports offsets up to 100; maxPages supports up to 25 batches. |
| **deduplicate** | Keep one row per place identity (default true). |
| **keyword** | Keep records whose visible name, category, address, or description contains this text. |
| **category** | Keep records whose primary category contains this text. |
| **country** | Keep records whose visible place text contains this country. |
| **minRating / minReviewCount** | Minimum visible rating (0–5) and review count. Places without the values do not pass the filters. |
| **sortBy** | Keep Maps relevance order, or sort by rating, review count, or name. |

#### Optional profile details

| Input | Description |
| --- | --- |
| **includeDetails** | Open selected Maps profiles for additional contact, hours, and business attributes (default false). |
| **maxDetailItems** | Maximum profiles to open (default 3; maximum 50). |
| **includeMedia** | Include visible business photos and image details (default true). |

#### Page settings

| Input | Description |
| --- | --- |
| **useBrowser** | Render dynamic Maps pages in a standard browser (default true). When disabled, only information available in static HTML can be collected. |
| **proxyConfiguration** | Optional Apify proxy settings for browser navigation. |

### Dataset

Each row includes the place name and canonical Google Maps URL. Depending on the source, a record may also include:

- **Place identity:** place ID, feature ID, and Knowledge Graph ID.
- **Location:** latitude, longitude, coordinate pair, Plus Code, address, and address parts when the displayed address can be parsed clearly.
- **Contact:** phone number, website, and website domain.
- **Public profile:** category, description, rating, review count, price range, hours, current status, service and accessibility attributes.
- **Links and images:** menu, ordering, and reservation links, plus public business photos and photo categories.
- **Coordinate source:** whether coordinates came from the public Maps place URL.

```json
{
  "name": "Example Cafe",
  "normalizedName": "example cafe",
  "primaryCategory": "Coffee shop",
  "categories": ["Coffee shop"],
  "address": "10 Example Street, Seattle, WA 98101, United States",
  "formattedAddress": "10 Example Street, Seattle, WA 98101, United States",
  "latitude": 47.61,
  "longitude": -122.33,
  "location": {
    "lat": 47.61,
    "lng": -122.33
  },
  "plusCode": "8R84+2X Seattle",
  "phone": "+1 206-555-0100",
  "website": "https://example.com/",
  "rating": 4.7,
  "reviewCount": 314,
  "currentStatus": "Open · Closes 5 pm",
  "openingHours": [
    { "day": "Monday", "hours": "7 am–5 pm" }
  ],
  "canonicalUrl": "https://www.google.com/maps/place/Example+Cafe/"
}
```

The example is illustrative; Maps may not expose every field for each place. If details are enabled, records can include expanded hours, accessibility, service options, and business attributes. Download the dataset from the Apify run page in JSON, CSV, Excel, or another supported format. Run totals and source outcomes are available in the run output.

### Limits and troubleshooting

Google Maps may show different results by query, location, and time. Result cards can be brief, and some place details may require a rendered page. If a run is empty or partial, check the run log and summary for access boundaries or unavailable pages.

The Actor uses public Google Maps pages and does not bypass CAPTCHAs or other access controls. A failed or empty source does not create a dataset row.

### Privacy

The Actor sends search phrases, addresses, coordinates, and supplied Maps URLs to Google Maps. Avoid submitting sensitive locations. This independent Actor is not affiliated with Google.

# Actor input Schema

## `startUrls` (type: `array`):

Public Google Maps search or place URLs. Place URLs are treated as the requested profile source.

## `placeUrls` (type: `array`):

Compatibility alias for public Google Maps URLs.

## `sourceUrls` (type: `array`):

Compatibility alias for public Google Maps URLs.

## `searchUrls` (type: `array`):

Compatibility alias for public Google Maps URLs.

## `urls` (type: `array`):

Compatibility alias for public Google Maps URLs.

## `queries` (type: `array`):

Public Google Maps place searches.

## `query` (type: `string`):

Compatibility alias for one search query.

## `searchQuery` (type: `string`):

Compatibility alias for one search query.

## `addresses` (type: `array`):

Public addresses converted into ordinary Google Maps searches.

## `coordinates` (type: `array`):

Coordinate pairs converted into ordinary public Maps URLs.

## `maxItems` (type: `integer`):

Global cap on unique business records returned.

## `page` (type: `integer`):

One-based starting Maps feed batch; Maps is advanced only by ordinary visible-feed scrolling.

## `maxPages` (type: `integer`):

Maximum visible feed batches to inspect for each search URL.

## `maxDetailItems` (type: `integer`):

Maximum number of search results to open for optional profile enrichment when includeDetails is enabled.

## `includeDetails` (type: `boolean`):

Open up to maxDetailItems public place pages to collect visible contact, hours, attributes, and profile facts. Disabled by default.

## `includeMedia` (type: `boolean`):

Include distinct visible Google-hosted business photos and image dimensions when available.

## `deduplicate` (type: `boolean`):

Keep one row per visible place identity across sources.

## `keyword` (type: `string`):

Optional case-insensitive filter across visible business name, category, address, and description.

## `category` (type: `string`):

Optional case-insensitive filter on the public primary category.

## `country` (type: `string`):

Optional case-insensitive filter on visible place text.

## `minRating` (type: `number`):

Return places with a visible Maps rating at or above this value.

## `minReviewCount` (type: `integer`):

Return places with a visible review count at or above this value.

## `sortBy` (type: `string`):

Order returned places by source relevance, rating, review count, or name.

## `useBrowser` (type: `boolean`):

Use ordinary headless browser rendering for dynamic public Maps results. When disabled, only source data present in static HTML is available.

## `requestTimeoutSecs` (type: `integer`):

Maximum navigation time for each public Maps page.

## `maxRequestRetries` (type: `integer`):

Retry count after transient request failures; access challenges are not retried.

## `requestDelayMs` (type: `integer`):

Polite pause before requests and feed scrolls.

## `browserWaitMs` (type: `integer`):

Wait for visible public page content after navigation or a normal tab click.

## `maxResponseBytes` (type: `integer`):

Bound for the optional static HTML response when browser rendering is disabled.

## `userAgent` (type: `string`):

Optional ordinary User-Agent header; no stealth or fingerprint evasion is used.

## `proxyConfiguration` (type: `object`):

Optional Apify proxy settings for browser navigation. Leave unset to use the ordinary direct connection.

## Actor input object example

```json
{
  "maxItems": 10,
  "page": 1,
  "maxPages": 3,
  "maxDetailItems": 3,
  "includeDetails": false,
  "includeMedia": true,
  "deduplicate": true,
  "sortBy": "relevance",
  "useBrowser": true,
  "requestTimeoutSecs": 30,
  "maxRequestRetries": 1,
  "requestDelayMs": 250,
  "browserWaitMs": 1500,
  "maxResponseBytes": 2000000
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `runHealth` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("googleapi/google-maps-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("googleapi/google-maps-geocoding-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call googleapi/google-maps-geocoding-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-maps-geocoding-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/pc3fve3uWfDoOscPb/builds/bKaUmdmrv7SQ8MlPw/openapi.json