A Guide to Apple Search APIs

The Search APIs

There are three ways you can index your content on Spotlight or Safari

  • CoreSpotlight
  • NSUserActivity
  • Web Markup
  • Private index which is the on device index, never shared with anyone or any device, even if you have multiple devices.
  • Public index which is shared across devices


CoreSpotlight is the way you manage the private on device index for your user.

Apple tells us that you use CoreSpotlight to index content that is specific to the user, for example, the documentation suggests that for an e-commerce app you could index wish-listed items, current orders of a user etc.


NSUserActivity helps you manage both the private and public index

Now the above statement might make you question that if you can manage the both the indexes using NSUserActivity why would you ever use CoreSpotlight. There are a few trade-offs involved which I’ll speak about later but first let’s see what NSUserActivity can provide us with.

Adding supported domains to Info.plist


The variable isEligibleForPublicIndexing deserves a special mention here because this is the switch that makes your item publicly searchable to your iOS user-base.

  • The content associated with it. For example the title, description, ratings, reviews, content-type (remember the kUTTypeText keyword while initializing a CSSearchableItemAttributeSet) etc. Provide thumbnail images if possible too, make your item more engaging.
  • The more engagement the users show with that particular item. If lots of your users are indexing a particular item and/or interacting with that item in spotlight, it’s ranking will go up.
  • The ranking of your webPageURL (if any) that is associated with this particular activity.

Handling Spotlight Items

When a user taps on any of your indexed items in Spotlight you will receive the callback in your AppDelegate in the following function

Using CoreSpotlight and NSUserActivity together

In this section I’m going to talk about two things

  • The trade-offs with using NSUserActivity and CoreSpotlight for indexing items in the on-device index.
  • The things you need to do to make sure that you can use both for their specific use-cases in tandem with each other.

The Trade-offs

In the last section I mentioned that there were certain trade-offs involved with using both these means to manage your on-device index(Not going to mention differences related to the public index).

  • In order to index items using NSUserActivity, you need a strong reference, because of which you usually do it when the user has actually visited that page whereas this limitation does not exist with CoreSpotlight.
  • Apple suggests that you do not create multiple NSUserActivity objects at one time, since if you need them indexed you will need a strong reference to each of them, whereas in CoreSpotlight you could index an array of items.
  • CoreSpotlight does not provide you with the ability to make your indexed item available for Hand-Off or Siri Smart Reminders.

Using them together

In case you’re using both CoreSpotlight and NSUserActivity to index the same item (maybe in different scenarios), you need to make sure that you set the userActivity.uniqueIdentifier is the same as the searchableItem.relatedUniqueIdentifier


The reason for this article was that when I was implementing Spotlight Indexing for my app, I had lots of questions which were all answered from different sources. I had to scrape through the Apple Documentation, some things were hidden in plain sight, and some were difficult to figure out while for some questions I just had to implement the code and figure them out. I’ve tried to answer all these questions while framing this article.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Neel Bakshi

Neel Bakshi

Guy who handles everything mobile @headout among other things! Ex @practo