openapi: 3.0.0
info:
  title: Apple Maps Guides API
  description: |
    Fetch a full Apple Maps editorial guide (curated place collection) in JSON format: the guide's title, description, publisher, and cover photos, plus every member place with full details, the guide's editorial review snippet for it, and a link to the publisher's own article.

    **Cross-linking**: Pass a `guide_id` value from the `guide_results` of the Apple Maps API. The member places carry `place_id` values usable with the other Apple Maps APIs.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Apple Maps Guides
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          schema:
            type: string
            enum: ["apple_maps_guides"]
          description: Search engine to use. Must be set to apple_maps_guides.
        - name: guide_id
          in: query
          required: true
          schema:
            type: string
            maxLength: 30
            pattern: '^\d+$'
          description: The numeric identifier of the guide to fetch, returned as guide_id in the guide_results of the Apple Maps API. It also appears as the curated query parameter of maps.apple.com/guides URLs.
        - 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 guide and 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'
        guide:
          $ref: '#/components/schemas/Guide'
        place_results:
          type: array
          description: The guide's member places, in guide order
          items:
            $ref: '#/components/schemas/PlaceResult'
        error:
          type: string
          description: Error message when the guide_id doesn't 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
        guide_id:
          type: string
          description: The requested guide identifier
        country:
          type: string
          description: The country code of the request
        lang:
          type: string
          description: The language of the guide and place details
    Guide:
      type: object
      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: Extended title of the guide
        description:
          type: string
          description: Editorial description of the guide
        description_html:
          type: string
          description: Editorial description with HTML markup, only when it differs from the plain text. Contains the publisher's markup verbatim; sanitize before rendering.
        language:
          type: string
          description: 'BCP 47 language tag Apple returns for the guide, reflecting the requested locale rather than a guarantee of the editorial content language (e.g. "en-US")'
        date_modified:
          type: string
          format: date-time
          description: When the guide was last updated
        link:
          type: string
          description: Apple Maps URL of the guide
        direct_link:
          type: string
          description: The publisher's own article for this guide
        publisher:
          $ref: '#/components/schemas/Publisher'
        media_link:
          type: object
          description: The App Store app Apple associates with the guide (e.g. the publisher's own app)
          properties:
            app_id:
              type: string
              description: App Store identifier (adam id) of the associated app
            type:
              type: string
              description: 'The kind of media linked (e.g. "app")'
        images:
          type: array
          description: Cover photos of the guide with source credits
          items:
            $ref: '#/components/schemas/Image'
        places_count:
          type: integer
          description: Number of member places in the guide
    PlaceResult:
      type: object
      properties:
        position:
          type: integer
          description: Position of the place, matching the guide 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'
        editorial_photos:
          type: array
          description: The publisher's curated photo(s) for this place within the guide (with the credit as source), distinct from the place's own images
          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)
        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
        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)'
    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:
      description: An editorial list of places as embedded in a place's guides (the Guide shape plus the per-place editorial snippet)
      allOf:
        - $ref: '#/components/schemas/Guide'
        - type: object
          properties:
            review_snippet:
              type: string
              description: The guide's editorial write-up of this place (present on a place's guides)
    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
        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