# Google Maps Address & Coordinate Geocoding Lookup (`vexaloom-labs/google-maps-address-and-coordinate-geocoding`) Actor

Convert addresses to coordinates or coordinates back to addresses using Google Maps, in batch, with structured address components, place IDs, plus codes and place categories.

- **URL**: https://apify.com/vexaloom-labs/google-maps-address-and-coordinate-geocoding.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Developer tools, Real estate
- **Security:** 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 Maps Address & Coordinate Geocoding

Turn addresses, place names, postal codes and Google Place IDs into coordinates — or turn coordinates back into the address Google Maps shows for that spot. Everything runs in one batch, in 35 output languages, with no Google Cloud API key, no browser and no login.

This actor is for data teams, delivery and logistics planners, real-estate analysts and anyone who needs a clean geocoding table from a list they already have.

### What it does

| Mode | Input | Output |
|---|---|---|
| Forward | Address, landmark, business name or postal code | Coordinates, formatted address, address parts, Place ID, Plus Code, time zone |
| Reverse | `lat,lng` coordinate | Nearest address or named place, distance from your point, address parts, Place ID |
| Place ID | Google Place ID (`ChIJ…`) or a Google Maps place URL | The place's address, coordinates, structured parts and Plus Code |
| Mixed | Any combination of the three lists | Each item is resolved by its own type into one dataset |

Choose `mixed` to process addresses, coordinate lines and Place IDs side by side in one dataset.

### Why it is fast and setup-free

The actor reads the same public result payloads the Google Maps web front-end uses. It sends direct HTTP requests, parses the structured JSON, and does not open a browser or call the paid Geocoding API. No key, cookie, account or proxy configuration is needed.

If Google temporarily rate-limits the direct connection, the actor retries and can switch to an Apify datacenter proxy automatically. You do not configure anything.

### Input

| Field | What to provide |
|---|---|
| `mode` | `forward`, `reverse`, `placeId` or `mixed`. Defaults to `forward`. |
| `address` / `addresses` | One address or a list. Place names, landmarks and postal codes work too; add a country bias for ambiguous postal codes. A `lat,lng` line inside the address list is reverse geocoded. |
| `location` / `locations` | One `{ "lat": 40.7484, "lng": -73.9857 }` object or a list. A `"lat,lng"` string is accepted in the list. |
| `placeId` / `placeIds` | One `ChIJ…` Place ID or Google Maps place URL, or a list of them. |
| `language` | One of 35 Google Maps interface languages. Changes the returned names, address format and country names. |
| `country` | Optional ISO 3166-1 alpha-2 country code. The country name is appended to forward queries so an ambiguous address resolves there first. |

| Input | Default | Notes |
|---|---|---|
| `mode` | – | The form starts at `forward`; choose `mixed` for all lists. |
| `address`, `addresses` | – | Forward query or list. |
| `location`, `locations` | – | Reverse coordinate or list. |
| `placeId`, `placeIds` | – | Place ID or Maps URL, one or a list. |
| `language` | `en` | One of the 35 enum values. |
| `country` | – | Empty means no region bias. |

Repeated inputs are geocoded once. Blank lines and duplicate inputs are ignored.

### Output

Every resolved input becomes one row. Fields that Google genuinely does not provide for a row are omitted rather than filled with `null`, `""` or a guess.

| Field | Meaning |
|---|---|
| `mode` | `forward`, `reverse` or `placeId` |
| `inputAddress`, `inputLocation`, `inputPlaceId` | The input this row answers |
| `name` | Place or business name Google returns |
| `formattedAddress` | One-line address |
| `addressComponents` | `streetNumber`, `street`, `neighborhood`, `city`, `state`, `stateCode`, `stateName`, `postalCode`, `country`, `countryCode`, `subpremise` when present |
| `location` | Resolved latitude and longitude |
| `placeId`, `featureId` | Canonical `ChIJ…` Place ID and legacy `0x…:0x…` feature ID |
| `plusCode`, `plusCodeGlobal`, `plusCodeCompound` | Open Location Code forms; checked against the emitted coordinates |
| `timezone` | IANA time zone, e.g. `Europe/Paris` |
| `countryCode` | Top-level ISO country code |
| `categories`, `categoryName` | Google place categories when the result is a place |
| `resultLevel` | `address`, `street`, `postal_code`, `area` or `place` |
| `distanceMeters` | Reverse mode only: distance from your point to the matched place |
| `googleMapsUrl`, `sourceUrl` | Canonical Google Maps link |
| `recordType` | Always `geocode` |
| `scrapedAt` | ISO timestamp |

### Examples

Forward — one address:

```json
{
  "mode": "forward",
  "addresses": ["1600 Amphitheatre Parkway, Mountain View, CA"],
  "language": "en"
}
```

Reverse — two coordinates in French:

```json
{
  "mode": "reverse",
  "locations": [
    { "lat": 48.8583701, "lng": 2.2944813 },
    { "lat": 40.7579, "lng": -73.9855 }
  ],
  "language": "fr"
}
```

Place IDs — batch:

```json
{
  "mode": "placeId",
  "placeIds": [
    "ChIJm-xEoHxZwokRTStZFhfbrKA",
    "https://www.google.com/maps/place/Eiffel+Tower/@48.8583701,2.2944813,17z"
  ],
  "language": "en"
}
```

