Documentation Archive


App Search Programming Guide

On This Page

Help Users Find Your Images

The #images app in Messages shows people popular images from public websites. Your publicly accessible images may be included in #images search results after Apple's web crawler, known as Applebot, has scanned your website.

To make your publicly accessible images available for #images search results, follow these steps:

To be considered for inclusion in #images search results, your publicly accessible images must meet the following specifications:

  • No smaller than 180 x 180 pixels

  • GIF format (preferred) or static image

  • No larger than 2 MB per image file

Update Your Association File

Add a dictionary for the spotlight-image-search service to your apple-app-site-association file (if you need to create this file, see Creating and Uploading the Association File to learn how). The spotlight-image-search dictionary should include your app ID (which is the team ID or app ID prefix, followed by the bundle ID) and a search key that contains the root path for your images. You can specify up to 500 paths and patterns that can be included for indexing by #images.

The spotlight-image-search dictionary can also include the trending and keywords keys, each of which points to an area of your server that contains resources that Applebot can fetch. Listing 7-1 shows part of an apple-app-site-association file that includes a dictionary for the spotlight-image-search service.

Listing 7-1Adding a spotlight-image-search service to an apple-app-site-association file
  1. {
  2. "spotlight-image-search": {
  3. "details": [{
  4. "appId": "....",
  5. "trending": [ { "url": "/trending?secret=abcdefgh&lc=en_US",
  6. "locale": "en_US" },... ],
  7. "keywords": [ "/keywords?secret=abcdefgh&page=1",
  8. "/keywords?secret=abcdefgh&page=2" ... ]
  9. }
  10. ]}
  11. }

One URL on your server can contain multiple keywords, but you should return no more than 20 MB of keywords per fetch. If you want to return keywords in excess of 20 MB, split the resources into multiple server pages and list the pages separately, as shown in Listing 7-1.

Each /keywords item should map a keyword to a URL that contains no more than 1000 associated images. List the most important keywords first. Each trending URL should point to a server resource that returns a list of ImageObject types.

As shown in Listing 7-2, you can mix different locales in the same list. You can also map a keyword in one locale to relevant results associated with a different locale, if the results related to the first locale are sparse.

Listing 7-2Associating keywords with relevant images
  1. [
  2. {
  3. "keyword": "facepalm",
  4. "locale": "en_US",
  5. "url": "/search?q=facepalm&format=jsonld"
  6. },
  7. {
  8. "keyword": "télévision drôle",
  9. "locale": "fr_FR",
  10. "url": "/search?q=television+funny&format=jsonld"
  11. },
  12. ...
  13. ]

To specify images that are trending or associated with keywords, you use the JSON-LD format for the ImageObject type to describe each image (for a full list of properties, see ImageObject). The format includes the following keys and values:


The URL of the image in the best possible resolution


The URL of the webpage that is hosting the content given by contentUrl


The original source of the asset (raw content bytes)


A general description of the image (optional)


A user interaction statistic on a per query level, used for ranking


Overall rating based on reviews


A list of keywords, each of which is combined with the rating of the keyword with regard to the corresponding image (the rating is required only when /trending is used)


MPAA US rating (that is, G, PG, PG-13, R, or NC-17)


The date on which the image was published

Listing 7-3 shows an example of an image specified in the JSON-LD format for image objects.

Listing 7-3Specifying an image using the JSON-LD format
  1. [{
  2. "@context": "",
  3. "@type": "ImageObject",
  4. "contentUrl": "",
  5. "mainEntityOfPage": "",
  6. "sameAs": "",
  7. "description": "rock-n-roll",
  8. "encodingFormat": "gif",
  9. "interactionStatistic": {
  10. "@type": "InteractionCounter",
  11. "interactionType": "",
  12. "userInteractionCount": 14300
  13. },
  14. "aggregateRating": {
  15. "@type": "AggregateRating",
  16. "bestRating": 100,
  17. "ratingCount": 24,
  18. "ratingValue": 87
  19. },
  20. "contentRating": "PG-13",
  21. "datePublished": "2016-09-16",
  22. "keywords": "no, facepalm, smh, smdh, shaking head"
  23. },
  24. ...
  25. ]

Update Your Associated Domains Entitlement

Add to your entitlement a list of the web domains that host the images you want to make searchable. For each domain, specify the spotlight-image-search service in an entry such as To learn more about the associated domains entitlement, see Preparing Your App to Handle Universal Links.

Specifying a Frequency for Pulling Images

The #images app periodically pulls content from the resources you specify in your apple-app-site-association file. You can use HTTP headers to specify frequencies that are appropriate for your content, such as:

  • Expiration

  • Last modified

  • ETag