Add custom file properties

Custom file properties are key-value pairs used to store custom metadata for a Google Drive file (such as tags), IDs from other data stores, information shared between workflow applications, and so on. For example, you can add file properties to all documents generated by the sales department in Q1.

To add properties visible to all applications, use the properties field of the files resource. To add properties restricted to your app, use the appProperties field of the files resource.

Note: If you're using the older version of Google Drive API (v2), utilize the properties resource to add properties to your app using properties.insert. For a complete list of differences between versions, see the Drive API v2 & v3 comparison reference.

Properties can also be used in search expressions.

This is the structure of a typical property that might be used to store a Drive file's database ID on the file.

Drive API v3

"appProperties": {
  "additionalID": "ID",
}

Drive API v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

Working with custom file properties

The section explains how to perform some custom file property-related tasks that affect all applications.

Note: The Google Drive UI doesn't include a built-in way for you to edit custom properties.

Add or update custom file properties

To add or update properties visible to all applications, use the files.update method to set the properties field of the files resource.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

You can also add a custom property to a file using the advanced Drive service in Google Apps Script. For more information, see Adding custom properties.

Get or list custom file properties

To view properties visible to all applications, use the files.get method to retrieve the custom file properties for the file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

The response consists of a properties object that contains a collection of key-value pairs.

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Delete custom file properties

To delete property values visible to all applications, use the files.update method to set the properties field of the files resource to null.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "name": null
}

To view the change, call the files.get method to retrieve the properties object for the file.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

Limits of custom file properties

Custom properties have the following limits:

• Maximum of 100 custom properties per file, totaled from all sources.
• Maximum of 30 public properties per file, totaled from all sources.
• Maximum of 30 private properties per file from any one application.
• Maximum of 124 bytes per property string (including both key and value) in UTF-8 encoding. For example, a property with a key that's 10 characters long can only have 114 characters in the value. Similarly, a property that requires 100 characters for the value can use up to 24 characters for the key.

For more information, see the files resource. For Drive API v2, see the properties resource.

Access private custom file properties

You can only retrieve private properties using the appProperties field through an authenticated request that uses an access token obtained with an OAuth 2.0 client ID. You cannot use an API key to retrieve private properties.