### FAQ

**Do I need a Google Maps API key?**
No. The actor uses Google Maps' public web result payloads. You do not need a Google Cloud project, billing account or key.

**Can I mix addresses and coordinates in one run?**
Yes. Choose `mode: mixed` and send any combination of the three lists. If `mode` is omitted entirely, the actor also detects which lists are present and processes them together.

**What happens when Google cannot place an address?**
The input is reported in the run status as unresolved and no row is invented. A nearby business or an unrelated street is never presented as the answer.

**Why is reverse geocoding sometimes a street address and sometimes a place name?**
Google returns the nearest addressable entity for that coordinate. In a city centre that is usually a street address; at a landmark it can be the landmark itself. `distanceMeters` tells you how far the matched entity is from your point.

**Which languages are supported?**
English (US and UK), German, French, Spanish (Spain and Latin America), Italian, Portuguese (Brazil and Portugal), Dutch, Polish, Swedish, Danish, Norwegian, Finnish, Czech, Slovak, Hungarian, Romanian, Bulgarian, Greek, Turkish, Russian, Ukrainian, Arabic, Hebrew, Hindi, Thai, Vietnamese, Indonesian, Malay, Japanese, Korean, Chinese (Simplified and Traditional).

**Does the `country` input restrict results to that country?**
It biases forward queries by appending the country name, which is what Google's own address search uses. It is a bias, not a hard filter. Reverse results follow the coordinate.

**What Place ID formats are accepted?**
Any `ChIJ…` Place ID, the `place_id:` prefix, or a full Google Maps place URL. Bare legacy `0x…:0x…` feature IDs cannot be resolved on their own; paste the full Maps URL instead.

**Are Plus Codes checked?**
Yes. Every emitted short Plus Code is verified against the emitted coordinates, or recomputed from them, so the code and the coordinate always describe the same cell.

**How many rows can I geocode?**
There is no batch-size cap in the actor. Large lists are processed with a small concurrency limit and deduplicated. Google may throttle very large bursts; the actor retries and can switch to an Apify proxy automatically.

**Is the data live?**
Each run reads Google Maps at run time. Nothing is cached between runs.

### Limitations

- Fields Google does not publish for a result are omitted, not guessed. For example, an intersection or a postcode-level result may have no street number or time zone.
- Google Maps occasionally answers an ambiguous or partial address with a nearby place that shares part of the query. The actor's match guard rejects answers that do not echo the input, but an address that shares a street name with a different city can still pass.
- Reverse geocoding returns the nearest addressable entity, which can be a named area rather than a building.
- Google's public web payloads can change. The actor pins the current request templates and reports unresolved inputs instead of fabricating rows if the format drifts.
- The actor is an independent tool and is not affiliated with Google. Use it in line with Google Maps' terms and the laws that apply to your data.

### Data source

Public Google Maps web endpoints (`google.com/maps` result payloads). No Google Geocoding API, no API key, no browser, no cookies.

### Local development

```bash
python3 -m pytest -q
apify run --purge --input-file .actor/example-input.json
```

The daily-test prefill is the smallest useful run: one forward address and one line of output.

# Actor input Schema

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

Forward turns an address, place name or postal code into coordinates. Reverse turns a coordinate pair into the nearest address. Place ID resolves a Google Place ID or Maps URL. Mixed processes every list in one run.

## `address` (type: `string`):

One address, landmark, business name or postal code for forward geocoding. Example: 1600 Amphitheatre Parkway, Mountain View, CA.

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

One address, place name or postal code per line. Add a country bias for ambiguous postal codes. A lat,lng line is treated as reverse geocoding.

## `location` (type: `object`):

One reverse-geocoding point as {"lat": 40.7484, "lng": -73.9857}. Decimal degrees, WGS84.

## `locations` (type: `array`):

A list of reverse-geocoding points. Each item is {"lat": 40.7484, "lng": -73.9857} or a "lat,lng" string.

## `placeId` (type: `string`):

One Google Place ID (starts with ChIJ) or a full Google Maps place URL. Returns the place's address, coordinates and structured components.

## `placeIds` (type: `array`):

One Google Place ID or Google Maps place URL per line.

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

Language of the returned names, formatted address and country names. Google Maps translates the result; it does not translate the input.

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

Optional ISO 3166-1 alpha-2 country code. The country name is appended to forward queries so an ambiguous address is resolved in that country first. Leave empty for no bias.

## Actor input object example

```json
{
  "mode": "forward",
  "addresses": [
    "1600 Amphitheatre Parkway, Mountain View, CA"
  ],
  "language": "en",
  "country": ""
}
```

# Actor output Schema

## `geocodingResults` (type: `string`):

Dataset of forward, reverse and Place ID 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_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("vexaloom-labs/google-maps-address-and-coordinate-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# 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("vexaloom-labs/google-maps-address-and-coordinate-geocoding").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": "forward",
  "addresses": [
    "1600 Amphitheatre Parkway, Mountain View, CA"
  ],
  "language": "en"
}' |
apify call vexaloom-labs/google-maps-address-and-coordinate-geocoding --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-address-and-coordinate-geocoding"
        }
    }
}
```

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/cQ4NrxbH6Ta75hska/builds/a4aDrgPfmy323zPS9/openapi.json