Apple Maps Refinement API

SerpApi Apple Maps API provides the refinement object in responses which scrapes the possible filtering and sorting options that can be used to narrow down search results. This can be used to get values to provide to refinement parameters when making requests:

toggles
sorts
multi_select_options
open_at

The API endpoint is https://serpapi.com/search?engine=apple_maps

Head to the playground for a live and interactive demo.

API Examples

Results with toggles & sorts parameters

You can use toggles parameter to apply toggle filters to search results. To use them, pass the key value for toggle. See the refinements.toggles object of the response to see available toggles for a search.

You can use sort parameter to apply sorting to search results. Use ratings to sort results by their user ratings or use distance to sort results by how close they are to the center.

To apply multiple refinements, use , (comma) to separate the keys. For example: TOGGLE_A,TOGGLE_B to apply multiple toggles.

In the following example we filter by OPEN_NOW and DRIVE_THRU, and sort by ratings

JSON Example

{
  ...
  "refinement": {
    "toggles": {
      "open_now": {
        "display_name": "Open Now",
        "key": "OPEN_NOW",
        "is_selected": true
      },
      "drive_thru": {
        "display_name": "Drive-Thru",
        "key": "DRIVE_THRU",
        "is_selected": true
      },
      "top_rated": {
        "display_name": "Top Rated",
        "key": "TOP_RATED"
      },
      ...
    },
    "sort": "ratings",
    ...
  }
}

Results with multi-select refinement

You can use multi_select_options parameter to apply multi select filters to search results. They can be used to narrow search results by amenities present, chains that restaurants may belong to and more. To use them you can pass keys from the options you want apply. See the refinement.multi_select.<type>.options object of the response to see available multi select refinements for the search.

To apply multiple refinements, use , (comma) to separate the keys. For example: OPTION_KEY_A,OPTION_KEY_B to select multiple options. From each multi select refinement you can chose multiple options to filter by.

In the following example we filter results which belong to the chain Starbucks and have Outdoor Dining

JSON Example

{
  ...
  "refinement": {
    "multi_select": {
      "chain": {
        "display_name": "Starbucks",
        "options": [
          {
            "display_name": "Starbucks",
            "is_selected": true,
            "key": "CHAIN:ANY:BYTES:792633534485581296:CAIQBiIqChI3OTI2MzM1MzQ0ODU1ODEyOTYSCVN0YXJidWNrcxoJU3RhcmJ1Y2tz"
          },
          {
            "display_name": "Summer Moon Coffee",
            "key": "CHAIN:ANY:BYTES:792633534690909972:CAIQBiI8ChI3OTI2MzM1MzQ2OTA5MDk5NzISElN1bW1lciBNb29uIENvZmZlZRoSU3VtbWVyIE1vb24gQ29mZmVl"
          }
          ...
        ]
      },
      "amenity": {
        "display_name": "Outdoor Seating",
        "options": [
          {
            "display_name": "Outdoor Seating",
            "is_selected": true,
            "key": "BUSINESS_ATTRIBUTE:ALL:STRING:OUTDOOR_SEATING:"
          },
          {
            "display_name": "Accepts Apple Pay",
            "key": "BUSINESS_ATTRIBUTE:ALL:STRING:ACCEPTS_APPLE_PAY:"
          }
          ...
        ]
      },
      ...
    }
    ...
  }
}

Results with open_at refinement

You can use open_at parameter to filter results to those locations which are open at a specific time. The provided time should be a unix epoch timestamp in seconds, that is in the future, and not beyond 24 hours from now. For example: 1777690399 to check places open 10 hours from now.

JSON Example

{
  ...
  "refinement": {
    "open_at": 1777690399,
    ...
  }
}

JSON structure overview

{
  ...
  "refinement": {
    "toggles": {
      "open_now": {
        "display_name": "String - Toggle name",
        "key": "String - Toggle refinement key",
        "is_selected": "Boolean - Present when this toggle has been applied"
      },
      "top_rated": {
        "display_name": "...",
        "key": "...",
      },
      "Toggle names ...": {
        "display_name": "...",
        "key": "...",
      },
      ...
    },
    "multi_select": {
      "chain": {
        "display_name": "String - Multi-select group name",
        "options": [
          {
            "display_name": "String - Option name",
            "is_selected": "Boolean - Present when this option has been applied",
            "key": "String - Option key used with multi_select_options"
          },
          ...
        ]
      },
      "price": {
        "display_name": "...",
        "options": [...]
      },
      "amenity": {
        "display_name": "...",
        "options": [...]
      },
      "Multi select group names ...": {
        "display_name": "...",
        "options": [...]
      },
      ...
    },
    "sort": "String - Selected sort key, `distance` or `ratings`. `default` if no sort has been applied",
    "open_at": "Integer - Unix epoch timestamp for the selected open_at refinement"
  },
  ...
}