Collectors · Local & Maps

Google Events API in Python

Event cards for a query — title, date, venue, address and link. One POST from Python with query, rows back as JSON with 9 fields, $0.002 per delivered event. No proxies or parsers to maintain.

Get an API key See the collector

A Python requests snippet that posts { — A Python requests call to the google_events collector returns one dict per event, at $0.002 each.

First call

Install, call, read the rows.

pip install requests

The only dependency.

import os, requests

r = requests.post(
    "https://api.quanticdata.io/v1/scraper/collectors/google_events/run",
    headers={"Authorization": f"Bearer {os.environ['QD_API_KEY']}"},
    json={
        "query": "concerts in Milan",
        "country": "it",
        "lang": "en",
        "max_results": 10,
    },
    timeout=120,
)
r.raise_for_status()
run = r.json()["payload"]
print(run["count"], "rows,", run["cost"]["usd"], "USD")
for row in run["results"]:
    print(row.get("title"), row.get("date"), row.get("venue"), row.get("address"))

Python: one Google Events run (Concerti a Milano), printing title, date, venue, address

The key comes from an environment variable, never from the code. The run answers in the same request when it finishes in time; payload.results holds the rows and payload.cost what they cost.

Request parameters

What the collector takes.

Input of the Google Events collector
Parameter	Type	Required	Meaning
`query`	string	yes	Event search, e.g. "concerts in Milan".
`location`	string	no	Search as if from this place, e.g. "Milan, Italy".
`country`	string	no	ISO 3166-1 alpha-2 code — proxy exit geo and Google locale (gl). Omit for the default pool.
`lang`	string	no	Interface language (hl), e.g. en, it, de.
`max_results`	integer	no (default 10)	How many events to deliver at most (1–20). You pay only for delivered events.

Response fields

9 fields per event.

Fields of each row (event)
Field	Type	What it holds
`rank`	integer	1-based position.
`title`	string	Event title.
`date`	string, nullable	Date line as shown ("Sat, Aug 22, 7 – 10 PM").
`venue`	string, nullable	Venue name.
`address`	string, nullable	Venue address.
`link`	string, nullable	Event link.
`thumbnail`	string, nullable	Event image.
`kgmid`	string, nullable	Google's entity id of the event.
`query`	string	Echo of the request.

Add ?format=csv to the runs endpoint to get the same rows as CSV.

Long runs

Run in the background, then poll.

A run that needs more time can go to the background: send "async": true, get 202 with the run id, and poll the runs endpoint until the status is done. Reading a run is free.

import os, time, requests

H = {"Authorization": f"Bearer {os.environ['QD_API_KEY']}"}
r = requests.post("https://api.quanticdata.io/v1/scraper/collectors/google_events/run", headers=H,
                  json={**{"query":"concerts in Milan","country":"it","lang":"en","max_results":10}, "async": True}, timeout=30)
run_id = r.json()["payload"]["run_id"]
while True:
    run = requests.get(f"https://api.quanticdata.io/v1/scraper/collectors/runs/{run_id}", headers=H, timeout=30).json()["payload"]
    if run["status"] in ("done", "failed"):
        break
    time.sleep(5)
print(run["status"], run["count"])

Python: background run and polling

Errors

What can come back, and what is billed.

Collector run errors
Status	Meaning	Billed
`400`	The input does not match the collector (`payload.errors`)	No
`401`	Missing or wrong API key	No
`402`	Balance and free credit do not cover the run: top up	No
`422`	The input can never resolve; retrying the same input cannot help	No
`424`	The run failed at the source (blocked, timed out, layout changed); safe to retry	No
`429`	Rate limit or a per-account brake; wait for `Retry-After`	No

Only delivered rows are billed: a run that delivers nothing costs nothing.

Price

$0.002 per delivered event.

What Google Events rows cost at list price
Rows	Cost
1	$0.002
1,000	$2.00
10,000	$20.00

Up to 20 events per run; split larger jobs into several runs. The $2 free credit every month covers about 1,000 events. No subscription; paid tiers lower the unit price. All collector prices: collector pricing.

Before you run it

Questions developers ask

Is there a free Google Events API?

Every account gets $2 of free usage each month, about 1,000 events of this collector at $0.002 each, with no card.

Do I have to handle proxies, retries or blocks?

No. The collector runs on our network and handles them; a run blocked at the source returns 424 and is not billed.

How many rows can one run return?

Up to 20 events per run (the max_results input, where the collector has one).

Can an AI agent run it?

Yes: the MCP server exposes it as the run_collector tool, with the same input and price. See the MCP server.

Run it on the free credit.

Create an API key, export it as QD_API_KEY and run the example. $0.002 per delivered event, no subscription.

Get an API key Google Events API