# Google Calendar Live Query Actor (`scrapeai/google-calendar`) Actor

Run a live public query against Google Calendar and return up to 100 normalized records without static fixtures.

- **URL**: https://apify.com/scrapeai/google-calendar.md
- **Developed by:** [ScrapeAI](https://apify.com/scrapeai) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 1,000 results

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

### What does Google Calendar Live Query Actor do?

This **Google Calendar Actor** sends a user-provided query to a live public Google Calendar source and writes multiple normalized records to the Apify dataset. The default query is deliberately non-empty and is tested with a default maxItems of 10; increase it up to 100 when the source supports more results. It does not use static fixtures, log in, solve CAPTCHAs, or access private account data.

This service uses a strict live adapter: if the public source does not expose enough rich records, the run fails and does not pad the dataset with unrelated autocomplete suggestions.

The Actor is packaged as an independent Apify project with API access, scheduling, monitoring, integrations, and local dataset output. Open the official service at [Google Calendar](https://calendar.google.com/) to compare the live results with the source UI.

### Why use Google Calendar Live Query Actor?

Use it for live research, search discovery, market monitoring, content planning, QA checks, and downstream automation. Each run preserves the original query, source URL, result URL, record position, and retrieval timestamp so consumers can distinguish current results from older runs. Rich adapters expose service-specific fields inside details; account-only services remain public-only and never fabricate private metrics.

Apify adds reliable dataset storage, API download, scheduling, run monitoring, integrations, and optional proxy configuration. The Actor never treats scraped page text as code and never fabricates a result when the public source is unavailable.

### What data can this Actor extract?

| Field | Type | Description |
| --- | --- | --- |
| query | string | The live query used for this run. |
| itemPosition | number | One-based position in the returned dataset. |
| title | string | Result, topic, place, app, book, video, translation, or suggestion title. |
| description | string | Live snippet, address, summary, or source description when available. |
| url | URL | Public result or service reference URL. |
| sourceUrl | URL | Public endpoint/page used for live retrieval. |
| details | object | Service-specific metadata such as ratings, authors, image URLs, coordinates, or translations. |
| scrapedAt | date-time | UTC time at which the record was fetched. |

### How to scrape Google Calendar data

1. Open the Actor input tab and enter a query such as Google Calendar events.
2. Set maxItems to 10 for a quick run or a higher value up to 100. Keep minItems at 10 when you want the Actor to fail rather than accept an undersized live response.
3. Choose hl, gl, and a request timeout when regional or language-specific results matter.
4. Click Start. Inspect the dataset and download it as JSON, HTML, CSV, or Excel, or call the Actor through the Apify API.

### Input

See the Input tab for the full configuration. The important fields are query, maxItems, minItems, hl, gl, requestTimeoutSecs, optional proxyConfiguration, optional flight departureDate/returnDate, optional hotel checkInDate/checkOutDate, and targetLanguages for Google Translate. The local default input is stored in storage/key\_value\_stores/default/INPUT.json.

Run locally from this directory with:

```bash
apify validate-schema
apify run --purge
```

### Google access challenges

If Google presents an unusual-traffic or regional access challenge during a local Search, Images, or Lens run, provide an enabled proxy in proxyConfiguration (for example {"useApifyProxy":true,"countryCode":"US"}) or provide custom proxyUrls. Apify Proxy external access must be enabled for the account. Search and Images can also use the official Google Custom Search JSON API when GOOGLE\_API\_KEY and GOOGLE\_CSE\_ID are configured as environment secrets. These strict Actors never replace blocked results with autocomplete, static fixtures, or unrelated records.

### Output

The Actor writes one dataset item per live result, not one metadata record for the whole service. You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

```json
{
  "serviceName": "Google Calendar",
  "query": "Google Calendar events",
  "itemPosition": 1,
  "maxItems": 10,
  "live": true,
  "recordType": "liveResult",
  "title": "Live result title",
  "url": "https://calendar.google.com/",
  "sourceType": "help-search-live",
  "scrapedAt": "2026-01-01T00:00:00.000Z"
}
```

### How much does it cost to scrape Google Calendar?

Local runs have no Apify platform charge. Cloud cost depends on your Apify plan and runtime. The default run is bounded to a small number of public requests and 10 records; larger maxItems values can increase requests and compute usage. If you configure an official Google API key, that provider may apply its own quota or billing rules.

### Tips and advanced options

- Keep maxItems at 10 while testing a query, then raise it to 100 for supported sources.
- Use a precise query and matching gl country code for more relevant live results.
- Inspect sourceType, details.extractionLevel, and details.accessNote to understand whether a row came from a direct public feed, a rendered result card, an official API, or live discovery autocomplete.
- Services that require OAuth are intentionally public-only. Supply an approved API integration in a future adapter if private account data is needed.

### FAQ, disclaimers, and support

Some Google services are authenticated or client-rendered. In those cases this Actor reports live public information or live query suggestions and never inserts static placeholders. Google may rate-limit or change public markup, so review sourceType, scrapedAt, and run logs when a source changes.

> Our Actors are ethical and do not extract private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. You should not scrape personal data unless you have a legitimate reason and comply with GDPR and other applicable laws. Review the target site terms, use the Issues tab for feedback, and use the API tab for programmatic access.

For a custom authenticated integration, use the appropriate Google API with the user’s consent and credentials instead of bypassing access controls.

# Actor input Schema

## `query` (type: `string`):

Query or text to send to the public Google Calendar source. The default is a working live-data query.

## `maxItems` (type: `integer`):

Maximum number of live records to return. Use 10 for a quick check or increase up to 100 when the source supports it.

## `minItems` (type: `integer`):

The Actor fails instead of adding static data when the live source returns fewer than this many records. Default is 10.

## `hl` (type: `string`):

Two- or three-letter language code for the live request.

## `gl` (type: `string`):

Two-letter country code used for regional live results.

## `requestTimeoutSecs` (type: `integer`):

Timeout for each public live request.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy or custom proxy configuration for public sources that rate-limit a local IP. Do not use this to bypass CAPTCHAs or access controls.

## `targetLanguages` (type: `array`):

Optional language codes used by Google Translate. Ignored by other Actors.

## `departureDate` (type: `string`):

Optional flight departure date in YYYY-MM-DD format. Used by Google Flights; ignored by other Actors.

## `returnDate` (type: `string`):

Optional flight return date in YYYY-MM-DD format. Used by Google Flights; ignored by other Actors.

## `checkInDate` (type: `string`):

Optional hotel check-in date in YYYY-MM-DD format. Used by Google Hotels; ignored by other Actors.

## `checkOutDate` (type: `string`):

Optional hotel check-out date in YYYY-MM-DD format. Used by Google Hotels; ignored by other Actors.

## Actor input object example

```json
{
  "query": "Google Calendar events",
  "maxItems": 10,
  "minItems": 10,
  "hl": "en",
  "gl": "us",
  "requestTimeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "targetLanguages": []
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 = {
    "query": "Google Calendar events",
    "hl": "en",
    "gl": "us",
    "targetLanguages": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeai/google-calendar").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 = {
    "query": "Google Calendar events",
    "hl": "en",
    "gl": "us",
    "targetLanguages": [],
}

# Run the Actor and wait for it to finish
run = client.actor("scrapeai/google-calendar").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 '{
  "query": "Google Calendar events",
  "hl": "en",
  "gl": "us",
  "targetLanguages": []
}' |
apify call scrapeai/google-calendar --silent --output-dataset

```

## MCP server setup

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

```

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/h724T45EmsPSakaSY/builds/BQEdhUk0Y8Recz2d3/openapi.json