# Google Earth Location Coordinate Finder (`nimbryxo-studio/google-earth-location-coordinate-finder`) Actor

Look up precise latitude/longitude coordinates, place names, short descriptions and Google's internal place IDs for any place name or address, one result per query, as resolved by Google Earth's own location search.

- **URL**: https://apify.com/nimbryxo-studio/google-earth-location-coordinate-finder.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Automation, Travel, Real estate
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 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/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

## Google Earth Location Coordinate Finder

Resolve place names, street addresses, postal codes, coordinate strings and public Google Earth URLs into precise latitude/longitude, Google place IDs, terrain elevation, matched addresses, place-card details and ready-to-import KML.

The actor talks to the same public Google Earth web endpoints that earth.google.com uses in a browser. You do not need a Google Maps API key, a Google Cloud account, cookies or a proxy setup.

### What this actor does

- **Search by text** - one query returns Google Earth's best match by default, and you can raise the per-query limit to collect every ranked match.
- **Search a region** - optional north/south/east/west bounds bias Google Earth's ranking to a city or country, so a generic query like `KFC` returns local branches.
- **Switch language** - place names, descriptions and details come back in the language you select.
- **Resolve Earth URLs** - paste public `earth.google.com/web` URLs. Search URLs are resolved; resolved view URLs with a `data=` token also unlock the place knowledge card.
- **Terrain elevation** - every coordinate can be enriched with ground elevation in metres above sea level.
- **Address matching** - Google's suggestion results are matched to search results when the match is unambiguous.
- **Place-card details** - for resolved URLs with a feature token: long description, full address, plus code, official website, Wikipedia link, photos and opening hours.
- **KML output** - optionally include a KML Placemark string on every record for QGIS, Google Earth or another GIS tool.
- **No empty fields** - values Google does not provide are omitted, never emitted as `null`, `""`, `[]` or a sentinel.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `search` | `search` for text queries, `byUrls` for Google Earth URLs. |
| `searchQueries` | string list | `["Eiffel Tower"]` prefill | Place names, addresses, postal codes or `lat,lon` strings. (mode=search) |
| `startUrls` | URL list | - | Public earth.google.com/web URLs. (mode=byUrls) |
| `maxItems` | integer | 100 | Global cap on saved records. The daily prefill uses 1. |
| `maxResultsPerQuery` | integer | 1 | Matches saved per query (1-200). The `rank` field keeps Google's original order. |
| `language` | select | `en` | Language for names, descriptions and details. |
| `searchArea` | object | world | Optional `{north, south, east, west}` bounds for search. |
| `includeAddress` | boolean | true | Match a street address when Google's suggestions are unambiguous. |
| `includeElevation` | boolean | true | Add `elevation_meters` (terrain elevation above sea level). |
| `includeKml` | boolean | false | Add a generated `kml` Placemark string. |

The smallest daily run is the prefill: one English query, one result, address/elevation/KML enrichment off. It makes a single search request and returns one record.

Older task inputs that used `query`, `queries`, `maxResults`, `minDelayBetweenRequests` or `maxDelayBetweenRequests` still run: those keys are read in code and mapped to the current fields or pacing. They are not shown in the input form.

#### Example: landmarks

```json
{
  "mode": "search",
  "searchQueries": ["Eiffel Tower", "Statue of Liberty", "Taj Mahal"],
  "maxResultsPerQuery": 1,
  "includeElevation": true
}
```

#### Example: all matches for a chain

```json
{
  "mode": "search",
  "searchQueries": ["KFC"],
  "searchArea": {"north": 41.0, "south": 40.4, "east": -73.5, "west": -74.3},
  "maxResultsPerQuery": 50,
  "maxItems": 100
}
```

#### Example: resolved Google Earth URL

```json
{
  "mode": "byUrls",
  "startUrls": [
    {"url": "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"}
  ],
  "includeElevation": true,
  "includeKml": true
}
```

### Output per location

Legacy fields are unchanged:

- `search_query` - the query text, or the source URL in `byUrls` mode
- `place_name` - the resolved place name
- `latitude`, `longitude` - the resolved coordinates (WGS84)
- `description` - Google Earth's short description, e.g. `Tower in Paris, France`
- `google_place_id` - Google's place identifier (`0x...:0x...`)
- `data_source` - `search_api` for a search response, `url_fallback` for a URL-derived record
- `url` - a Google Earth URL for the resolved location
- `scraped_at` - ISO 8601 UTC timestamp

New fields are added beside them:

- `elevation_meters` - terrain elevation above sea level, when available
- `address` - matched street address, when unambiguous
- `rank` - original position in Google's result list
- `language` - language used for the response
- `record_type` - `location`
- `kml` - generated KML Placemark, when `includeKml` is on

For `byUrls` records with a feature token, the place knowledge card can also add:

- `feature_id` - Google Knowledge Graph id (`/m/...` or `/g/...`)
- `description_long` - the longer place description
- `plus_code`, `plus_code_local`
- `website`, `website_domain`
- `wikipedia_url`
- `photos` - Google-hosted photo URLs
- `opening_hours` - day-to-hours object
- `google_maps_url`
- `camera_altitude_meters`, `camera_distance_meters`, `field_of_view_degrees`, `heading_degrees`, `tilt_degrees`, `roll_degrees`, `camera_text` - camera values read from the URL

### Use cases

