Manage file metadata

Stay organized with collections Save and categorize content based on your preferences.

Much of the information you'll need to get started inserting and retrieving files is detailed in the Files reference. Here are a few more important considerations for naming files and working with metadata like thumbnails and indexable text.

Specify file names and 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 requests 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, Google Drive attempts to determine the extension based on the file's MIME type.

Save indexable text

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

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. Also keep in mind:

  • The size limit for contentHints.indexableText is 128K.
  • Don't try to sort text in order of importance; the indexer does that very efficiently for you.
  • Indexable text should be updated by your application with each save.
  • Make sure the text is related to the content of the file.

This last point may seem obvious, but it is quite important. It's not a good idea to add commonly searched terms to try and force a file to show up 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 File resource during an insert 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 will use the generated one and ignore any you may have uploaded. If it can't generate a thumbnail, it will always use yours if you provided one. Things to keep in mind:

  • Thumbnails may be uploaded in PNG, GIF, or JPG formats.
  • The recommended width is 1600px.
  • The maximum file size for a thumbnail is 2mb.
  • The minimum width for thumbnails is 220px.
  • Thumbnails should be updated by your application with each save.

For more information, see the Files reference.