# Google Events API for AI Agents (`khadinakbar/google-events-api`) Actor

Find Google Events by keyword and location through SerpApi. Use for event discovery, calendar assistants, conference research, and ticket-link enrichment. Returns one normalized event with dates, venue, maps link, and ticket sources. Charged $0.05 per completed search plus $0.005 per returned event.

- **URL**: https://apify.com/khadinakbar/google-events-api.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** MCP servers, Lead generation, Travel
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $100.00 / 1,000 completed google events searches

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Events API for AI Agents

Search Google Events by keyword, location, and an upcoming-date filter. This regular Apify Actor is designed for AI agents, calendar assistants, event-research workflows, and developers that need a bounded JSON response rather than browser automation.

Use it when you need structured upcoming event results such as conferences, concerts, festivals, classes, sports, or local meetups. It returns one normalized dataset row per event with its title, source description, dates, venue, Google Maps link, event page, and available ticket or information links.

This focused discovery surface works for public upcoming Google Events. Ticket purchasing, private calendars, availability confirmation, and historical archives belong in their dedicated organizer, calendar, or ticketing workflows. Results are drawn from Google Events through SerpApi at collection time, so Google controls availability and field completeness.

### Why agents use this Actor

- One focused action: find Google Events for a query and location.
- Agent-safe inputs: one query, one location selector, one date-window enum, and a hard result cap.
- Stable, flat fields: `eventTitle`, `startAt`, `venueName`, `eventUrl`, `googleMapsUrl`, and `ticketLinks`.
- Honest terminal state: every run writes `OUTPUT` and `RUN_SUMMARY` with `COMPLETE`, `PARTIAL`, `VALID_EMPTY`, `INVALID_INPUT`, `UPSTREAM_FAILED`, or `CONFIG_ERROR`.

### Best fit and workflow routing

Choose this Actor for a focused event-discovery step: an agent starts with a subject, a city, and an upcoming date window, then receives source-linked event records it can compare, shortlist, schedule, or pass to a calendar or research workflow. Pair it with your calendar, CRM, or venue-enrichment step after the event shortlist is ready; this Actor is designed as a focused standalone workflow for collecting the Google Events discovery layer.

### Workflow story: from query to shortlist

An event-research assistant starts with “AI conferences in New York next month.” It sends that scope as `eventQuery`, `locationName`, and `dateRange`, then reads the default dataset after collection completes. Next, it compares `startAt`, `venueName`, and `ticketLinks`, confirms the selected organizers on their source pages, and exports the resulting shortlist to the user’s itinerary or outreach plan.

### Focused standalone workflow

This Actor is designed as a focused standalone workflow when an agent needs the Google Events discovery layer before calendar, CRM, venue, or organizer-specific steps.

### Input

```json
{
  "eventQuery": "AI conferences",
  "locationName": "New York,New York,United States",
  "dateRange": "next_month",
  "languageCode": "en",
  "maxResults": 10,
  "countryCode": "us"
}
```

Set `locationName` to a city-level value such as `London, England, United Kingdom`, and use `countryCode` to set Google’s two-letter country context such as `gb`. The health-safe default is New York, New York, United States.

### Output

Each dataset item has a compact, agent-readable shape:

```json
{
  "eventTitle": "AI Summit New York",
  "startAt": "2026-09-12T09:00:00",
  "endAt": "2026-09-12T17:00:00",
  "displayedDates": "Fri, Sep 12, 9 AM – 5 PM",
  "venueName": "Javits Center",
  "venueAddress": "429 11th Ave, New York, NY",
  "eventUrl": "https://example.com/event",
  "googleMapsUrl": "https://www.google.com/maps/place/...",
  "ticketLinks": [{ "title": "Ticket source", "label": "TICKETS", "url": "https://example.com/tickets", "domain": "example.com" }],
  "searchQuery": "AI conferences",
  "location": "New York,New York,United States",
  "dateRange": "next_month",
  "provider": "serpapi_google_events",
  "source": "Google Events via SerpApi"
}
```

Nullable fields are deliberate: an absent description, end time, image, venue, or ticket source is returned as `null` or an empty `ticketLinks` array rather than invented.

| Field | How an agent uses it |
| --- | --- |
| `eventTitle`, `startAt`, `endAt` | Compare the event identity and timing. |
| `venueName`, `venueAddress`, `googleMapsUrl` | Route the user to the location and travel context. |
| `eventUrl`, `ticketLinks` | Confirm details with an organizer or ticket source. |
| `source`, `collectedAt`, `providerCostUsd` | Preserve provenance, freshness, and request-cost context. |

### Pricing

This Actor uses Pay per event plus platform usage. The event prices are predictable before an agent calls it:

| Event | Price |
| --- | ---: |
| Actor start | $0.00005 |
| Completed Google Events search | $0.10 |
| Persisted event row | $0.005 |

