# 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:** 20 total users, 9 monthly users, 100.0% runs succeeded, 7 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $8.88 / 1,000 place details

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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.**

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](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=20`. 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.

***

### 💸 Pay per run with crypto (x402)

The Apple Maps API supports agentic payments via the [x402 protocol](https://docs.apify.com/platform/integrations/x402).
AI agents and MCP clients can pay for runs in USDC (on Base) with no Apify account or API token needed:
point your agent at the [Apify MCP server](https://mcp.apify.com/?tools=actors,docs,johnvc/apple-maps-api) and it can
discover, pay for, and run this Actor autonomously. Read the
[Apify x402 announcement](https://apify.com/change-log/pay-for-apify-actors-with-x402?fpr=9n7kx3) for details.

### 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](https://docs.apify.com/platform/integrations).

#### Tasks and schedules (the core recipe)

Save one [task](https://docs.apify.com/platform/actors/running/tasks) per thing you want to track, then attach a [schedule](https://docs.apify.com/platform/schedules) 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](https://apify.com/johnvc/apple-maps-api/examples/find-coffee-shop-leads-seattle-apple-maps?fpr=9n7kx3) 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:

```python
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](https://docs.apify.com/platform/integrations/n8n) docs.

#### Make and Zapier

The same pattern works without any code through [Make](https://docs.apify.com/platform/integrations/make) and [Zapier](https://docs.apify.com/platform/integrations/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](https://docs.apify.com/platform/integrations/webhooks) 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. Minimum effective value 20 (lower values are raised; the upstream call is billed the same either way). 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": 20
  },
  "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?fpr=9n7kx3).
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.
6. Prefer to work in code? The [example repo on GitHub](https://github.com/johnisanerd/Apify-Apple-Maps-API) 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](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3)** 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](https://apify.com/johnvc/google-maps-directions-api?fpr=9n7kx3)** turns the places you find into routes, distances, and travel times for itinerary and logistics work.
- **[Apple App Store Product API](https://apify.com/johnvc/apple-app-store-product-api?fpr=9n7kx3)** pulls app details, reviews, and pricing when your research spans Apple's app ecosystem, not just its map.
- **[Apple App Store Search](https://apify.com/johnvc/apple-app-store-search?fpr=9n7kx3)** 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](https://apify.com/knasterrrbuilds/maps-scraper?fpr=9n7kx3) 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](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.

#### 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](https://docs.apify.com/platform/actors/running/tasks) with your query and location frozen in, then open the task and use the **Actions** then **Schedule** menu to attach a [schedule](https://docs.apify.com/platform/schedules). 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](https://en.wikipedia.org/wiki/API) (where one exists, usually rate limited and quota bound) or a [web scraping](https://en.wikipedia.org/wiki/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](https://docs.apify.com/platform/integrations) the Actor connects to almost any cloud service: [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier), [Slack](https://docs.apify.com/platform/integrations/slack), Google Sheets, and more. For custom endpoints, attach a [webhook](https://docs.apify.com/platform/integrations/webhooks) 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](https://apify.com/johnvc/apple-maps-api/api?fpr=9n7kx3) 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](https://mcp.apify.com/), 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](https://claude.ai/referral/uIlpa7nPLg) (free trial), Claude Desktop, Cursor, and other MCP-aware agents. See the [Apify MCP docs](https://docs.apify.com/platform/integrations/mcp) 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](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3) and reconcile the two maps. For routing between places, use the [Google Maps Directions API](https://apify.com/johnvc/google-maps-directions-api?fpr=9n7kx3). For Apple's app ecosystem, the [Apple App Store Product API](https://apify.com/johnvc/apple-app-store-product-api?fpr=9n7kx3) and [Apple App Store Search](https://apify.com/johnvc/apple-app-store-search?fpr=9n7kx3) 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](https://www.apple.com/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](https://www.npmjs.com/package/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](https://apify.com/johnvc/apple-maps-api/examples/extract-apple-maps-business-listings-phone?fpr=9n7kx3) - Extract Apple Maps business listings with phone, address, rating, and hours.
- [Compare restaurant ratings in Austin on Apple Maps](https://apify.com/johnvc/apple-maps-api/examples/compare-restaurant-ratings-austin-apple-maps?fpr=9n7kx3) - Rank Austin restaurants by rating on Apple Maps with Apple, Yelp, Foursquare, and TripAdvisor scores.
- [Find coffee shop leads in Seattle from Apple Maps](https://apify.com/johnvc/apple-maps-api/examples/find-coffee-shop-leads-seattle-apple-maps?fpr=9n7kx3) - Find coffee shops in Seattle from Apple Maps with phone, address, rating, and hours.
- [Get curated Apple Maps guides for a city](https://apify.com/johnvc/apple-maps-api/examples/find-curated-apple-maps-guides?fpr=9n7kx3) - Get curated Apple Maps guides for a city, each grouping places under a theme.
- [Get Apple Maps place details by API](https://apify.com/johnvc/apple-maps-api/examples/get-apple-maps-place-details-by-api?fpr=9n7kx3) - Resolve any Apple Maps place to a full detail object.
- [Search Apple Maps places from Claude via MCP](https://apify.com/johnvc/apple-maps-api/examples/search-apple-maps-places-from-claude-via-mcp?fpr=9n7kx3) - Let Claude search Apple Maps through MCP.

***

### Where the data comes from

Every field this Actor returns is read from the public [Apple Maps](https://maps.apple.com) 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](https://maps.apple.com) 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](https://maps.apple.com), 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.

***

### 🌐 About Alpha OSINT

This Actor is part of [Alpha OSINT](https://www.alphaosint.com), toolset of financial and operations data sources and APIs.
See the [Apple Maps API source page](https://www.alphaosint.com/sources/apple-maps-api/) for related tools and use cases.
For support or requests for this actor, please start a ticket [directly on our support page](https://apify.com/johnvc/apple-maps-api/issues/open?fpr=9n7kx3).

Last Updated: 2026.09.10

# 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. In search and guide modes, values 1-19 are raised to 20: the upstream bills one full call regardless of size, so you receive at least 20 results at the same per-result price. 0 still means unlimited (safety cap 100).

## 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# 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(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,johnvc/apple-maps-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/N5VUB8TPw7s1QMuSX/builds/DqsgNO92odPQsU52W/openapi.json