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.

The Apple Maps API turns a search term plus a location into structured Apple Maps data in one call. 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.

---

🔌 Integrations: Automate Your Apple Maps API Data Pipeline

A single run answers one question. The real value shows up when you run the Apple Maps API on a schedule and let the data accumulate: a refreshed lead list every morning, a ratings history that grows week over week, a market map that stays current. Everything below plugs this Actor into that kind of recurring pipeline through the Apify platform integrations.

Tasks and schedules (the core recipe)

Save one task per thing you want to track, then attach a schedule so it reruns on its own. A task is just this Actor with your input frozen in (for example search_mode=search, query=coffee, location=Seattle, Washington, United States, sort=ratings). Open the task, use the Actions then Schedule menu, and pick a cron cadence:

• 0 7 * * * runs every day at 7 AM, good for a fresh local lead generation pull.
• 0 */6 * * * runs every six hours to catch rating and hours changes quickly.
• 0 9 * * 1 runs every Monday, a steady cadence for market mapping a category across a metro.

One schedule can trigger many tasks at once, so a single 7 AM run can refresh coffee shops in Seattle, ramen in Brooklyn, and dentists in Austin together. The Find coffee shop leads in Seattle featured task is a ready-made template you can save and schedule.

Store the data in Supabase (or any database)

Point each run at a database so results accumulate instead of expiring with the run. No-code path: in n8n, chain the Actor node into a Supabase node and map the fields. In code, run the Actor with apify-client and bulk-insert the flat local_results rows:

from apify_client import ApifyClient
from supabase import create_client

apify = ApifyClient("YOUR_APIFY_TOKEN")
supabase = create_client("YOUR_SUPABASE_URL", "YOUR_SUPABASE_KEY")

run = apify.actor("johnvc/apple-maps-api").call(run_input={
    "search_mode": "search",
    "query": "coffee",
    "location": "Seattle, Washington, United States",
    "sort": "ratings",
    "max_results": 50,
})

rows = []
for item in apify.dataset(run["defaultDatasetId"]).iterate_items():
    for place in item.get("local_results", []):
        rows.append({
            "title": place.get("title"),
            "address": place.get("address"),
            "phone": place.get("phone"),
            "website": place.get("website"),
            "rating": place.get("rating"),
            "reviews": place.get("reviews"),
            "latitude": (place.get("gps_coordinates") or {}).get("latitude"),
            "longitude": (place.get("gps_coordinates") or {}).get("longitude"),
        })

supabase.table("apple_maps_places").insert(rows).execute()

Run that on a schedule and the apple_maps_places table becomes a living record of how each business appears on Apple Maps over time.

n8n

This Actor ships as an n8n community node, so you can wire it into a low-code workflow with a Schedule Trigger, the Actor node, a Filter, and a Slack or email step. See the n8n integration section below for the package name and install steps, or read the Apify n8n integration docs.

Make and Zapier

The same pattern works without any code through Make and Zapier: trigger the Actor on a schedule, then route each result into a spreadsheet, CRM, or notification.

MCP and AI agents

For agent workflows, this Actor is a callable tool on the Apify MCP server. See the Use with Claude, ChatGPT, Cursor & other AI agents (MCP) section above for full setup. In short, an agent can pick the right search mode for a request like "map every ramen shop near Apple Park and rank them by rating" and hand back a clean list.

Webhooks

For anything custom, attach an Apify webhook on the ACTOR.RUN.SUCCEEDED event. Apify posts the run and dataset IDs to your endpoint the moment a run finishes, which is the glue for pushing fresh Apple Maps data into your own systems.

---

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.
6. Prefer to work in code? The example repo on GitHub has a Python quick-start plus MCP setup walkthroughs for Claude, Cursor, and ChatGPT.

---

🔗 Related Tools

Building a location dataset usually means pulling from more than one source. These related Actors from the same portfolio pair well with the Apple Maps API:

• Google Maps Places Scraper cross-references the same businesses on Google Maps for bulk places, so you can reconcile names, ratings, and address data across both maps.
• Google Maps Directions API turns the places you find into routes, distances, and travel times for itinerary and logistics work.
• Apple App Store Product API pulls app details, reviews, and pricing when your research spans Apple's app ecosystem, not just its map.
• Apple App Store Search returns App Store search results and keyword rankings for the same Apple-first competitive work.

For contrast, single-purpose alternatives such as this Apple Maps places scraper exist, but they accept only pre-collected place URLs, cover business listings alone (no curated guides, place-detail, or refinement modes), and show minimal adoption on the Store. This Actor searches by query or coordinates, returns all four Apple Maps result families under one schema, and is MCP-ready.

---

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.

Can I schedule this Apple Maps Actor?

Yes, and this is where the Actor earns its keep. Any input you can run once, you can run on repeat. Save a task with your query and location frozen in, then open the task and use the Actions then Schedule menu to attach a schedule. Cron strings set the cadence: 0 7 * * * for daily at 7 AM, 0 */6 * * * for every six hours, or 0 9 * * 1 for Mondays. One schedule can drive many tasks at once, so a single trigger can refresh several cities or categories together. See the Integrations section above for the full monitoring and storage recipe.

Should I use an Apple Maps API or a web scraper?

