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:

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

Reverse — two coordinates in French:

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

Place IDs — batch:

{
  "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

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.