# Yelp Events (`payam54/yelp-events`) Actor Fetches Yelp's public events. - **URL**: https://apify.com/payam54/yelp-events.md - **Developed by:** [Payam Pirooznia](https://apify.com/payam54) (community) - **Categories:** Jobs, Social media, Travel - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.25 / actor start 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## Yelp Events Apify Actor A standalone Apify actor repository that extracts public event listings from Yelp city events pages. It is designed for BFU-Feeder ingestion, but the repository itself is intended to be developed, tested, and deployed independently. ### What It Does | Step | Description | |------|-------------| | 1. Navigate | Load Yelp events browse pages (e.g., `/events/austin-tx-us/browse?official=0`) | | 1b. Throttle | Enforce a 500 ms same-domain delay between Yelp page requests to reduce firewall/challenge risk | | 2. Classify | Detect page type: events list, event detail, blocked/challenge, unsupported layout | | 3. Parse list | Extract event cards using multi-strategy selectors | | 4. Enrich (optional) | Follow event detail links for richer data | | 5. Map & emit | Merge card + detail data into `YelpEventRecord` aligned with BFU-Feeder `RawEventContract` | | 6. Diagnostics | Save per-source and global run metrics to key-value store | ### Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `startUrls` | `StartUrl[]` | *required* | Yelp events page URLs | | `maxItems` | `integer` | `200` | Max total events (0 = unlimited) | | `maxEventsPerSource` | `integer` | `100` | Max events per source URL (0 = unlimited) | | `categories` | `string[]` | `undefined` | Optional category filter (see below) | | `includeDetailPages` | `boolean` | `true` | Follow event detail links for enrichment | | `proxyConfiguration` | `object` | `undefined` | Apify proxy settings | | `browserType` | `"chromium" \| "firefox" \| "webkit"` | `"chromium"` | Browser engine used by Playwright | | `browserUserAgents` | `string[]` | `built-in pool` | Optional custom user-agent pool; one is selected randomly per run | | `browserViewportWidth` | `integer` | `1366` | Browser viewport width in pixels | | `browserViewportHeight` | `integer` | `768` | Browser viewport height in pixels | | `browserJavaScriptEnabled` | `boolean` | `true` | Enable JavaScript in browser context | | `browserIgnoreHTTPSErrors` | `boolean` | `true` | Ignore TLS/HTTPS certificate errors | | `debugMode` | `boolean` | `false` | Verbose logging | | `saveDebugHtml` | `boolean` | `false` | Save raw HTML to key-value store | | `saveDebugScreenshots` | `boolean` | `false` | Save page screenshots | #### Example Start URLs ```` https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0 https://www.yelp.com/events/austin-tx-us/browse?official=0 https://www.yelp.com/events/san-diego-ca-us/browse?official=0 ```` #### Category Filter The optional `categories` field filters events by Yelp's event category. When provided, each start URL is expanded into one request per selected category by appending `&c=`. | Category | ID | |---|---| | Other | 0 | | Music | 1 | | Visual Arts | 2 | | Performing Arts | 3 | | Film | 4 | | Lectures & Books | 5 | | Fashion | 6 | | Food & Drink | 7 | | Festivals & Fairs | 8 | | Charities | 9 | | Sports & Active life | 10 | | Nightlife | 11 | | Kids & Family | 12 | Example: 2 start URLs with `["Music", "Food & Drink"]` produces 4 requests. #### Browser Runtime Defaults - Default browser type: `chromium` - Supported browser types: `chromium`, `firefox`, `webkit` - Default viewport: `1366x768` - Default `javaScriptEnabled`: `true` - Default `ignoreHTTPSErrors`: `true` - User-Agent selection: - If `browserUserAgents` is provided and non-empty, one value is chosen randomly per run. - Otherwise, one value is chosen randomly from a built-in fallback pool. When `browserType` is `chromium`, the actor always applies fixed launch arguments: - `--disable-gpu` - `--no-sandbox` - `--disable-dev-shm-usage` - `--disable-extensions` - `--disable-popup-blocking` - `--disable-blink-features=AutomationControlled` - `--disable-web-security` - `--disable-background-networking` - `--disable-notifications` - `--disable-infobars` ### Output Each dataset item is a `YelpEventRecord` with these key fields: | Field | Type | Description | |-------|------|-------------| | `source_family` | `"yelp_events"` | Fixed identifier | | `platform` | `"yelp"` | Fixed identifier | | `raw_title` | `string \| null` | Event title | | `raw_description` | `string \| null` | Event description text (line breaks preserved, including `
`-derived breaks) | | `raw_start_text` | `string \| null` | Start date/time text (ISO when available) | | `raw_end_text` | `string \| null` | End date/time text (ISO when available) | | `raw_location_text` | `string \| null` | Venue/location text (line breaks, including `
`, normalized to comma-space) | | `location` | `string \| null` | Venue/business name extracted from the event page biz-name link | | `zip_code` | `string \| null` | 5-digit ZIP extracted from `raw_location_text` when pattern is present | | `raw_image_url` | `string \| null` | Event image URL | | `event_url` | `string \| null` | Direct event page URL | | `external_event_id` | `string \| null` | Yelp event slug | | `raw_payload_json` | `object` | Card HTML, detail HTML, strategy, version | | `is_cancelled_hint` | `boolean \| null` | Cancellation detection | | `starts_at_hint` | `string \| null` | ISO datetime if parseable from start text | | `ends_at_hint` | `string \| null` | ISO datetime if parseable from end text | | `fetched_at` | `string` | ISO timestamp | Full schema: see [src/types.ts](src/types.ts) `YelpEventRecord` interface. ### BFU-Feeder Integration This repository's output aligns with BFU-Feeder's `RawEventContract`: | Actor field | Contract field | |-------------|----------------| | `raw_title` | `raw_title` | | `raw_start_text` | `raw_start_text` | | `raw_location_text` | `raw_location_text` | | `zip_code` | `zip_code` | | `event_url` | `raw_url` | | `raw_image_url` | `raw_image_url` | | `raw_description` | `raw_description` | | `raw_end_text` | `raw_end_text` | | `ends_at_hint` | `ends_at_hint` | | `raw_payload_json` | `raw_payload_json` | | `is_cancelled_hint` | `is_cancelled_hint` | | `external_event_id` | `external_event_id` (prefixed with `apify-` by mapper) | | `fetched_at` | `fetched_at` | ### Development #### Prerequisites - Node.js 18+ - npm 9+ #### Setup ```bash npm install ```` #### Build ```bash npm run build ## TypeScript → dist/ make build ## Same as npm run build ``` #### Test ```bash npm test ## Run all tests with vitest npm run test:coverage ## Run tests with coverage output npm run test:watch ## Watch mode make test ## Run tests with coverage output make test-watch ## Watch mode via make ``` #### Common Make targets ```bash make help ## List available targets make install ## Install dependencies make build ## Compile TypeScript make test ## Run tests with coverage report make test-watch ## Run Vitest in watch mode make run ## Run the actor locally with Apify CLI make clean ## Remove dist/, coverage/, and local runtime artifacts ``` #### Run locally ```bash ## Using Apify CLI apify run --input='{"startUrls": [{"url": "https://www.yelp.com/events/austin-tx-us/browse?official=0"}], "maxItems": 10}' ``` ### Architecture ``` src/ ├── main.ts ## Actor entry point + PlaywrightCrawler orchestration ├── types.ts ## All TypeScript interfaces + category map ├── url_utils.ts ## URL expansion for category filter ├── navigation.ts ## Page classification (list, detail, blocked, unsupported) ├── list_parser.ts ## Multi-strategy event card extraction from browse pages ├── detail_parser.ts ## Event detail page enrichment ├── output_mapper.ts ## Merge card + detail → YelpEventRecord ├── browser_runtime.ts ## Browser runtime normalization and launch settings └── diagnostics.ts ## Run metrics tracker tests/ ├── url_utils.test.ts ├── list_parser.test.ts ├── detail_parser.test.ts ├── output_mapper.test.ts ├── browser_runtime.test.ts └── diagnostics.test.ts ``` #### Parser Strategies The list parser tries multiple selector strategies in order: 1. **classic-events-list** — `ul.events-index_events-list li` and similar containers 2. **card-layout** — `[class*="event-card"]` and data-testid patterns 3. **anchor-fallback** — Links to `/events/` detail pages with container inference #### Page Classification | Classification | Meaning | |----------------|---------| | `yelp_events_list` | Yelp events browse page with event cards | | `yelp_event_detail` | Individual event detail page | | `blocked_challenge` | CAPTCHA, rate-limit block, or "unusual activity" page | | `unsupported_layout` | Page loaded but no recognizable events layout | | `error` | Navigation or timeout error | ### Diagnostics Run diagnostics are saved to the key-value store under the key `run-diagnostics` and include: - Pages visited, events found/emitted/skipped - Detail page attempt/success counts - Partial failure count (events emitted with warnings) - Per-source breakdown (URL, classification, counts, warnings) - Global parser warnings and unsupported layout notes # Actor input Schema ## `startUrls` (type: `array`): One or more public Yelp events page URLs. Example: https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0 ## `maxItems` (type: `integer`): Maximum total events to extract across all start URLs. 0 = unlimited. ## `maxEventsPerSource` (type: `integer`): Maximum events to extract from a single start URL. 0 = unlimited. ## `categories` (type: `array`): Optional list of Yelp event categories to filter by. When set, each start URL is expanded into one request per category. Leave empty to fetch all categories. ## `includeDetailPages` (type: `boolean`): If true, follow public event detail links to enrich event records. ## `proxyConfiguration` (type: `object`): Apify proxy configuration. ## `browserType` (type: `string`): Playwright browser engine used by the crawler. ## `browserUserAgents` (type: `array`): Optional list of user-agent strings. One value is selected randomly per run. If omitted or empty, a built-in default pool is used. ## `browserViewportWidth` (type: `integer`): Browser viewport width in pixels. ## `browserViewportHeight` (type: `integer`): Browser viewport height in pixels. ## `browserJavaScriptEnabled` (type: `boolean`): Enable JavaScript execution in the browser context. ## `browserIgnoreHTTPSErrors` (type: `boolean`): Ignore TLS/HTTPS certificate errors in the browser context. ## `debugMode` (type: `boolean`): Enable verbose logging for debugging. ## `saveDebugHtml` (type: `boolean`): Save raw HTML snapshots to key-value store for debugging layout issues. ## `saveDebugScreenshots` (type: `boolean`): Save page screenshots to key-value store for visual debugging. ## Actor input object example ```json { "startUrls": [ { "url": "https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0" } ], "maxItems": 200, "maxEventsPerSource": 100, "includeDetailPages": true, "browserType": "chromium", "browserViewportWidth": 1366, "browserViewportHeight": 768, "browserJavaScriptEnabled": true, "browserIgnoreHTTPSErrors": true, "debugMode": false, "saveDebugHtml": false, "saveDebugScreenshots": false } ``` # Actor output Schema ## `events` (type: `string`): Normalized Yelp event records emitted to the default dataset. Each item follows the YelpEventRecord contract defined in src/types.ts, including event metadata, timestamps, warnings, raw payload snippets, and actor run context. ## `runDiagnostics` (type: `string`): Structured run summary saved to the default key-value store under the 'run-diagnostics' record. Includes page classifications, counts, warnings, and unsupported-layout notes for the Actor run. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("payam54/yelp-events").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0" }] } # Run the Actor and wait for it to finish run = client.actor("payam54/yelp-events").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ { "url": "https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0" } ] }' | apify call payam54/yelp-events --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=payam54/yelp-events", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Yelp Events", "description": "Fetches Yelp's public events.", "version": "0.0", "x-build-id": "nfk6oZYzfcCTKNk3q" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/payam54~yelp-events/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-payam54-yelp-events", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/payam54~yelp-events/runs": { "post": { "operationId": "runs-sync-payam54-yelp-events", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/payam54~yelp-events/run-sync": { "post": { "operationId": "run-sync-payam54-yelp-events", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "startUrls" ], "properties": { "startUrls": { "title": "Start URLs", "type": "array", "description": "One or more public Yelp events page URLs. Example: https://www.yelp.com/events/mission-viejo-ca-us/browse?official=0", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxItems": { "title": "Max total items", "minimum": 0, "type": "integer", "description": "Maximum total events to extract across all start URLs. 0 = unlimited.", "default": 200 }, "maxEventsPerSource": { "title": "Max events per source URL", "minimum": 0, "type": "integer", "description": "Maximum events to extract from a single start URL. 0 = unlimited.", "default": 100 }, "categories": { "title": "Event categories", "uniqueItems": true, "type": "array", "description": "Optional list of Yelp event categories to filter by. When set, each start URL is expanded into one request per category. Leave empty to fetch all categories.", "items": { "type": "string", "enum": [ "Other", "Music", "Visual Arts", "Performing Arts", "Film", "Lectures & Books", "Fashion", "Food & Drink", "Festivals & Fairs", "Charities", "Sports & Active life", "Nightlife", "Kids & Family" ] } }, "includeDetailPages": { "title": "Include detail pages", "type": "boolean", "description": "If true, follow public event detail links to enrich event records.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy configuration." }, "browserType": { "title": "Browser type", "enum": [ "chromium", "firefox", "webkit" ], "type": "string", "description": "Playwright browser engine used by the crawler.", "default": "chromium" }, "browserUserAgents": { "title": "Custom browser user-agent pool", "type": "array", "description": "Optional list of user-agent strings. One value is selected randomly per run. If omitted or empty, a built-in default pool is used.", "items": { "type": "string" } }, "browserViewportWidth": { "title": "Browser viewport width", "minimum": 1, "type": "integer", "description": "Browser viewport width in pixels.", "default": 1366 }, "browserViewportHeight": { "title": "Browser viewport height", "minimum": 1, "type": "integer", "description": "Browser viewport height in pixels.", "default": 768 }, "browserJavaScriptEnabled": { "title": "Enable browser JavaScript", "type": "boolean", "description": "Enable JavaScript execution in the browser context.", "default": true }, "browserIgnoreHTTPSErrors": { "title": "Ignore HTTPS errors", "type": "boolean", "description": "Ignore TLS/HTTPS certificate errors in the browser context.", "default": true }, "debugMode": { "title": "Debug mode", "type": "boolean", "description": "Enable verbose logging for debugging.", "default": false }, "saveDebugHtml": { "title": "Save debug HTML", "type": "boolean", "description": "Save raw HTML snapshots to key-value store for debugging layout issues.", "default": false }, "saveDebugScreenshots": { "title": "Save debug screenshots", "type": "boolean", "description": "Save page screenshots to key-value store for visual debugging.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```