# Apple Maps API | Places, Guides, Local Search & Refinements (`johnvc/apple-maps-api`) Actor Scrape Apple Maps and extract local business listings, place details, curated guides, and refinement filters in one Actor. Phone, ratings, reviews, hours, address, GPS, amenities, multi-source ratings. City-name or coordinate targeting. Pay per result. MCP-ready for Claude, ChatGPT, Cursor. - **URL**: https://apify.com/johnvc/apple-maps-api.md - **Developed by:** [John](https://apify.com/johnvc) (community) - **Categories:** Travel, SEO tools, Lead generation - **Stats:** 5 total users, 4 monthly users, 100.0% runs succeeded, 4 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.01 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ## Apple Maps API | Places, Guides, Local Search & Refinements (MCP-ready) > **Search Apple Maps and extract local business listings, place details, curated guides, and refinement filters in a single Actor. Phone, ratings, reviews, hours, address, GPS, amenities, plus multi-source ratings from Apple, Yelp, Foursquare, and TripAdvisor. City-name or coordinate targeting. Pay per result. MCP-ready for Claude, ChatGPT, Cursor, and other AI agents.** Pass a query plus a location anchor (city name or lat,lng coordinates), pick one of four search modes, and the Actor returns the matching slice of Apple Maps data: local business listings, a single rich place detail object, curated Apple Maps guide collections, or the full set of refinement filters and sort options available for that query. Phone, weekly hours, GPS coordinates, multi-source ratings, photo galleries, amenities, and price tiers are all included where Apple Maps exposes them. This is the **only Apple Maps Actor on the Apify store that covers all four result families** (local + place + guide + refinement) under a unified input schema. Competing actors handle one slice each; this one handles all of them, with explicit per-mode billing so you never pay for data you did not request. --- ### Use with Claude, ChatGPT, Cursor & other AI agents (MCP) This Actor is a first-class tool on the [Apify MCP Server](https://docs.apify.com/platform/integrations/mcp). Any MCP-compatible AI agent - Claude (Desktop, Web, Code), ChatGPT (via custom GPT or MCP bridge), Cursor, VS Code, Cline, Windsurf, Kilo Code, Opencode, Glama - can discover and call this Actor in natural language. **What an AI agent does with this:** > User: *"Find me the highest-rated ramen spots open right now near Apple Park."* > > Agent calls `search-actors("apple maps")` on the Apify MCP server, picks this Actor, and runs it twice. First in `refinement` mode for the query "ramen" to discover the `open_now` toggle key. Then in `search` mode with `query=ramen`, `center=37.3349,-122.0090`, `sort=ratings`, `toggles=[open_now]`, and `max_results=10`. The agent returns a short ranked list with phone numbers, addresses, and weekly hours. > User: *"Get me the full place page for Blue Bottle Coffee in San Francisco."* > > Agent runs the Actor in `place` mode with `query="Blue Bottle Coffee San Francisco"`. Receives the single place detail object back: photo gallery, full weekly hours, multi-source ratings, about text, amenities, and the curated guides this place appears in. > User: *"What Apple Maps guides cover the best brunch in Brooklyn?"* > > Agent runs the Actor in `guide` mode with `query="brunch Brooklyn"`. Receives the curated Apple Maps guide list, each with a publisher, photo set, and the underlying place items. --- ### What this Actor returns The output shape depends on `search_mode`: | Mode | What you get | Billed as | |---|---|---| | `search` (default) | `local_results` (business listings) + `guide_results` (curated guides) + `refinement` (filter options) | `local_result` per listing + `guide_result` per guide + `refinement_result` | | `place` | `place_results` - one rich place detail object | `place_result` | | `guide` | `guide_results` - curated Apple Maps guide collections | `guide_result` per guide | | `refinement` | `refinement` - the toggles, multi-select filters, and sort options available for the query | `refinement_result` | Every successful response also includes `search_parameters`, `search_metadata`, `search_mode`, `search_timestamp`, and `result_counts`. #### Fields returned in `local_results` `title`, `position`, `place_id`, `muid`, `gps_coordinates`, `rating`, `max_rating`, `reviews`, `ratings` (multi-source: Apple, Yelp, Foursquare, TripAdvisor with attribution), `address`, `phone`, `website`, `amenities`, `price_score`, `open_state`, `weekly_hours`, `timezone`, `type`, `type_id`, `types`, `type_ids`, `actions`, `images`, `user_reviews`, `collection` (guides containing this place), `facts`. #### Fields returned in `place_results` Same as `local_results` plus `about` (description), `link`, and full photo gallery categories. Single object, not an array. #### Fields returned in `guide_results` `position`, `position_in_page`, `muid`, `provider_id`, `title`, `long_title`, `description`, `link`, `apple_maps_link`, `item_count`, `publisher`, `photos`, `items` (the places inside the guide). #### Fields returned in `refinement` `toggles` (single-value filters like `open_now`, `drive_thru`, `TOP_RATED`), `multi_select` (multi-value groups like chains, amenities, price tiers), `sort` (allowed sort keys), `open_at` (slot for the open-at timestamp filter). --- ### Use cases - **Local lead generation:** Pull business listings with phone, address, website, and ratings for outbound sales lists. - **Travel itinerary building:** Surface curated Apple Maps guides plus underlying places for a destination. - **Local SEO and rank tracking:** Audit how a business appears in Apple Maps (NAP consistency, ratings, photos, amenities) across regions. - **Market mapping:** Aggregate every coffee shop within a coordinate span, sorted by rating, for competitive landscape work. - **Filter discovery for downstream automations:** Run `refinement` mode first to learn which toggles and multi-select keys Apple Maps will accept for the query, then chain a filtered search. - **Agent tool calls:** Let AI agents pick the right mode for the user's intent without writing custom integrations. --- ### Input parameters | Parameter | Type | Required | Default | Notes | |---|---|---|---|---| | `search_mode` | string | yes | `search` | One of `search`, `place`, `guide`, `refinement`. | | `query` | string | yes | `coffee` | The search term. Any string valid in Apple Maps search. | | `location` | string | conditional | `Austin, Texas, United States` | City-level place name. Either this OR `center` must be provided. Cannot be combined with `center`. | | `center` | string | conditional | - | `lat,lng` coordinates (e.g. `30.3246,-97.7305`). Either this OR `location` must be provided. Cannot be combined with `location`. | | `span` | string | no | `0.5,0.5` | Viewport size as `latDelta,lngDelta`. Larger = wider radius. | | `sort` | string | no | `default` | `default`, `distance`, or `ratings`. Sorts `local_results`. | | `toggles` | array(string) | no | - | Single-value filter keys (e.g. `open_now`). Discover keys via `refinement` mode. | | `multi_select_options` | array(string) | no | - | Multi-value filter keys (chains, amenities, price tiers). Discover keys via `refinement` mode. | | `open_at` | integer | no | - | Unix timestamp for the open-at filter. Must be within the next 24 hours. | | `locale` | string | no | `en-US` | Language and region code (e.g. `en-US`, `fr-FR`). | | `max_results` | integer | no | `20` | Caps how many `local_result` or `guide_result` items are kept and billed. Set `0` for unlimited (safety cap 100). Ignored for `place` and `refinement` modes. | --- ### Search modes explained **`search` (default).** Broad mix. Use when you want everything Apple Maps surfaces for the query: the local pack, related guides, and the available refinement filters. Billed per local listing, per guide, and per refinement object. **`place`.** Single rich place lookup. Use when your query is specific enough to resolve to one location (e.g. "Apple Park Cupertino", "Blue Bottle Coffee SF Ferry Building"). Returns the full place detail object with photo gallery, about text, multi-source ratings, full weekly hours, amenities, and guide membership. When Apple Maps does not surface a dedicated `place_results` object for the query (its internal classifier decided the query is a local search), the top-ranked match from `local_results` is automatically promoted into the `place_results` slot and flagged with `promoted_from_local_results: true`. Billed once. **`guide`.** Curated Apple Maps guides only. Use when you want themed collections rather than raw listings ("Best ramen Brooklyn", "Hidden hiking spots California"). Billed per guide returned. **`refinement`.** Filter discovery mode. Returns only the refinement object so you can learn which toggles, multi-select keys, and sort options Apple Maps will accept for the query. Useful as a planning step before a filtered `search`. Billed once. --- ### Example output (search mode) ```json { "search_mode": "search", "search_timestamp": "2026-05-13T14:30:12.456789", "search_parameters": { "search_mode": "search", "query": "coffee", "location": "Austin, Texas, United States", "center": null, "span": "0.5,0.5", "locale": "en-US", "sort": "default", "toggles": null, "multi_select_options": null, "open_at": null, "max_results": 5 }, "result_counts": {"local": 5, "guide": 2, "place": 0, "refinement": 1}, "local_results": [ { "position": 1, "title": "Houndstooth Coffee", "place_id": "PLACE_ID_REDACTED", "muid": "MUID_REDACTED", "gps_coordinates": {"latitude": 30.2729, "longitude": -97.7444}, "rating": 4.6, "max_rating": 5, "reviews": 412, "ratings": { "apple": {"rating": 4.6, "count": 412}, "yelp": {"rating": 4.5, "count": 1180} }, "address": "401 Congress Ave, Austin, TX 78701", "phone": "+1 512-394-6051", "website": "https://houndstoothcoffee.com", "amenities": ["Wi-Fi", "Outdoor seating", "Wheelchair accessible"], "price_score": 2, "open_state": "Open", "weekly_hours": {"monday": "7AM-7PM", "tuesday": "7AM-7PM"}, "timezone": "America/Chicago", "type": "Coffee Shop", "types": ["Coffee Shop", "Cafe"] } ], "guide_results": [ { "position": 1, "title": "Best Coffee in Austin", "publisher": {"name": "Austin Eats Magazine"}, "item_count": 12, "items": [] } ], "refinement": { "toggles": {"open_now": {"display_name": "Open Now", "key": "open_now"}}, "sort": ["default", "distance", "ratings"] } } ```` *** ### Pricing Pay-per-event. You are only billed for the result types your chosen mode actually returns. | Event | Price (USD) | When charged | |---|---|---| | `setup` | $0.02 | Once per Actor run | | `local_result` | $0.003 | Per business listing in `local_results` | | `place_result` | $0.005 | Per place detail object in `place_results` | | `guide_result` | $0.003 | Per curated guide in `guide_results` | | `refinement_result` | $0.01 | Per refinement object returned | **Typical run costs:** - `search` for 20 listings + 3 guides + refinements: $0.02 + (20 x $0.003) + (3 x $0.003) + $0.01 = $0.099 - `place` lookup: $0.02 + $0.005 = $0.025 - `guide` mode for 10 guides: $0.02 + (10 x $0.003) = $0.05 - `refinement` only: $0.02 + $0.01 = $0.03 Validation errors (missing query, conflicting `location` and `center`) are pushed as an error dataset item **before** any charge fires, so a misconfigured run costs you nothing. *** ### How to get started 1. Open this Actor in the Apify console: [apple-maps-api](https://apify.com/johnvc/apple-maps-api). 2. Pick `search_mode`, set `query`, and optionally `location` or `center`. 3. Click **Start**. Results appear in the run's dataset within seconds. 4. Export as JSON, CSV, or Excel from the dataset tab, or call the run via API for downstream automation. 5. For AI agents: enable [Apify MCP](https://docs.apify.com/platform/integrations/mcp) in your client and ask for an Apple Maps lookup in plain language. *** ### FAQ / Troubleshooting **Q: I get `ValidationError: The 'query' parameter is required.`** A: Every mode needs a `query`. Even `refinement` mode uses it to figure out which filters apply. **Q: I get `ValidationError: Provide either 'location' or 'center', not both.`** A: These two fields target the map in different ways. Pick one. `location` accepts a place name; `center` accepts coordinates. **Q: I get `ValidationError: Apple Maps requires a location anchor.`** A: Apple Maps will not run a search without a geographic anchor. Add a `location` (e.g. `"Austin, Texas, United States"`) or a `center` (e.g. `"30.3246,-97.7305"`) and re-run. **Q: My `place` mode call returned an empty `place_results` object.** A: Apple Maps did not resolve the query to any place at all (even after the local-results promotion fallback). Try a more specific query (add city, brand, or a unique street name) or run `search` mode to see the local results directly. **Q: My `place` result has `promoted_from_local_results: true`. What does that mean?** A: Apple Maps classified your query as a broad local search rather than a single-place lookup, so we promoted the top-ranked match from `local_results` into the `place_results` slot. The data is genuine Apple Maps data for that place; it just did not come back via the dedicated place response shape. To force a richer single-place response, try a more specific query (full name + city, or full name + street). **Q: How do I discover the right `toggles` and `multi_select_options` keys for my query?** A: Run the Actor in `refinement` mode first. The returned `refinement` object lists every accepted filter key for that query. **Q: Is there a rate limit?** A: The Actor calls the underlying provider once per run. Concurrency is bound by your Apify account's run-slot allotment. **Q: Does this work outside the US?** A: Yes. Pass a non-US `location` or `center` and set `locale` (e.g. `fr-FR`, `de-DE`) for localized response text. **Q: How do I integrate this with my AI agent?** A: Connect [Apify MCP](https://docs.apify.com/platform/integrations/mcp) to your agent. The Actor advertises itself with searchable keywords ("apple maps", "places", "guides", "local search", "refinements") so agents can find it on their own. *** Last Updated: 2026.05.14 # Actor input Schema ## `search_mode` (type: `string`): Which Apple Maps result family to return. 'search' returns the broad mix (local listings, guides, and the refinement object). 'place' resolves a specific query to a single rich place detail object. 'guide' returns only curated Apple Maps guide collections. 'refinement' returns only the available toggles, multi-select filters, and sort options for the query. ## `query` (type: `string`): The Apple Maps search term. Examples: 'coffee', 'dentists', 'plumbers in Brooklyn', 'Apple Park Cupertino', 'best ramen'. Combine with location or center for geo-targeted results. Required for every mode. ## `location` (type: `string`): City-level location name (e.g., 'Austin, Texas, United States', 'London', 'Brooklyn, New York'). Either this OR 'center' must be provided. Cannot be combined with 'center'. ## `center` (type: `string`): Geographic center as 'latitude,longitude' (e.g., '30.3246,-97.7305'). Use instead of 'location' for fine-grained coordinate targeting. Either this OR 'location' must be provided. Cannot be combined with 'location'. ## `span` (type: `string`): Viewport dimensions as 'latitudeDelta,longitudeDelta' (e.g., '0.5,0.5'). Larger values widen the search radius. Default is '0.5,0.5'. Optional. ## `sort` (type: `string`): How to sort local results. 'default' lets Apple Maps decide; 'distance' sorts by proximity to the center; 'ratings' sorts by rating descending. ## `toggles` (type: `array`): Single-value filter keys to apply (e.g., \['open\_now'], \['drive\_thru'], \['TOP\_RATED']). Discoverable via 'refinement' mode. Sent as a comma-joined list to the upstream API. ## `multi_select_options` (type: `array`): Multi-value filter keys (chains, amenities, price tiers) discovered via 'refinement' mode. Pass each option key as a separate array element. ## `open_at` (type: `integer`): Unix timestamp (seconds) for an 'open at this time' filter. Must be in the future and within the next 24 hours. Optional. ## `locale` (type: `string`): Language and region code for the response (e.g., 'en-US', 'en-GB', 'fr-FR', 'de-DE'). Defaults to 'en-US'. ## `max_results` (type: `integer`): Caps how many local\_result or guide\_result items are kept and billed. Set 0 for unlimited (bounded by a safety cap of 100). Default 20. Ignored for 'place' and 'refinement' modes which always return a single object. ## Actor input object example ```json { "search_mode": "search", "query": "coffee", "location": "Austin, Texas, United States", "span": "0.5,0.5", "sort": "default", "locale": "en-US", "max_results": 20 } ``` # Actor output Schema ## `allResults` (type: `string`): Complete dataset for this run. Each item is one Apple Maps response and contains the result fields appropriate to its search\_mode. ## `overview` (type: `string`): Filtered view focused on mode, timestamps, counts, and the populated result fields. Easier to scan for quick triage. # 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 = { "query": "coffee", "location": "Austin, Texas, United States", "span": "0.5,0.5", "locale": "en-US" }; // Run the Actor and wait for it to finish const run = await client.actor("johnvc/apple-maps-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "query": "coffee", "location": "Austin, Texas, United States", "span": "0.5,0.5", "locale": "en-US", } # Run the Actor and wait for it to finish run = client.actor("johnvc/apple-maps-api").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 '{ "query": "coffee", "location": "Austin, Texas, United States", "span": "0.5,0.5", "locale": "en-US" }' | apify call johnvc/apple-maps-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=johnvc/apple-maps-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Apple Maps API | Places, Guides, Local Search & Refinements", "description": "Scrape Apple Maps and extract local business listings, place details, curated guides, and refinement filters in one Actor. Phone, ratings, reviews, hours, address, GPS, amenities, multi-source ratings. City-name or coordinate targeting. Pay per result. MCP-ready for Claude, ChatGPT, Cursor.", "version": "0.0", "x-build-id": "ynONGDkWfwaitStxW" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~apple-maps-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-apple-maps-api", "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/johnvc~apple-maps-api/runs": { "post": { "operationId": "runs-sync-johnvc-apple-maps-api", "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/johnvc~apple-maps-api/run-sync": { "post": { "operationId": "run-sync-johnvc-apple-maps-api", "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": [ "search_mode", "query" ], "properties": { "search_mode": { "title": "Search Mode", "enum": [ "search", "place", "guide", "refinement" ], "type": "string", "description": "Which Apple Maps result family to return. 'search' returns the broad mix (local listings, guides, and the refinement object). 'place' resolves a specific query to a single rich place detail object. 'guide' returns only curated Apple Maps guide collections. 'refinement' returns only the available toggles, multi-select filters, and sort options for the query.", "default": "search" }, "query": { "title": "Search Query", "minLength": 1, "type": "string", "description": "The Apple Maps search term. Examples: 'coffee', 'dentists', 'plumbers in Brooklyn', 'Apple Park Cupertino', 'best ramen'. Combine with location or center for geo-targeted results. Required for every mode." }, "location": { "title": "Location (place name)", "type": "string", "description": "City-level location name (e.g., 'Austin, Texas, United States', 'London', 'Brooklyn, New York'). Either this OR 'center' must be provided. Cannot be combined with 'center'." }, "center": { "title": "Center (lat,lng)", "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$", "type": "string", "description": "Geographic center as 'latitude,longitude' (e.g., '30.3246,-97.7305'). Use instead of 'location' for fine-grained coordinate targeting. Either this OR 'location' must be provided. Cannot be combined with 'location'." }, "span": { "title": "Span (latDelta,lngDelta)", "type": "string", "description": "Viewport dimensions as 'latitudeDelta,longitudeDelta' (e.g., '0.5,0.5'). Larger values widen the search radius. Default is '0.5,0.5'. Optional." }, "sort": { "title": "Sort Order", "enum": [ "default", "distance", "ratings" ], "type": "string", "description": "How to sort local results. 'default' lets Apple Maps decide; 'distance' sorts by proximity to the center; 'ratings' sorts by rating descending.", "default": "default" }, "toggles": { "title": "Toggles", "type": "array", "description": "Single-value filter keys to apply (e.g., ['open_now'], ['drive_thru'], ['TOP_RATED']). Discoverable via 'refinement' mode. Sent as a comma-joined list to the upstream API.", "items": { "type": "string" } }, "multi_select_options": { "title": "Multi-Select Options", "type": "array", "description": "Multi-value filter keys (chains, amenities, price tiers) discovered via 'refinement' mode. Pass each option key as a separate array element.", "items": { "type": "string" } }, "open_at": { "title": "Open-At Timestamp", "minimum": 0, "type": "integer", "description": "Unix timestamp (seconds) for an 'open at this time' filter. Must be in the future and within the next 24 hours. Optional." }, "locale": { "title": "Locale", "type": "string", "description": "Language and region code for the response (e.g., 'en-US', 'en-GB', 'fr-FR', 'de-DE'). Defaults to 'en-US'." }, "max_results": { "title": "Maximum Results", "minimum": 0, "maximum": 100, "type": "integer", "description": "Caps how many local_result or guide_result items are kept and billed. Set 0 for unlimited (bounded by a safety cap of 100). Default 20. Ignored for 'place' and 'refinement' modes which always return a single object.", "default": 20 } } }, "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 } } } } } } } } } } ```