# Google Earth Scraper (`googleapi/google-earth-scraper`) Actor

Resolve public Google Earth searches into coordinates, camera geometry, feature identifiers and matched public place-card descriptions, addresses and website links when exposed.

- **URL**: https://apify.com/googleapi/google-earth-scraper.md
- **Developed by:** [Google API](https://apify.com/googleapi) (community)
- **Security:** Limited permissions
- **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

### What does Google Earth Scraper do?

This Actor resolves public [Google Earth](https://earth.google.com/web/) place searches and Earth /web URLs into coordinates, camera geometry, a reusable Earth view URL, and any feature identifier explicitly present in the resolved URL. It returns one location per successful query; it is not a business directory or an exhaustive nearby-place listing.

Google Earth documents searches for place names, addresses, postal codes, and coordinate strings. The Actor uses the public search route and the normal keyboard accessibility affordance to read the displayed Inspector card. It preserves available full description text and clean paragraph HTML, address, plus code, place website and Wikipedia links only when the card title matches the query. It never reverse-geocodes the point, reads private Flutter state, borrows browser cookies or follows external links. Already-resolved input URLs retain the URL-only path without extra network requests.

### Why use Google Earth Scraper?

- Resolve multiple place queries in one bounded run.
- Start from a public Google Earth search URL or resolved-view URL.
- Keep exact decimal precision, Earth camera values, and token-based feature identity together.
- Export location records and review run summaries for empty or unavailable results.

Use Apify scheduling, API access, integrations, and run history to automate collection. An optional Apify proxy can be used for public navigation. If Google blocks or cannot resolve a request, the run stops and the summary reports the issue; the Actor does not sign in, solve CAPTCHAs, or bypass access controls. Coordinates and camera fields alone do not constitute a complete place profile.

### What data can Google Earth Scraper extract?

| Group | Fields |
|---|---|
| Place/query label | placeName, requestedPlaceName, earthSearchText, resolvedPlaceName |
| Feature identity | googleEarthFeatureId, featureIdFormat, featureIdentity, googleEarthFeatureNamespace, googleEarthFeatureHexId, googleMapsCid |
| Coordinates | latitude, longitude, coordinates, coordinatePrecision, hemisphere labels, mapCenterText, coordinateSystem |
| Camera | altitudeMeters, cameraDistanceMeters, fieldOfViewDegrees, headingDegrees, tiltDegrees, rollDegrees, camera, cameraText, elevationUnit |
| Earth link | earthUrl, canonicalEarthUrl, earthHost, earthPath, dataToken, dataTokenLength, publicProduct |
| Source-exposed flags | hasFeatureIdentity, hasCamera, hasDataToken |
| Matched public place card | resolvedPlaceName, description, descriptionHtml, address, plusCode, websiteUrl, wikipediaUrl |

The altitudeMeters value is the camera eye-altitude encoded in the URL, not terrain elevation. earthSearchText is decoded from the resolved URL's search path and is not a verified feature title. resolvedPlaceName is populated only from a matched Inspector heading, never the opaque token. placeName uses that heading when available and otherwise remains a convenience query label. Unavailable card details are omitted. Clean descriptionHtml represents the accessible text as paragraphs; it is not the original canvas markup. Card fields, coordinate aliases, camera settings and repeated text/HTML do not guarantee more than 20 independent place facts.

### How to scrape Google Earth

1. Open the Input tab and enter one or more place names, addresses, or coordinate strings in searchQueries.
2. Optionally provide public Earth /web URLs in startUrls; these take precedence over generated searches.
3. Set `maxItems`, then start the Actor.
4. Inspect resolved records in the Dataset tab and the run summary in the Output tab.

maxItems is global across inputs. Google Earth search here resolves one location per query and has no pageable result list, so page and maxPages are fixed to 1. With both query aliases present, non-empty searchQueries takes precedence over queries.

### How much will it cost to scrape Google Earth?

Run cost depends on the number of place searches and the selected Apify compute allocation. A resolved Earth URL does not require a search. Start with a small `maxItems` value, then increase it as needed. This Actor does not quote a fixed price.

### Input

| Field | Type | Default / limits | Meaning |
|---|---|---|---|
| searchQueries | string array | \["Eiffel Tower"], up to 100 | Place names, addresses, or coordinate strings |
| queries | string array | optional, up to 100 | Compatibility alias |
| startUrls | URL-source array | optional, up to 100 | Public Earth /web search or resolved URLs; overrides query inputs |
| maxItems | integer | 100, range 1–100 | Global location cap |
| maxResults | integer | optional, range 1–100 | Alias for maxItems |
| page, maxPages | integer | fixed at 1 | Earth location resolution is not a paginated listing |
| proxyConfiguration | object | optional | Existing Apify proxy applied to the complete fresh browser context |

### Output

Each dataset row represents one resolved location and includes its coordinates, camera settings, and Earth URL, plus a feature identity or place-card details when available. A failed query, empty result, or access boundary is reported in the run summary and logs rather than added as a location record.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

The following example shows a resolved Earth URL. Coordinates and camera values come from the URL; a separate place-title card is not inferred.

```json
{
  "requestedPlaceName": "Eiffel Tower",
  "earthSearchText": "Eiffel Tower",
  "resolvedPlaceName": null,
  "placeName": "Eiffel Tower",
  "googleEarthFeatureId": "/m/02j81",
  "googleEarthFeatureNamespace": null,
  "googleEarthFeatureHexId": null,
  "googleMapsCid": null,
  "featureIdFormat": "google_knowledge_graph_mid",
  "featureIdentity": {
    "featureId": "/m/02j81",
    "format": "google_knowledge_graph_mid",
    "namespace": null,
    "hexId": null,
    "mapsCid": null
  },
  "latitude": 48.8583701,
  "longitude": 2.2944813,
  "coordinates": {
    "latitude": 48.8583701,
    "longitude": 2.2944813,
    "altitudeMeters": 146.9105192,
    "coordinateSystem": "WGS84"
  },
  "altitudeMeters": 146.9105192,
  "cameraDistanceMeters": 533.29335005,
  "fieldOfViewDegrees": 35,
  "headingDegrees": 0,
  "tiltDegrees": 0,
  "rollDegrees": 0,
  "camera": {
    "altitudeMeters": 146.9105192,
    "distanceMeters": 533.29335005,
    "fieldOfViewDegrees": 35,
    "headingDegrees": 0,
    "tiltDegrees": 0,
    "rollDegrees": 0,
    "angleUnit": "degrees",
    "distanceUnit": "meters"
  },
  "coordinatePrecision": 7,
  "latitudeHemisphere": "N",
  "longitudeHemisphere": "E",
  "mapCenterText": "48.8583701, 2.2944813",
  "cameraText": "146.9105192a,533.29335005d,35y,0h,0t,0r",
  "earthUrl": "https://earth.google.com/web/search/Eiffel+Tower/@48.8583701,2.2944813,146.9105192a,533.29335005d,35y,0h,0t,0r/data=CjoaDAoIL20vMDJqODEYAiImCiQJME-ZgofyPUARME-ZgofyPcAZ26Y5nC09S0AhQYot7SnSTMBCAggBQgIIAEoNCP___________wEQAA",
  "canonicalEarthUrl": "https://earth.google.com/web/search/Eiffel+Tower/@48.8583701,2.2944813,146.9105192a,533.29335005d,35y,0h,0t,0r/data=CjoaDAoIL20vMDJqODEYAiImCiQJME-ZgofyPUARME-ZgofyPcAZ26Y5nC09S0AhQYot7SnSTMBCAggBQgIIAEoNCP___________wEQAA",
  "dataToken": "CjoaDAoIL20vMDJqODEYAiImCiQJME-ZgofyPUARME-ZgofyPcAZ26Y5nC09S0AhQYot7SnSTMBCAggBQgIIAEoNCP___________wEQAA",
  "dataTokenLength": 106,
  "publicProduct": "Google Earth",
  "earthHost": "earth.google.com",
  "earthPath": "/web/search/Eiffel+Tower/@48.8583701,2.2944813,146.9105192a,533.29335005d,35y,0h,0t,0r/data=CjoaDAoIL20vMDJqODEYAiImCiQJME-ZgofyPUARME-ZgofyPcAZ26Y5nC09S0AhQYot7SnSTMBCAggBQgIIAEoNCP___________wEQAA",
  "coordinateSystem": "WGS84",
  "elevationUnit": "meters",
  "hasFeatureIdentity": true,
  "hasCamera": true,
  "hasDataToken": true
}
```

### Tips and responsible use

Use exact coordinate searches when you need a known point rather than relying on a place-name search. Coordinate precision reflects the URL text and does not claim survey accuracy. If the page cannot resolve a coordinate URL, check the run summary and logs; the Actor does not substitute a guessed location.

Google Earth is a Google product. This Actor is not affiliated with Google. Respect Google's terms, robots guidance, rate limits, privacy expectations, and applicable law. Search phrases can include personal addresses; provide only information you are authorized to process. Report bugs through the Actor's Issues tab with the run ID and a brief description.

# Actor input Schema

## `searchQueries` (type: `array`):

Place names, addresses, or coordinate strings searched in the public Google Earth application.

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

Optional compatibility alias for searchQueries. If both are supplied, non-empty searchQueries takes precedence.

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

Optional public earth.google.com/web search or resolved-view URLs. When present, these take precedence over searchQueries.

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

Maximum number of distinct resolved location records across all supplied queries or URLs.

## `maxResults` (type: `integer`):

Compatibility alias for maxItems. If both are supplied, maxItems takes precedence.

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

Google Earth resolves one location per query and does not expose a pageable result list; this Actor supports page 1 only.

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

Pagination is not applicable to a single resolved Earth view; this Actor supports one page per query.

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

Optional existing Apify proxy applied to all requests in the fresh ordinary browser context. Proxy initialization failures never fall back to direct requests; the run stops at an access boundary without rotation.

## Actor input object example

```json
{
  "searchQueries": [
    "Eiffel Tower"
  ],
  "maxItems": 100,
  "page": 1,
  "maxPages": 1
}
```

# Actor output Schema

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

Coordinates, camera geometry, Earth URLs, and any feature identifier disclosed in the public page URL.

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

Record counts, request totals, failure-code tallies, limits, and completion time.

## `runHealth` (type: `string`):

Failure and access-boundary tallies. Failures are never written as dataset rows.

# 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-earth-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-earth-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-earth-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-earth-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/kSZHe4LhFkZtvkgrc/builds/uG6cAQyXPfVWKQEgx/openapi.json