- **GIS data collection** - bulk-resolve place names into coordinates and elevation for maps and terrain models.
- **Travel research** - get exact coordinates, addresses and opening hours for landmarks and venues.
- **Location intelligence** - attach Google place IDs and coordinates to a list of business names or addresses.
- **Dataset enrichment** - add latitude, longitude, elevation and a place ID to records that only have a name.
- **Franchise mapping** - resolve many branches of the same chain, optionally biased to a city or region.
- **KML handoff** - export a ready-to-import Placemark for each record.

### FAQ

**Do I need a Google Maps API key?** No. The actor uses the public endpoints behind earth.google.com and never asks you for a key.

**Why did a query return no record?** Google Earth could not resolve that text to a location. A typo, a very vague query, an unsupported script, or a temporary rate limit can all cause this. The run summary reports how many inputs were unresolved.

**Why does one query return only one record?** That is the default. Set `maxResultsPerQuery` above 1 to collect every ranked match. Google Earth itself may return fewer matches than you ask for.

**Why is `address` missing on some records?** An address is added only when Google's suggestion results identify the same place unambiguously. Common names such as `KFC` can match many branches, so the actor omits the address instead of guessing.

**Why can't I see website, photos or opening hours for a search result?** Google Earth's search response exposes coordinates, place IDs and short descriptions. The full place card requires a feature id, which Google only exposes in a resolved view URL. Use `mode=byUrls` with a resolved Earth URL to get the full card.

**What is the difference between `search_api` and `url_fallback`?** `search_api` means the record came from Google Earth's search response. `url_fallback` means the record came from a URL you supplied (a resolved view, a coordinate URL, or a search URL resolved through the API).

**Are the coordinates survey-grade?** No. They are the coordinates Google Earth resolves for the place, typically accurate to a few metres for landmarks but not a survey measurement.

**Does this work in any language?** The 32 most common Google Earth interface languages are available. Google may fall back to English for places that have no localized name.

**Is this affiliated with Google?** No. This is an independent, third-party actor that reads Google Earth's public location search and place card data. It is not operated by or affiliated with Google.

### Limitations

- Google Earth may cap the number of matches for a broad query; the actor stops when the source stops returning a next page.
- Place-card details (website, photos, hours, plus code) are only available for resolved URLs that contain a feature token, or when Google exposes a matching card.
- Some official venue websites block automated link checks. Their URLs are still the real website URLs Google publishes.
- Coordinates and names can change over time as Google updates its data.
- Broad queries are ranked by Google Earth, not by the actor. Use a specific query or `searchArea` for predictable local results.

# Actor input Schema

## `mode` (type: `string`):

Choose whether to search by text or resolve Google Earth URLs. (mode=search / mode=byUrls)

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

Place names, addresses, postal codes or coordinate strings to search on Google Earth. (mode=search) Each query returns one result by default; raise 'Results per query' to collect more. Use specific queries such as 'KFC New York' for a particular branch.

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

Public earth.google.com/web URLs to resolve. A URL can contain a search text, a resolved view with coordinates and a data token, or both. URLs with a data token also unlock the place knowledge card (address, website, Wikipedia, photos and opening hours). (mode=byUrls)

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

Global cap on the number of location records saved across all queries or URLs.

## `maxResultsPerQuery` (type: `integer`):

How many Google Earth matches to save for each search query. The default of 1 keeps the exact-name match. Raise it to collect every ranked match; the 'rank' field preserves Google's original order.

## `language` (type: `string`):

Language used for place names, descriptions and details returned by Google Earth.

## `searchArea` (type: `object`):

Optional north/south/east/west bounding box that biases Google Earth's ranking toward a region. Leave it unset to search worldwide. All four bounds are recommended; missing bounds fall back to the world.

## `includeAddress` (type: `boolean`):

Add a street address when Google's suggestion results identify the same place unambiguously. Adds one lightweight request per query.

## `includeElevation` (type: `boolean`):

Add terrain elevation in metres above sea level for every resolved coordinate, using Google Earth's public elevation service.

## `includeKml` (type: `boolean`):

Add a ready-to-import KML Placemark string to every record. Useful for opening the results in Google Earth, QGIS or other GIS tools.

## Actor input object example

```json
{
  "mode": "search",
  "searchQueries": [
    "Eiffel Tower",
    "1600 Pennsylvania Avenue NW, Washington, DC",
    "48.8584, 2.2945"
  ],
  "maxItems": 1,
  "maxResultsPerQuery": 1,
  "language": "en",
  "includeAddress": false,
  "includeElevation": false,
  "includeKml": false
}
```

# Actor output Schema

## `locations` (type: `string`):

Dataset containing all resolved Google Earth locations.

# 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 = {
    "mode": "search",
    "searchQueries": [
        "Eiffel Tower"
    ],
    "maxItems": 1,
    "maxResultsPerQuery": 1,
    "language": "en",
    "includeAddress": false,
    "includeElevation": false,
    "includeKml": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/google-earth-location-coordinate-finder").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 = {
    "mode": "search",
    "searchQueries": ["Eiffel Tower"],
    "maxItems": 1,
    "maxResultsPerQuery": 1,
    "language": "en",
    "includeAddress": False,
    "includeElevation": False,
    "includeKml": False,
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/google-earth-location-coordinate-finder").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 '{
  "mode": "search",
  "searchQueries": [
    "Eiffel Tower"
  ],
  "maxItems": 1,
  "maxResultsPerQuery": 1,
  "language": "en",
  "includeAddress": false,
  "includeElevation": false,
  "includeKml": false
}' |
apify call nimbryxo-studio/google-earth-location-coordinate-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/google-earth-location-coordinate-finder"
        }
    }
}
```

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/DmHPH9fVzMr9I6BsE/builds/GITDHS0K1DnBKj5Cf/openapi.json