Google Geocoding Scraper

Convert addresses to coordinates, or coordinates to structured addresses. Each query produces one Dataset record with its status, matches, normalised address parts, Place IDs, map bounds, and available location metadata.

Choose the geocoding direction

Goal	Query field	Settings that apply
Convert an address or place description to coordinates	addresses	language, region, components, and bounds
Convert coordinates to nearby addresses and geographic areas	latlngs	language, resultType, and locationType

You can submit both query types in one run. Each input occurrence produces its own Dataset record, including repeated queries and queries with no match.

Quick start

Addresses to coordinates

{
  "addresses": [
    "Eiffel Tower, Paris, France",
    "Sydney Opera House, Australia"
  ]
}

Coordinates to addresses

{
  "latlngs": [
    "40.748817,-73.985428",
    "48.8584,2.2945"
  ]
}

Run both query types

{
  "addresses": ["Times Square, New York"],
  "latlngs": ["34.0522,-118.2437"],
  "maxConcurrency": 20
}

Localise and bias an ambiguous place

Use language for the preferred result language and region to influence the ranking of an ambiguous forward query:

{
  "addresses": ["Toledo"],
  "language": "es",
  "region": "es"
}

Restrict a forward query by country and viewport

Use components to restrict eligible results. Use bounds to influence their ranking inside a viewport.

{
  "addresses": ["Springfield"],
  "components": "country:US",
  "bounds": "39.70,-89.80|40.10,-89.40"
}

Filter reverse results

Use resultType and locationType when one coordinate returns more geographic levels than you need:

{
  "latlngs": ["37.4224764,-122.0842499"],
  "resultType": "street_address",
  "locationType": "ROOFTOP"
}

Input

At least one item in addresses or latlngs must contain one or more characters. You can provide both arrays in one run. For compatibility, the Actor does not trim submitted strings or optional text values, so it accepts whitespace-only values. The Actor keeps repeated queries, so each input occurrence has its own output record.

The complete example below combines all forward, reverse, shared, and connection fields. Forward-only settings do not affect coordinate queries, and reverse-only settings do not affect address queries.

Input reference

Field	Type	Default	Applies to	Description
addresses	string[]	none	Forward	Addresses or place descriptions to convert into coordinates.
latlngs	string[]	none	Reverse	Coordinates written as latitude,longitude.
language	string	none	Both	Preferred result language, such as en, ja, de, or fr.
region	string	none	Forward	Country-code region bias, such as us, uk, or de. This changes ranking but is not a strict country filter.
components	string	none	Forward	Component filter such as country:US or country:US|postal_code:94043.
bounds	string	none	Forward	Viewport bias written as southwestLat,southwestLng|northeastLat,northeastLng.
resultType	string	none	Reverse	Pipe-separated result types such as street_address|locality.
locationType	string	none	Reverse	Pipe-separated precision filters such as ROOFTOP|APPROXIMATE.
maxConcurrency	integer	10	Both	Number of queries processed in parallel. Allowed range: 1 to 50.
proxyConfiguration	object	{"useApifyProxy":true}	Both	Optional connection settings for the run.

Forward-only settings are ignored for coordinate queries. Reverse-only settings are ignored for address queries. Shared settings apply to every compatible query in the run.

Output

The default Dataset contains one record for each submitted query. With concurrent work, Dataset order can differ from input order. Match records by query and mode.

Field	Type	Description
query	string	The submitted address or coordinate.
mode	string	forward or reverse.
status	string	OK, ZERO_RESULTS, INVALID_REQUEST, or ERROR.
errorMessage	string	Safe text for INVALID_REQUEST or ERROR. This field is omitted for other statuses.
results	array	Matched locations. This is empty for every non-OK status.

Each result item can contain the fields in this table.

Field	Type	Description
address	string	Formatted address.
placeId	string	Google place identifier.
lat, lng	number	Result coordinates.
locationType	string	ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, or APPROXIMATE.
types	string[]	Result categories. The array can be empty.
components	object	Normalised address parts and the full raw component array.
viewport	object	Recommended map viewport with ne and sw corners.
bounds	object	Precise ne and sw bounds when available.
partialMatch	boolean	True when the result is an approximate or partial match.
plusCode	object	globalCode and compoundCode when available.
postcodeLocalities	string[]	Localities represented by a postal code when available.

components can contain streetNumber, street, city, state, stateCode, country, countryCode, postalCode, neighborhood, sublocality, and administrativeAreaLevel2. Each components.raw[] item contains longName, shortName, and types.

Some records contain many matches or address components. The examples below shorten repeated arrays.

Forward result

This retained Dataset item is unchanged and matches the repository fixture for Eiffel Tower, Paris, France.

Reverse result

This Brooklyn record keeps two matches to show the normalised components, plusCode, and bounds.

Status values

• OK: The query has at least one match.
• ZERO_RESULTS: The query is valid, but no location matched.
• INVALID_REQUEST: Google did not accept the coordinate or filter combination.
• ERROR: This query could not be completed. Other queries in the batch continue.

If every query ends in ERROR, the records are still saved and the run completes successfully. Check status before you use a result.

Several reverse matches

One coordinate can match several geographic levels, such as a street address, neighbourhood, city, region, and country. Use resultType or locationType when you need a narrower result set.

An unexpected forward match

region and bounds change result ranking. They do not make a strict area filter. Use components when you need to restrict eligible forward results.

Every matched result includes its placeId, address, and coordinates.