openapi: 3.0.0 info: title: Apple Maps Places API description: | Look up full Apple Maps place details for one or more places in a single batch request. Each place comes back with its name, category, address, phone number, website, ratings, reviews, opening hours, amenities, photos, and GPS coordinates in JSON format. **Cross-linking**: Pass the `place_id` values returned by the Apple Maps API as the `place_ids` parameter. Identifiers Apple can't resolve are echoed back in `not_found_places`, so `place_results` may contain fewer places than requested. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Apple Maps Places security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true schema: type: string enum: ["apple_maps_places"] description: Search engine to use. Must be set to apple_maps_places. - name: place_ids in: query required: true schema: type: string maxLength: 500 pattern: '^(I[0-9A-Fa-f]+|\d+)(,\s*(I[0-9A-Fa-f]+|\d+))*$' description: A comma-separated list of up to 20 Apple Maps place identifiers to look up in a single request. Each value is a place_id returned by the Apple Maps API — the same identifier used in maps.apple.com place URLs. Raw decimal identifiers are also accepted. Identifiers Apple can't resolve are echoed back in not_found_places. - name: country in: query required: false schema: type: string default: "us" enum: ["au", "bd", "br", "ca", "cn", "cz", "de", "dk", "es", "fi", "fr", "gb", "gr", "hk", "hr", "hu", "id", "il", "in", "it", "jp", "kr", "mx", "my", "nl", "no", "pk", "pl", "pt", "ro", "ru", "sa", "se", "si", "sk", "th", "tr", "tw", "ua", "us", "vn"] description: The country where the request is coming from, as a two-letter country code. Apple uses it to localize region-specific content, such as rating providers and formats. Defaults to us. - name: lang in: query required: false schema: type: string default: "en" enum: ["ar", "bn", "ca", "cs", "da", "de", "el", "en", "es", "fi", "fr", "gu", "he", "hi", "hr", "hu", "id", "it", "ja", "kn", "ko", "ml", "mr", "ms", "nb", "nl", "or", "pa", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "ta", "te", "th", "tr", "uk", "ur", "vi", "zh"] description: The language the place details are returned in. Defaults to en. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' place_results: type: array description: One entry per resolved place, in request order items: $ref: '#/components/schemas/PlaceResult' not_found_places: type: array description: Requested place_ids Apple could not resolve, echoed back in the form they were sent. Present only when some but not all ids resolve. items: type: string error: type: string description: Error message when none of the requested place_ids resolve SearchMetadata: type: object properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Apple Maps URL for this request html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine used place_ids: type: string description: The requested comma-separated place identifiers country: type: string description: The country code of the request lang: type: string description: The language of the place details PlaceResult: type: object properties: position: type: integer description: Position of the place, matching the request order place_id: type: string description: Apple's unique place identifier, matching the place-id in maps.apple.com URLs provider_id: type: string description: Apple's data provider identifier for the result title: type: string description: Name of the place link: type: string description: Apple Maps URL for the place description: $ref: '#/components/schemas/Description' address: type: string description: Formatted address of the place structured_address: $ref: '#/components/schemas/StructuredAddress' neighborhood: type: string description: 'The neighborhood or containing place Apple shows next to the category (e.g. "Flatiron, Manhattan")' phone: type: string description: Phone number of the place phone_formatted: type: string description: Phone number formatted for display price: type: string description: Price level expressed as dollar signs (e.g. "$$") price_score: type: integer description: Numeric price level max_price_score: type: integer description: Maximum possible price level rating: type: number description: Overall rating score max_rating: type: number description: Maximum possible rating score rating_type: type: string description: 'The rating scale in use: "apple_rating" (Apple''s percentage of visitors who recommend the place, out of 100) or "user_rating" (a third-party score, e.g. Yelp''s out of 5). Don''t compare ratings across different types.' rating_source: type: string description: The provider of the rating (e.g. Apple) reviews: type: integer description: Number of ratings used to compute the overall score reviews_formatted: type: string description: 'Abbreviated review count as displayed (e.g. "2.8K")' subratings: type: array description: Per-category rating breakdown (Food & Drink, Atmosphere, Customer Service) items: $ref: '#/components/schemas/Subrating' user_reviews: $ref: '#/components/schemas/UserReviews' website: type: string description: Website URL of the place is_unclaimed: type: boolean description: Present and true when the listing is still open to be claimed by its owner is_claimed: type: boolean description: Present and true when the listing has already been claimed by its owner claim_listing_link: type: string description: URL to claim the business listing gps_coordinates: $ref: '#/components/schemas/GpsCoordinates' bounds: $ref: '#/components/schemas/Bounds' access_points: type: array description: Curated road and walking access points for the place (e.g. the parking entrance driving navigation should end at) items: $ref: '#/components/schemas/AccessPoint' type: type: string description: The place's primary (most specific) category type_id: type: string description: Identifier of the primary category type_path: type: string description: Apple's full dotted path of the primary category, from broadest to most specific (e.g. dining.restaurant.bbq_restaurant) alt_type_paths: type: array description: Apple's full dotted paths of the place's secondary categories (e.g. a grocery store that is also a restaurant), mirroring type_path items: type: string place_type: type: string description: 'Apple''s high-level place classification (e.g. "business", "poi", "landmark")' types: type: array description: All categories associated with the place items: type: string type_ids: type: array description: Identifiers of all categories associated with the place items: type: string open_state: type: string description: 'Current open status derived from the opening hours, the place''s timezone, and the search time. A language-neutral enum (one of "open", "closed", "open_24_hours", or "closing_soon") that stays stable across the `lang` parameter; the exact closing time is in open_hours.' enum: - open - closed - open_24_hours - closing_soon open_hours: $ref: '#/components/schemas/OpenHours' linked_services: type: array description: Services attached to the place that keep their own schedules (e.g. Delivery Service, Drive-Through Service) items: $ref: '#/components/schemas/LinkedService' timezone: type: string description: Timezone identifier of the place actions: type: array description: Third-party actions surfaced for the place (Order, Reserve, Menu, ...), each grouping one or more provider links items: $ref: '#/components/schemas/Action' amenities: type: array description: Amenities available at the place items: $ref: '#/components/schemas/Amenity' awards: type: array description: Awards and recognition (e.g. MICHELIN Bib Gourmand) items: $ref: '#/components/schemas/Award' located_in: type: string description: Name of the parent place that contains this place contained_place: $ref: '#/components/schemas/ContainedPlace' external_ids: type: array description: The place's identifiers in third-party providers' systems (TripAdvisor, Foursquare, Michelin, ...), usable as join keys to those providers' own APIs items: $ref: '#/components/schemas/ExternalId' similar_places_nearby: type: array description: Other places Apple relates to this one items: $ref: '#/components/schemas/PlaceReference' images: type: array description: Photos of the place, each with its category and source items: $ref: '#/components/schemas/Image' thumbnail: type: string description: URL of the place's primary thumbnail image cover_photo: type: string description: URL of the curated wide cover photo branded businesses ship (e.g. chains) logo: type: string description: URL of the business's square logo image guides: type: array description: Editorial guides this place is featured in items: $ref: '#/components/schemas/Collection' StructuredAddress: type: object description: The address broken down into its administrative components properties: short: type: string description: Short form of the address city_and_above: type: string description: City and higher-level administrative parts of the address country: type: string description: Country name country_code: type: string description: Two-letter country code administrative_area: type: string description: Top-level administrative area (e.g. state) administrative_area_code: type: string description: Code for the administrative area sub_administrative_area: type: string description: Sub-administrative area (e.g. county) locality: type: string description: Locality (e.g. city) post_code: type: string description: Postal code sub_locality: type: string description: Sub-locality (e.g. neighborhood) sub_thoroughfare: type: string description: Street number of the address (e.g. "600") thoroughfare: type: string description: Street name full_thoroughfare: type: string description: Street name including the number area_of_interest: type: string description: Named area of interest dependent_locality: type: array description: Dependent localities (e.g. district or neighborhood names) items: type: string sub_premise: type: array description: Sub-premise unit names (e.g. suites or units) items: type: string formatted_lines: type: array description: Address lines as displayed items: type: string GpsCoordinates: type: object description: Geographic coordinates of the place properties: latitude: type: number description: Latitude of the place longitude: type: number description: Longitude of the place Bounds: type: object description: Apple's display bounding box for the place — the viewport Apple Maps zooms to when showing it properties: north_latitude: type: number description: Latitude of the northern edge south_latitude: type: number description: Latitude of the southern edge east_longitude: type: number description: Longitude of the eastern edge west_longitude: type: number description: Longitude of the western edge AccessPoint: type: object description: A curated access point for reaching the place properties: gps_coordinates: $ref: '#/components/schemas/GpsCoordinates' driving_direction: type: string description: How driving navigation uses this point (e.g. destination) walking_direction: type: string description: How pedestrians use this point (e.g. entry_exit) source: type: string description: Where the access point data comes from (e.g. access_point_service_curated) OpenHours: type: object description: 'Day-keyed opening hours; each day is an array of language-neutral 24-hour ranges (e.g. ["00:00–01:00", "04:00–24:00"])' properties: monday: type: array items: type: string tuesday: type: array items: type: string wednesday: type: array items: type: string thursday: type: array items: type: string friday: type: array items: type: string saturday: type: array items: type: string sunday: type: array items: type: string LinkedService: type: object description: A service attached to the place with its own weekly schedule properties: name: type: string description: Name of the service (e.g. Delivery Service, Drive-Through Service) open_hours: $ref: '#/components/schemas/OpenHours' UserReviews: type: object description: Third-party user reviews surfaced for the place properties: source: type: string description: The provider of the reviews (e.g. Yelp, Tripadvisor) source_logo: type: string description: URL of the review provider's logo link: type: string description: 'Deep link to view all reviews on the provider (e.g. "See all reviews on Yelp")' most_relevant: type: array items: $ref: '#/components/schemas/UserReview' UserReview: type: object properties: username: type: string description: Name of the reviewer rating: type: number description: The reviewer's rating score max_rating: type: number description: Maximum possible rating score rating_type: type: string description: 'The rating scale for this review: "user_rating" (e.g. Yelp''s out of 5) or "apple_rating" (out of 100), so a score can be read on the right scale' user_thumbnail: type: string description: URL of the reviewer's profile image description: type: string description: Text snippet of the review link: type: string description: URL to view the full review iso_date: type: string format: date-time description: ISO 8601 timestamp of the review id: type: string description: Identifier of the review Action: type: object properties: text: type: string description: The action label (e.g. Order, Reserve) link: type: string description: The provider link for the action type: type: string description: 'The kind of link Apple ships for the action: "app_clip_link" (an App Clip experience) or "quick_link" (a plain web link)' category: type: string description: 'Apple''s language-neutral semantic category for the action (e.g. "quicklinks.restaurant_order_food", "quicklinks.restaurant_reservation", "quicklinks.restaurant_view_menu", "quicklinks.buy_tickets"); stable across the `lang` parameter, unlike the localized `text`' app_id: type: string description: Apple App Store identifier (adam id) of the provider's app behind the action is_authorized: type: boolean description: Present and true when the provider is an authorized Apple Maps partner for this action Award: type: object properties: name: type: string description: Name of the award (e.g. Bib Gourmand) source: type: string description: The awarding body vendor_id: type: string description: Identifier of the awarding vendor (e.g. com.michelin) ContainedPlace: type: object description: The parent place that contains this place properties: title: type: string description: Name of the parent place place_id: type: string description: Apple's unique place identifier for the parent place provider_id: type: string description: Apple's data provider identifier for the parent place link: type: string description: Apple Maps URL for the parent place ExternalId: type: object description: The place's identifier in a third-party provider's system properties: vendor_id: type: string description: Identifier of the third-party vendor (e.g. com.tripadvisor) id: type: string description: The place's identifier within that vendor's system Amenity: type: object properties: amenity_id: type: string description: Apple's dotted amenity identifier (e.g. crossbusiness.services.take_out); the rare places without the richer amenity data fall back to a legacy enum identifier (e.g. ACCEPTS_CREDIT_CARDS) title: type: string description: Amenity name (e.g. Accepts Credit Cards), localized by Apple following the lang parameter; legacy fallback entries derive an English title from the identifier instead vendor_id: type: string description: The vendor that confirmed the amenity (e.g. com.yelp) Subrating: type: object description: A single per-category rating (e.g. Food & Drink) properties: category: type: string description: Rating category (e.g. Food & Drink, Atmosphere, Customer Service) rating: type: number description: Category rating score max_rating: type: number description: Maximum possible rating score reviews: type: integer description: Number of ratings used for this category score PlaceReference: type: object description: A reference to another place by id properties: place_id: type: string description: Apple's unique place identifier, matching the place-id in maps.apple.com URLs provider_id: type: string description: Apple's data provider identifier for the place link: type: string description: Apple Maps URL for the place Description: type: object description: Apple's editorial blurb about the place, with optional facts and source attribution properties: text: type: string description: The editorial text about the place facts: type: array description: Quantitative facts about the place (Area, Height, ...) items: $ref: '#/components/schemas/Fact' source: type: object description: The source the editorial text is attributed to properties: name: type: string description: Name of the source (e.g. Wikipedia) link: type: string description: URL back to the source Fact: type: object properties: text: type: string description: The fact label (e.g. Area, Height) value: type: number description: The numeric value of the fact unit: type: string description: The unit of the value Image: type: object properties: title: type: string description: Caption of the photo source: type: string description: The provider of the photo (e.g. Apple Business Register) link: type: string description: Provider permalink to view the photo at its source (e.g. Foursquare) thumbnail: type: string description: URL of the photo at thumbnail resolution original: type: object description: The photo at full resolution properties: link: type: string description: URL of the full-resolution photo width: type: integer description: Width of the full-resolution photo in pixels height: type: integer description: Height of the full-resolution photo in pixels category_id: type: string description: Identifier of the photo category (e.g. from_owner) category_name: type: string description: Name of the photo category (e.g. Food & Drink) date_added: type: string format: date-time description: ISO 8601 timestamp of when the photo was added Collection: type: object description: An editorial list of places (e.g. "The Best Breweries in Austin") properties: guide_id: type: string description: Apple's unique identifier for the guide provider_id: type: string description: Apple's data provider identifier for the guide title: type: string description: Display title of the guide long_title: type: string description: Long-form title of the guide description: type: string description: Description of the guide description_html: type: string description: HTML version of the description, present only when it carries markup the plain text drops (e.g. publisher emphasis) review_snippet: type: string description: The guide's editorial write-up of this place (present on a place's guides) date_modified: type: string format: date-time description: ISO 8601 timestamp of when the guide was last modified link: type: string description: Apple Maps link to the curated guide direct_link: type: string description: URL of the publisher's article for the guide publisher: $ref: '#/components/schemas/Publisher' images: type: array items: $ref: '#/components/schemas/Image' places_count: type: integer description: Number of places in the guide Publisher: type: object description: The publisher of an editorial collection properties: publisher_id: type: string description: Apple's unique identifier for the publisher provider_id: type: string description: Apple's data provider identifier for the publisher title: type: string description: Name of the publisher subtitle: type: string description: Subtitle of the publisher source: type: string description: The publisher's source identifier link: type: string description: Publisher website URL guides_count: type: integer description: Total number of guides this publisher has on Apple Maps ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong