Google Geocoding Scraper

Geocode addresses and reverse geocode coordinates using Google's Geocoding API. Forward geocoding turns an address into coordinates plus structured address components; reverse geocoding turns a coordinate into formatted addresses. Returns place IDs, location type, result types, recommended viewport, bounding box, and plus codes. No Google API key required: the actor ships with a self-rotating pool of working Google keys.

Why use this scraper?

• No Google API key needed: a built-in pool of 39 working keys rotates automatically, with health tracking and cooldown.
• Forward geocoding: address or place description to latitude/longitude plus structured components.
• Reverse geocoding: latitude/longitude to formatted addresses and components.
• Structured address breakdown: street number, street, city, state and state code, country and country code, postal code, neighborhood, sublocality, plus the full raw component list.
• Rich result metadata: Google Place ID, location type (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE), result types, recommended viewport, precise bounding box, and plus codes.
• Component filtering: restrict forward results by country, postal code, locality, and more.
• Region biasing: bias forward results toward a country's region (ccTLD).
• Viewport biasing: bias forward results toward a bounding box.
• Reverse filters: narrow reverse results by result type and location type.
• Localization: return addresses in any supported language.
• Concurrent batch processing with configurable concurrency.
• One dataset record per query, with graceful per-query handling of empty and invalid inputs.

Use cases

• Bulk convert lists of addresses into coordinates for mapping and analytics.
• Reverse geocode GPS traces or device coordinates into human-readable addresses.
• Normalize and standardize messy address data into structured fields.
• Enrich CRM, spreadsheet, or catalog records with lat/lng, place IDs, and postal codes.
• Validate addresses and flag ambiguous or partial matches.
• Localize place names across multiple languages.

How to use

Forward geocode an address

{
  "addresses": ["1600 Amphitheatre Parkway, Mountain View, CA"]
}

Forward geocode multiple addresses

{
  "addresses": ["Eiffel Tower, Paris", "Sydney Opera House", "Brandenburg Gate, Berlin"]
}

Reverse geocode coordinates

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

Restrict results to a country (components filter)

{
  "addresses": ["Paris"],
  "components": "country:US"
}

Bias results toward a region

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

Localize the output language

{
  "addresses": ["Munich, Germany"],
  "language": "de"
}

Bias forward results to a viewport (bounds)

{
  "addresses": ["Springfield"],
  "bounds": "39.0,-90.0|40.0,-89.0"
}

Filter reverse results by type

{
  "latlngs": ["40.748817,-73.985428"],
  "resultType": "street_address",
  "locationType": "ROOFTOP"
}

Forward and reverse in one run, with tuned concurrency

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

Input

Field	Type	Default	Description
addresses	string[]		Addresses or place descriptions to forward geocode into coordinates
latlngs	string[]		Coordinates as lat,lng strings to reverse geocode into addresses
language	string		Response language (e.g. en, ja, de, fr)
region	string		ccTLD region bias for forward geocoding (e.g. us, gb, de)
components	string		Forward component filter, e.g. country:US or country:US|postal_code:94043
bounds	string		Forward viewport bias as swLat,swLng|neLat,neLng
resultType	string		Reverse result-type filter, e.g. street_address|locality
locationType	string		Reverse location-type filter, e.g. ROOFTOP|APPROXIMATE
maxConcurrency	number	10	Maximum number of queries processed in parallel (1-50)
proxyConfiguration	object	direct	Optional proxy. The official keyed API rarely needs one; leave disabled unless required

At least one of addresses or latlngs is required. The language, region, components, and bounds parameters apply to all forward queries; resultType and locationType apply to all reverse queries.

Output

One record per query in the default dataset. Each record:

Field	Type	Description
query	string	The input address (forward) or lat,lng (reverse)
mode	string	forward or reverse
status	string	OK, ZERO_RESULTS, INVALID_REQUEST, or ERROR
errorMessage	string	Present only when the request failed or was rejected
results	array	Matched results; empty for ZERO_RESULTS and error statuses

Each item in results:

Field	Type	Description
address	string	Formatted address
placeId	string	Google Place ID
lat / lng	number	Coordinates
locationType	string	ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, or APPROXIMATE
types	string[]	Result types (e.g. street_address, premise, locality)
components	object	Structured address parts (see below)
viewport	object	Recommended map viewport with ne and sw corners
bounds	object	Precise bounding box, when Google provides one
partialMatch	boolean	true when Google returned an approximate or partial match
plusCode	object	globalCode and compoundCode, when available
postcodeLocalities	string[]	Localities within a postal code, when available

components contains: streetNumber, street, city, state, stateCode, country, countryCode, postalCode, neighborhood, sublocality, administrativeAreaLevel2, and raw (every Google address component with longName, shortName, and types). Absent fields are omitted from the output.

Forward output (live data)

{
  "query": "1600 Amphitheatre Parkway, Mountain View, CA",
  "mode": "forward",
  "status": "OK",
  "results": [
    {
      "address": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "lat": 37.4224864,
      "lng": -122.0855962,
      "locationType": "ROOFTOP",
      "types": ["premise", "street_address"],
      "components": {
        "streetNumber": "1600",
        "street": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "California",
        "stateCode": "CA",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "94043",
        "raw": ["...full Google address_components..."]
      },
      "viewport": {
        "ne": { "lat": 37.4238679802915, "lng": -122.0842176197085 },
        "sw": { "lat": 37.4211700197085, "lng": -122.0869155802915 }
      },
      "partialMatch": false
    }
  ]
}

Reverse output (live data)

Reverse geocoding returns multiple results from most specific to least specific (16 for the coordinate below). The first result, trimmed:

{
  "query": "40.748817,-73.985428",
  "mode": "reverse",
  "status": "OK",
  "results": [
    {
      "address": "W 34 St & 5 Av, New York, NY 10001, USA",
      "lat": 40.7488509,
      "lng": -73.9852755,
      "types": ["intersection"],
      "components": {
        "city": "New York",
        "stateCode": "NY",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "10001",
        "raw": ["...full Google address_components..."]
      }
    }
  ]
}

Statuses

• OK: one or more results returned.
• ZERO_RESULTS: the query was valid but matched nothing (empty results).
• INVALID_REQUEST: the query was malformed (e.g. an unparseable coordinate); errorMessage explains why.
• ERROR: the request could not be completed after the key pool was exhausted; errorMessage has details.

Development

npm install
npm test          # unit tests (vitest)
npm run typecheck # tsc --noEmit
npm run dev       # run locally with storage/key_value_stores/default/INPUT.json