Use Google Maps Top List & Ranked Places Extractor with Python

Pull the ranked places from a Google Maps Top list query like 'Top hotels in Paris', or from a list/search URL, with optional full place-page enrichment.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "countryCodes": [],
  "enrichDetails": false,
  "excludeCategories": [],
  "hasPhone": false,
  "hasWebsite": false,
  "includeCategories": [],
  "includeClosed": true,
  "language": "en",
  "location": "",
  "maxRating": 5,
  "maxResults": 3,
  "maxReviews": 0,
  "minRating": 0,
  "minReviews": 0,
  "nameFilter": "",
  "openNow": false,
  "queries": [
    "Top hotels in Paris"
  ]
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	optional	Use 'topList' for ranked queries like 'Top hotels in Paris'. Use 'listUrl' for a shared Google Maps list link or a Maps search URL.
`queries`	array	optional	Ranked list queries. For example: 'Top hotels in Paris', 'Best coffee in Brooklyn', 'Things to do in Tokyo'. Each query is scraped separately.
`location`	string	optional	Optional city, neighborhood or region appended to every query when it is not already mentioned.
`listUrls`	array	optional	Public Google Maps shared-list links (google.com/maps/placelists/list/...) or Maps search URLs. Short maps.app.goo.gl links are resolved automatically.
`maxResults`	integer	optional	Maximum places to return per query or list. The public feed may expose fewer; lists are returned up to the source window.
`enrichDetails`	boolean	optional	Adds Plus Code, rating histogram, photos, amenities, price range, booking links, closure state and hotel details. Turn it off for the fastest, smallest runs using list-feed data only.
`language`	string	optional	Google Maps interface language. Names, categories, addresses and hours are localized.
`minRating`	number	optional	Drop places with a lower rating or no published rating.
`maxRating`	number	optional	Drop places with a higher rating.
`minReviews`	integer	optional	Drop places with fewer reviews or no published review count.
`maxReviews`	integer	optional	Drop places with more reviews.
`openNow`	boolean	optional	Keep only places Google currently marks as open.
`hasWebsite`	boolean	optional	Keep only places with a published website.
`hasPhone`	boolean	optional	Keep only places with a published phone number.
`includeClosed`	boolean	optional	When disabled, permanently closed places are dropped. This needs full place details.
`nameFilter`	string	optional	Keep only places whose name contains this text (case-insensitive).
`excludeCategories`	array	optional	Drop places whose primary or secondary category contains any of these words.
`includeCategories`	array	optional	Keep places whose primary or secondary category contains any of these words.
`countryCodes`	array	optional	Keep places in these two-letter countries, e.g. FR, US, JP. Empty means all countries.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/YpWNF6hudIGBsowV8/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Ranked places from a Google Maps Top list or list/search URL, with rank, rating and optional full place details.

Questions before you run

Which inputs are required?

No top-level fields are marked required in the published schema. Conditional requirements can still apply; check the README.

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build LQuqRWbzWdl2Ey9lU and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.