openapi: 3.0.0 info: title: Apple Maps API description: | Retrieve local search results from Apple Maps. Get businesses and places with names, addresses, phone numbers, ratings, reviews, opening hours, photos, and GPS coordinates in JSON format. Searches are anchored to a geographic region defined either by a `center` coordinate or a named `location`, with the region size controlled by `zoom` or `span`. Category and area searches additionally return editorial `guide_results`. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Apple Maps Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true schema: type: string enum: ["apple_maps"] description: Search engine to use. Must be set to apple_maps. - name: q in: query required: true schema: type: string maxLength: 1000 description: 'The search terms to look up on Apple Maps. Can include queries like "restaurants near me" or "Starbucks New York". Limited to 1000 characters.' - name: center in: query required: false schema: type: string pattern: '^-?\d+(\.\d+)?,\s*-?\d+(\.\d+)?$' description: 'Coordinates of the center point of the region to search within, in the latitude,longitude format (e.g. "40.712776,-74.005974"). Latitude must be between -90 and 90 and longitude between -180 and 180. center and location cannot be used together. When neither is provided, the search covers the whole world.' - name: location in: query required: false schema: type: string description: The search origin defined by name, resolved to GPS coordinates using the locations API (e.g. "Manhattan, New York, United States"). center and location cannot be used together. When neither is provided, the search covers the whole world. - name: zoom in: query required: false schema: type: integer minimum: 1 maximum: 20 description: How zoomed in the search region is, as an integer from 1 (widest area) to 20 (street level). Higher values search a smaller, more local area. When omitted, the default span applies. - name: span in: query required: false schema: type: string pattern: '^\d+(\.\d+)?,\s*\d+(\.\d+)?$' description: 'The exact size of the search area as two values in degrees — its north-south size, then its east-west size (e.g. "0.1,0.15" searches an area 0.1° tall and 0.15° wide). Both values must be greater than 0, with the north-south size up to 180 and the east-west size up to 360. Use instead of zoom for precise control or a non-square area. When both are provided, span takes precedence over zoom. Defaults to "0.35,0.35" (a local area) when a center or location is set, or "180,360" (the whole world) when there is no anchor.' - 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 search 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 interface language of the search. Defaults to en. - name: sort_by in: query required: false schema: type: string enum: ["best_match", "distance", "ratings"] description: 'Sort order for the results. One of "distance" (nearest first), "ratings" (highest rated first), or "best_match" (Apple''s default ranking, the default).' - name: filters in: query required: false schema: type: string maxLength: 2000 description: 'A comma-separated list of filter values to apply, each taken from the value field of an option in the filters array of a previous response (e.g. "OPEN_NOW,PRICE_RANGE_INEXPENSIVE"). Chain filters use the opaque chain: token returned in the response; readable values can also be passed directly. Treat the values as opaque tokens and pass them back exactly as returned — do not construct or interpret them. Limited to 2000 characters; at most the first 25 values are applied.' - name: open_at in: query required: false schema: type: string description: 'Limit results to places open at a given time. Accepts a time of day for today ("18:00"), a datetime ("2026-06-04T18:00:00"), or a datetime with a UTC offset ("2026-06-04T18:00:00-05:00" or "2026-06-04T18:00:00Z"). A time of day or offset-less datetime is interpreted in the timezone of the searched area; an explicit offset takes precedence. Must resolve to a time in the future and no more than 24 hours from now.' 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' search_information: $ref: '#/components/schemas/SearchInformation' local_results: type: array description: The businesses and places matching the search items: $ref: '#/components/schemas/LocalResult' guide_results: type: array description: Editorial guides Apple returns alongside places for area or category searches items: $ref: '#/components/schemas/GuideResult' filters: type: array description: The filters available for this search. Pass an option's value back via the filters parameter to refine results. items: $ref: '#/components/schemas/Filter' error: type: string description: Error message when no results are found 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 search 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 q: type: string description: The search query location: type: string description: The location name provided in the request location_used: type: string description: The resolved name of the location used for the search center: type: string description: The center coordinate of the search region center_used: type: string description: The resolved latitude,longitude coordinates the search was centered on zoom: type: integer description: The zoom level of the search region span: type: string description: The size of the search area in degrees, as its north-south size followed by its east-west size country: type: string description: The country code of the search lang: type: string description: The interface language of the search sort_by: type: string description: The sort order applied to the results filters: type: string description: The filter values applied to the search open_at: type: string description: The time the results were filtered to be open at SearchInformation: type: object description: Apple's echo of the search and the result count it displays properties: query_displayed: type: string description: The query Apple ran for this search total_results: type: integer description: 'Total number of matching places, parsed from the results-list header (e.g. "25 found")' total_results_displayed: type: string description: The raw localized results-list header, returned only when a count cannot be parsed from it Filter: type: object description: A group of related filter options (e.g. prices, chains, amenities) properties: key: type: string description: 'Stable, language-neutral identifier of the filter group (e.g. "open_now", "price", "chain", "amenities"); use it instead of the localized type for programmatic filtering' type: type: string description: The localized display name of the filter group (e.g. "All Prices", "Chains") options: type: array description: The selectable options within this filter group items: $ref: '#/components/schemas/FilterOption' FilterOption: type: object properties: text: type: string description: The display name of the option (e.g. "Open Now", "$") value: type: string description: The value to pass back via the filters parameter to apply this option is_selected: type: boolean description: Present and true when this option was applied via the filters parameter LocalResult: type: object properties: position: type: integer description: Position of the result in the list 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 GuideResult: allOf: - type: object properties: position: type: integer description: Position of the guide in the list places: type: array description: Member places of the guide, referenced by id items: $ref: '#/components/schemas/PlaceReference' - $ref: '#/components/schemas/Collection' 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