Apple does not publish an open places API for third-party business search, so your two practical options are an official API (where one exists, usually rate limited and quota bound) or a web scraping approach. This Actor gives you the strengths of both: a clean, structured JSON endpoint you call like an API, with no quotas or key management, plus no-code export to CSV or Excel like a scraper. You send a query and a location, you get back rows.

Can I integrate this Apple Maps Scraper with other apps?

Yes. Through Apify integrations the Actor connects to almost any cloud service: Make, Zapier, Slack, Google Sheets, and more. For custom endpoints, attach a webhook on ACTOR.RUN.SUCCEEDED. The Integrations section above has copy-paste recipes for the common ones.

Can I use this Actor with the Apify API?

Yes. The Apify API gives you programmatic control to start runs, attach schedules, and fetch datasets, and the apify-client package exists for both Python and Node.js. It is the same client used in the Integrations code snippet above.

Can I use Apple Maps through an MCP Server?

Yes. The Actor is a first-class tool on the hosted Apify MCP server, so any MCP client can call it in natural language. Point your client at https://mcp.apify.com/?tools=actors,docs,johnvc/apple-maps-api to load it directly. It works in Claude Code (free trial), Claude Desktop, Cursor, and other MCP-aware agents. See the Apify MCP docs for client setup.

How can I pull data from other maps and app-store tools?

Cluster this Actor with its neighbors depending on what you are building. For cross-source place data, run the Google Maps Places Scraper and reconcile the two maps. For routing between places, use the Google Maps Directions API. For Apple's app ecosystem, the Apple App Store Product API and Apple App Store Search cover app details and keyword rankings. See Related Tools above for the full list.

Does Apple Maps have an API?

Apple offers MapKit and a limited server-side API aimed mainly at map display, geocoding, and directions inside your own apps, not an open endpoint for bulk local business search with ratings and guides. This Actor fills that gap: it returns structured business listings, place details, curated guides, and refinement filters from Apple Maps without you managing Apple developer keys.

Is the Apple Maps API free?

Running this Actor is pay-per-result, so you are billed only for the listings, place details, guides, or refinement bundles a run actually returns (see Pricing above), plus your normal Apify platform usage. There is no separate Apple subscription or API key to buy, and a misconfigured run that fails validation is not charged.

Can you use the Apple Maps API for lead generation and market mapping?

Yes. Local lead generation and market mapping are the two most common jobs users run this for. Pull every business in a category across a coordinate span with phone, address, website, and rating for outbound lists, or aggregate a whole category to size a market and see who ranks where. Both scale cleanly on a schedule (see the Integrations section above).

What is h3.apis.apple.map.fastly.net?

That hostname is one of the content-delivery endpoints Apple uses to serve Apple Maps tile and place data. You do not need to call it or think about it to use this Actor: you send a query and a location anchor, and the Actor returns clean, structured JSON. It is mentioned here only because people searching that string are usually trying to pull Apple Maps data programmatically, which is exactly what this Actor does.

---

n8n integration

Available as an n8n community node, n8n-nodes-apple-maps-api. In n8n: Settings, Community Nodes, install n8n-nodes-apple-maps-api, then use it in any workflow (it also works as an AI Agent tool).

---

Featured Tasks

Ready-to-run examples that show this API solving a specific problem. Each opens its own setup so you can run it on your account in one click.

• Extract Apple Maps business listings with phone numbers - Extract Apple Maps business listings with phone, address, rating, and hours.
• Compare restaurant ratings in Austin on Apple Maps - Rank Austin restaurants by rating on Apple Maps with Apple, Yelp, Foursquare, and TripAdvisor scores.
• Find coffee shop leads in Seattle from Apple Maps - Find coffee shops in Seattle from Apple Maps with phone, address, rating, and hours.
• Get curated Apple Maps guides for a city - Get curated Apple Maps guides for a city, each grouping places under a theme.
• Get Apple Maps place details by API - Resolve any Apple Maps place to a full detail object.
• Search Apple Maps places from Claude via MCP - Let Claude search Apple Maps through MCP.

---

Where the data comes from

Every field this Actor returns is read from the public Apple Maps surface: the business listings for a query, the curated guides Apple attaches to it, and the toggle, multi-select, and sort options Apple offers for narrowing it down. Nothing is blended in from a second map. If a listing has no phone number on Apple Maps, phone comes back empty instead of being filled from somewhere else.

This is an independent Actor. It is not affiliated with, endorsed by, or operated by Apple Inc., and it is not Apple's own API or a drop-in replacement for MapKit. What it does is make the same public data addressable: send a query plus a location or a center, and you get rows carrying title, address, phone, website, rating, reviews, weekly_hours, and gps_coordinates wherever Apple publishes them.

How is this different from searching Apple Maps by hand?

Scale and repeatability. Typing a query into Apple Maps gives you one result card at a time and no export button, which is fine for picking a lunch spot and slow going when you need 80 dentists across three metros with phone numbers attached. The Actor runs the same search, hands back the whole result set as JSON, CSV, or Excel, and can rerun on a schedule, so this week's ratings can be diffed against last week's rather than re-read off the map.

Do I need an Apple ID or an Apple developer account?

No. There is no sign-in to Apple Maps, no MapKit registration, and no Apple key to rotate. Your Apify account is the only credential in the loop, and you are billed per result under the pay-per-event table above.

---

Last Updated: 2026.07.14