# Apple Maps (/docs/apple_maps) Search Apple Maps places in a map box, then read up to 50 places by id with ratings, hours, amenities and menus Apple Maps lists businesses and places worldwide with their ratings, opening hours, contact details, photos and amenities. These endpoints search a map area for a query and read places in bulk by their Apple Maps id. Every place uses the canonical `Place` shape. Base URL: `/v1/apple_maps/...` Apple Maps exposes 2 routes here. ## Quickstart ### Search a map box Send what you are looking for as `query` and the area as `bbox`, four decimal degrees in the order west, north, east, south (the same order GET /v1/yelp/search takes). ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/apple_maps/search?query=coffee&bbox=-74.000,40.765,-73.970,40.745" \ -H "x-api-key: YOUR_API_KEY" ``` ```json title="Response (trimmed)" { "success": true, "data": { "items": [ { "place": { "id": "5144915183449522016", "name": "Culture Espresso", "url": "https://maps.apple.com/place?auid=5144915183449522016", "category": "Coffee & tea", "rating": { "value": 4.5, "max": 5 }, "reviews_count": 1469, "address": "72 W 38th St, New York, NY 10018", "ext": { "rating_source": "Yelp", "yelp_id": "culture-espresso-new-york", "weekly_hours": { "monday": ["07:00 - 19:00"] }, "rank": 1 } } } ] } } ``` ### Read places by id Take `place.id` from search rows and send up to 50 of them, comma-separated, as `ids`. One call returns them all, in the order you sent them. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/apple_maps/places?ids=5144915183449522016,4568414994170597789" \ -H "x-api-key: YOUR_API_KEY" ``` ```json title="Response (trimmed)" { "success": true, "data": { "items": [ { "place": { "id": "5144915183449522016", "name": "Culture Espresso", "category": "Espresso Bar", "rating": { "value": 93, "max": 100 }, "reviews_count": 98, "verified": true, "ext": { "rating_source": "Apple", "category_ratings": [ { "category": "Food & Drink", "label": "Food & Drink", "value": 97, "max": 100 } ], "amenities": ["Accepts Apple Pay", "Free Wi-Fi"], "menu_url": "https://www.yelp.com/menu/culture-espresso-new-york" } } } ] } } ``` ## Questions people ask ### Why are some ratings out of 100 and others out of 5? Apple rates places itself on a 0 to 100 scale, with sub-ratings for food and drink, atmosphere and customer service. Places Apple has not rated show a partner's rating instead, Yelp's out of 5. `place.rating.max` always gives the scale, and `place.ext.rating_source` says who rated. Nothing is rescaled, so compare ratings only on the same scale. ### What happens if one of my ids is wrong? The other places still come back. An id Apple Maps does not know is left out and named in `data._warnings`. A lookup where none of the ids is known returns an empty list and is not charged. ### How do I cover a whole city? One search covers one map box and returns about 20 places. Split the city into smaller boxes and search them side by side. A point (`lat` with `lng`) covers a much smaller area than a box, so prefer boxes. ### Can I join these places to Yelp? Yes. Search rows carry `place.ext.yelp_id`, which GET /v1/yelp/business/info and GET /v1/yelp/business/reviews take. ## All endpoints ## Platform notes **`place.id` is the Apple Maps id.** It is the id `places` takes, and `place.url` is the Apple Maps link built from it. **Opening hours are by weekday.** `place.ext.weekly_hours` maps `monday` to `sunday` to a list of ranges such as `07:00 - 19:00`, in the place's own time zone (`place.ext.timezone`). **A search can take up to 30 seconds** when Apple Maps is slow to answer; most answer in a few seconds. ## Next steps - [Yelp](/docs/yelp.md): Reviews and business details for the same places. - [Google Business](/docs/google.md): Google Maps places, reviews and popular times.