Manage file metadata

This document covers important considerations for naming files and working with metadata like thumbnails and indexable text. To get started inserting and retrieving files, see Files reference.

Specify file names & extensions

Apps should specify a file extension in the title property when inserting files with the API. For example, an operation to insert a JPEG file should specify something like "name": "cat.jpg" in the metadata.

Subsequent GET responses can include the read-only fileExtension property populated with the extension originally specified in the name property. When a Google Drive user requests to download a file, or when the file is downloaded through the sync client, Drive builds a full filename (with extension) based on the title. In cases where the extension is missing, Drive attempts to determine the extension based on the file's MIME type.

Save indexable text

Note: Beginning October 31, 2022, indexable text can be shown in result snippets and will affect search results in more places, including Cloud Search and the search overlay in Drive and Gmail.

Drive automatically indexes documents for search when it recognizes the file type, including text documents, PDFs, images with text, and other common types. If your app saves other types of files (such as drawings, video, and shortcuts), you can improve the discoverability by supplying indexable text in the contentHints.indexableText field of the file.

Indexable text is indexed as HTML. If you save the indexable text string <section attribute="value1">Here's some text</section>, then "Here's some text" is indexed, but "value1" is not. Because of this, saving XML as indexable text isn't as useful as saving HTML.

When specifying indexableText, also keep in mind:

• The size limit for contentHints.indexableText is 128 KB.
• Capture the key terms and concepts that you expect a user to search for.
• Don't try to sort text in order of importance because the indexer does that efficiently for you.
• Your application should update the indexable text with each save.
• Make sure the text is related to the content or metadata of the file.

This last point might seem obvious, but it's important. It's not a good idea to add commonly searched terms to force a file to appear in search results. This can frustrate users, and might even motivate them to delete the file.

Upload thumbnails

Drive automatically generates thumbnails for many common file types. For shortcuts and other file types that Drive can't render, you can provide a thumbnail image generated by your application. Upload a thumbnail by setting the contentHints.thumbnail property on the Files resource during an create or update call as follows:

• Set contentHints.thumbnail.image to the URL-safe Base64-encoded image (see RFC 4648 section 5).
• Set contentHints.thumbnail.mimeType to the appropriate type for the image format.

If Drive can generate a thumbnail from the file, then it uses the generated one and ignores any you have uploaded. If it can't generate a thumbnail, it always uses yours if you provided one. Items to keep in mind:

• Thumbnails can be uploaded in PNG, GIF, or JPG formats.
• The recommended width is 1600 pixels.
• The maximum file size for a thumbnail is 2 MB.
• The minimum width for thumbnails is 220 pixels.
• Your application should update the thumbnails with each save.

Important: Thumbnails are invalidated each time the content of the file changes. When supplying thumbnails, it's important to upload new thumbnails each time the content is modified. Metadata changes don't invalidate thumbnails.

For more information, see the Files reference.