Pricing

Rating

Developer

Actor stats

Categories

Share

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. 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:

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

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)

{
"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.

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.
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 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 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