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:

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)

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