A ten-event response therefore has event charges of $0.15005, plus Apify platform usage. A valid empty response still has one completed-search charge because the provider search was completed; malformed input and missing credentials produce no event rows. The live Pricing tab is the current source of truth for event prices and Pay per event plus platform usage configuration. `RUN_SUMMARY` preserves the provider search ID, output counts, and terminal outcome for auditability.

### API and MCP use

Run the Actor through the Apify API, then read the default dataset and terminal records. Replace the actor ID with the one shown in your Apify Console after deployment.

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('khadinakbar/google-events-api').call({
  eventQuery: 'startup events',
  locationName: 'Austin,Texas,United States',
  dateRange: 'weekend',
  maxResults: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

> Agent prompt: “Find up to 10 startup events in Austin this weekend. Use the Google Events API Actor with `dateRange: \"weekend\"`; return the title, start time, venue, and the first ticket link when present. Read the resulting dataset and `OUTPUT` record, preserve `source` and `collectedAt`, and treat `VALID_EMPTY` as a completed search with no matching Google Events rows.”

### Best results, freshness, and workflow guidance

The Actor calls SerpApi’s regular Google search surface and reads its Google Events result block for the selected query, location, language, and country. `dateRange` adds a natural-language date hint such as “this weekend” to the source query. Google and the provider can vary or omit events, descriptions, times, source pages, ticket links, and venue details; this Actor preserves that uncertainty instead of filling gaps.

Use a specific subject plus a city-level location for the strongest match between user intent and the Google Events source. Confirm event details, access, pricing, availability, and cancellation policies with the organizer before taking downstream action. `RUN_SUMMARY` provides result counts, warnings, and terminal diagnostics; `VALID_EMPTY` represents a completed search whose query and targeting had no matching rows.

### Builder's note

I designed this Actor around SerpApi’s regular Google result surface, which currently exposes the event-result block, instead of a browser scraper because agents need a bounded, source-labeled response with transparent request cost. My goal is to preserve the useful event, venue, maps, and ticket-source fields while making missing upstream fields explicit, so a downstream agent can make a grounded decision.

### Legal and responsible use

Use this Actor only for lawful purposes and in line with the applicable terms, privacy rules, and provider account agreement. Verify event details, accessibility, pricing, availability, and cancellation policies with the event organizer before acting on them.

# Actor input Schema

## `eventQuery` (type: `string`):

Free-text event search sent to Google Events, for example `technology conferences` or `jazz concerts`. It accepts up to 700 characters. Defaults to `events in New York` for the automated health check. This is not a venue URL or a ticket URL.

## `locationName` (type: `string`):

City or regional location used by Google Events, for example `New York, New York, United States`. Defaults to New York, New York, United States. Use a city-level location for the most relevant local event results. This is not a coordinates string or a Google Maps URL.

## `dateRange` (type: `string`):

Google Events date filter. Choose `weekend`, `next_week`, or `month` when the agent needs an upcoming window. Defaults to `all`, which applies no date filter. This is not an arbitrary start and end date range.

## `languageCode` (type: `string`):

Google Events interface language code, for example `en`. Defaults to `en`. This controls the search interface language, not an event-language guarantee. Use a two-to-ten character language code.

## `countryCode` (type: `string`):

Two-letter Google country code, for example `us` or `gb`. Defaults to `us` and works with locationName to localize the search. This is not the country where an event organizer is registered.

## `maxResults` (type: `integer`):

Maximum normalized events written to the dataset. Defaults to 10 and accepts 1 through 10, the bounded result page supported by this Actor. This is not a guarantee that Google has that many matching events.

## Actor input object example

```json
{
  "eventQuery": "events in New York",
  "locationName": "New York, New York, United States",
  "dateRange": "week",
  "languageCode": "en",
  "countryCode": "us",
  "maxResults": 10
}
```

# Actor output Schema

## `events` (type: `string`):

One normalized Google Events result per row.

## `runSummary` (type: `string`):

Detailed terminal outcome, input boundary, provider cost, counts, and warnings.

## `compactOutput` (type: `string`):

Stable terminal output for agents and automations.

## `lastRunSummary` (type: `string`):

Compatibility alias for the detailed terminal record.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "eventQuery": "events in New York",
    "locationName": "New York, New York, United States",
    "dateRange": "week",
    "languageCode": "en",
    "countryCode": "us",
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/google-events-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "eventQuery": "events in New York",
    "locationName": "New York, New York, United States",
    "dateRange": "week",
    "languageCode": "en",
    "countryCode": "us",
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/google-events-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "eventQuery": "events in New York",
  "locationName": "New York, New York, United States",
  "dateRange": "week",
  "languageCode": "en",
  "countryCode": "us",
  "maxResults": 10
}' |
apify call khadinakbar/google-events-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/google-events-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AWrNRryF7CxDV3eG3/builds/LqSQIfmiPPbKkMcXj/openapi.json