Search for files and folders

    This guide explains how the Google Drive API supports several ways to search files and folders.

    You can use the list method on the files resource to return all or some of a Drive user's files and folders. The list method can also be used to retrieve the fileId required for some resource methods (such as the get method and the update ) method.

    Use the fields parameter

    If you want to specify the fields to return in the response, you can set the fields system parameter with any method of the files resource. If you omit the fields parameter, the server returns a default set of fields specific to the method. For example, the list method returns only the kind , id , name , mimeType , and resourceKey fields for each file. To return different fields, see Return specific fields .

    Get a file

    To get a file, use the get method on the files resource with the fileId path parameter. If you don't know the file ID, you can list all files using the list method.

    The method returns the file as an instance of a files resource. If you provide the alt=media query parameter, then the response includes the file contents in the response body. To download or export the file, see Download and export files .

    To acknowledge the risk of downloading known malware or other abusive files, set the acknowledgeAbuse query parameter to true . This field is only applicable when the alt=media parameter is set and the user is either the file owner or an organizer of the shared drive in which the file resides.

    Search for all files and folders on the current user's My Drive

    Use the list method without any parameters to return all files and folders.

     GET https://www.googleapis.com/drive/v3/files

    Search for specific files or folders on the current user's My Drive

    To search for a specific set of files or folders, use the query string q field with the list method to filter the files to return by combining one or more search terms.

    The query string syntax contains the following three parts:

    query_term operator values

    Where:

    • query_term is the query term or field to search upon.

    • operator specifies the condition for the query term.

    • values are the specific values you want to use to filter your search results.

    For example, the following query string filters the search to only return folders by setting the MIME type :

     q: mimeType = 'application/vnd.google-apps.folder'

    To view all file query terms, see File-specific query terms .

    To view all query operators that you can use to construct a query, see Query operators .

    Query string examples

    The following table lists examples of some basic query strings. The actual code differs depending on the client library you use for your search.

    You must also escape special characters in your file names to make sure the query works correctly. For example, if a filename contains both an apostrophe ( ' ) and a backslash ( "\" ) character, use a backslash to escape them: name contains 'quinn\'s paper\\essay' .

    What you want to query Example
    Files with the name "hello" name = 'hello'
    Files with a name containing the words "hello" and "goodbye" name contains 'hello' and name contains 'goodbye'
    Files with a name that does not contain the word "hello" not name contains 'hello'
    Files that contain the text "important" and in the trash fullText contains 'important' and trashed = true
    Files that contain the word "hello" fullText contains 'hello'
    Files that don't have the word "hello" not fullText contains 'hello'
    Files that contain the exact phrase "hello world" fullText contains '"hello world"'
    Files with a query that contains the "\" character (for example, "\authors") fullText contains '\\authors'
    Files that are folders mimeType = 'application/vnd.google-apps.folder'
    Files that are not folders mimeType != 'application/vnd.google-apps.folder'
    Files modified after a given date (default time zone is UTC) modifiedTime > '2012-06-04T12:00:00'
    Image or video files modified after a specific date modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
    Files that are starred starred = true
    Files within a collection (for example, the folder ID in the parents collection) '1234567' in parents
    Files in an application data folder in a collection 'appDataFolder' in parents
    Files for which user "test@example.org" is the owner 'test@example.org' in owners
    Files for which user "test@example.org" has write permission 'test@example.org' in writers
    Files for which members of the group "group@example.org" have write permission 'group@example.org' in writers
    Files shared with the authorized user with "hello" in the name sharedWithMe and name contains 'hello'
    Files with a custom file property visible to all apps properties has { key='mass' and value='1.3kg' }
    Files with a custom file property private to the requesting app appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
    Files that have not been shared with anyone or domains (only private, or shared with specific users or groups) visibility = 'limited'

    Filter search results with a client library

    The following code sample shows how to use a client library to filter search results to file names and IDs of JPEG files. This sample uses the mimeType query term to narrow results to files of type image/jpeg . It also sets spaces to drive to further narrow the search to the Drive space . When nextPageToken returns null , there are no more results.

    Java

    drive/snippets/drive_v3/src/main/java/SearchFile.java
     import 
  
 com.google.api.client.http.HttpRequestInitializer 
 ; 
 import 
  
 com.google.api.client.http.javanet.NetHttpTransport 
 ; 
 import 
  
 com.google.api.client.json.gson.GsonFactory 
 ; 
 import 
  
 com.google.api.services.drive.Drive 
 ; 
 import 
  
 com.google.api.services.drive.DriveScopes 
 ; 
 import 
  
 com.google.api.services.drive.model.File 
 ; 
 import 
  
 com.google.api.services.drive.model.FileList 
 ; 
 import 
  
 com.google.auth.http.HttpCredentialsAdapter 
 ; 
 import 
  
 com.google.auth.oauth2.GoogleCredentials 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.util.ArrayList 
 ; 
 import 
  
 java.util.Arrays 
 ; 
 import 
  
 java.util.List 
 ; 
 /* Class to demonstrate use-case of search files. */ 
 public 
  
 class 
 SearchFile 
  
 { 
  
 /** 
 * Search for specific set of files. 
 * 
 * @return search result list. 
 * @throws IOException if service account credentials file not found. 
 */ 
  
 public 
  
 static 
  
 List<File> 
  
 searchFile 
 () 
  
 throws 
  
 IOException 
  
 { 
  
 /*Load pre-authorized user credentials from the environment. 
 TODO(developer) - See https://developers.google.com/identity for 
 guides on implementing OAuth2 for your application.*/ 
  
 GoogleCredentials 
  
 credentials 
  
 = 
  
 GoogleCredentials 
 . 
 getApplicationDefault 
 () 
  
 . 
 createScoped 
 ( 
 Arrays 
 . 
 asList 
 ( 
 DriveScopes 
 . 
 DRIVE_FILE 
 )); 
  
 HttpRequestInitializer 
  
 requestInitializer 
  
 = 
  
 new 
  
 HttpCredentialsAdapter 
 ( 
  
 credentials 
 ); 
  
 // Build a new authorized API client service. 
  
 Drive 
  
 service 
  
 = 
  
 new 
  
 Drive 
 . 
 Builder 
 ( 
 new 
  
 NetHttpTransport 
 (), 
  
 GsonFactory 
 . 
 getDefaultInstance 
 (), 
  
 requestInitializer 
 ) 
  
 . 
 setApplicationName 
 ( 
 "Drive samples" 
 ) 
  
 . 
 build 
 (); 
  
 List<File> 
  
 files 
  
 = 
  
 new 
  
 ArrayList<File> 
 (); 
  
 String 
  
 pageToken 
  
 = 
  
 null 
 ; 
  
 do 
  
 { 
  
 FileList 
  
 result 
  
 = 
  
 service 
 . 
 files 
 (). 
 list 
 () 
  
 . 
 setQ 
 ( 
 "mimeType='image/jpeg'" 
 ) 
  
 . 
 setSpaces 
 ( 
 "drive" 
 ) 
  
 . 
 setFields 
 ( 
 "nextPageToken, files(id, title)" 
 ) 
  
 . 
 setPageToken 
 ( 
 pageToken 
 ) 
  
 . 
 execute 
 (); 
  
 for 
  
 ( 
 File 
  
 file 
  
 : 
  
 result 
 . 
 getFiles 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Found file: %s (%s)\n" 
 , 
  
 file 
 . 
 getName 
 (), 
  
 file 
 . 
 getId 
 ()); 
  
 } 
  
 files 
 . 
 addAll 
 ( 
 result 
 . 
 getFiles 
 ()); 
  
 pageToken 
  
 = 
  
 result 
 . 
 getNextPageToken 
 (); 
  
 } 
  
 while 
  
 ( 
 pageToken 
  
 != 
  
 null 
 ); 
  
 return 
  
 files 
 ; 
  
 } 
 }

    Python

    drive/snippets/drive-v3/file_snippet/search_file.py
     import 
  
 google.auth 
 from 
  
 googleapiclient.discovery 
  
 import 
 build 
 from 
  
 googleapiclient.errors 
  
 import 
 HttpError 
 def 
  
 search_file 
 (): 
  
 """Search file in drive location 
 Load pre-authorized user credentials from the environment. 
 TODO(developer) - See https://developers.google.com/identity 
 for guides on implementing OAuth2 for the application. 
 """ 
 creds 
 , 
 _ 
 = 
 google 
 . 
 auth 
 . 
 default 
 () 
 try 
 : 
 # create drive api client 
 service 
 = 
 build 
 ( 
 "drive" 
 , 
 "v3" 
 , 
 credentials 
 = 
 creds 
 ) 
 files 
 = 
 [] 
 page_token 
 = 
 None 
 while 
 True 
 : 
 # pylint: disable=maybe-no-member 
 response 
 = 
 ( 
 service 
 . 
 files 
 () 
 . 
 list 
 ( 
 q 
 = 
 "mimeType='image/jpeg'" 
 , 
 spaces 
 = 
 "drive" 
 , 
 fields 
 = 
 "nextPageToken, files(id, name)" 
 , 
 pageToken 
 = 
 page_token 
 , 
 ) 
 . 
 execute 
 () 
 ) 
 for 
 file 
 in 
 response 
 . 
 get 
 ( 
 "files" 
 , 
 []): 
 # Process change 
 print 
 ( 
 f 
 'Found file: 
 { 
 file 
 . 
 get 
 ( 
 "name" 
 ) 
 } 
 , 
 { 
 file 
 . 
 get 
 ( 
 "id" 
 ) 
 } 
 ' 
 ) 
 files 
 . 
 extend 
 ( 
 response 
 . 
 get 
 ( 
 "files" 
 , 
 [])) 
 page_token 
 = 
 response 
 . 
 get 
 ( 
 "nextPageToken" 
 , 
 None 
 ) 
 if 
 page_token 
 is 
 None 
 : 
 break 
 except 
 HttpError 
 as 
 error 
 : 
 print 
 ( 
 f 
 "An error occurred: 
 { 
 error 
 } 
 " 
 ) 
 files 
 = 
 None 
 return 
 files 
 if 
 __name__ 
 == 
 "__main__" 
 : 
 search_file 
 ()

    Node.js

    drive/snippets/drive_v3/file_snippets/search_file.js
     import 
  
 { 
 GoogleAuth 
 } 
  
 from 
  
 'google-auth-library' 
 ; 
 import 
  
 { 
 google 
 } 
  
 from 
  
 'googleapis' 
 ; 
 /** 
 * Searches for files in Google Drive. 
 * @return {Promise<object[]>} A list of files. 
 */ 
 async 
  
 function 
  
 searchFile 
 () 
  
 { 
  
 // Authenticate with Google and get an authorized client. 
  
 // TODO (developer): Use an appropriate auth mechanism for your app. 
  
 const 
  
 auth 
  
 = 
  
 new 
  
 GoogleAuth 
 ({ 
  
 scopes 
 : 
  
 'https://www.googleapis.com/auth/drive' 
 , 
  
 }); 
  
 // Create a new Drive API client (v3). 
  
 const 
  
 service 
  
 = 
  
 google 
 . 
 drive 
 ({ 
 version 
 : 
  
 'v3' 
 , 
  
 auth 
 }); 
  
 // Search for files with the specified query. 
  
 const 
  
 result 
  
 = 
  
 await 
  
 service 
 . 
 files 
 . 
 list 
 ({ 
  
 q 
 : 
  
 "mimeType='image/jpeg'" 
 , 
  
 fields 
 : 
  
 'nextPageToken, files(id, name)' 
 , 
  
 spaces 
 : 
  
 'drive' 
 , 
  
 }); 
  
 // Print the name and ID of each found file. 
  
 ( 
 result 
 . 
 data 
 . 
 files 
  
 ?? 
  
 []). 
 forEach 
 (( 
 file 
 ) 
  
 = 
>  
 { 
  
 console 
 . 
 log 
 ( 
 'Found file:' 
 , 
  
 file 
 . 
 name 
 , 
  
 file 
 . 
 id 
 ); 
  
 }); 
  
 return 
  
 result 
 . 
 data 
 . 
 files 
  
 ?? 
  
 []; 
 }

    PHP

    drive/snippets/drive_v3/src/DriveSearchFiles.php
    < ?php 
 use Google\Client; 
 use Google\Service\Drive; 
 function searchFiles() 
 { 
 try { 
 $client = new Client(); 
 $client->useApplicationDefaultCredentials(); 
 $client->addScope(Drive::DRIVE); 
 $driveService = new Drive($client); 
 $files = array(); 
 $pageToken = null; 
 do { 
 $response = $driveService->files->listFiles(array( 
 'q' => "mimeType='image/jpeg'", 
 'spaces' => 'drive', 
 'pageToken' => $pageToken, 
 'fields' => 'nextPageToken, files(id, name)', 
 )); 
 foreach ($response->files as $file) { 
 printf("Found file: %s (%s)\n", $file->name, $file->id); 
 } 
 array_push($files, $response->files); 
 $pageToken = $response->pageToken; 
 } while ($pageToken != null); 
 return $files; 
 } catch(Exception $e) { 
 echo "Error Message: ".$e; 
 } 
 }

    Search for files with a custom file property

    To search for files with a custom file property, use either the properties or the appProperties search query term with a key and value. For example, to search for a custom file property that's private to the requesting app called additionalID with a value of 8e8aceg2af2ge72e78 :

     appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }

    For more information, see Add custom file properties .

    Search for files with a specific label or field value

    To search for files with specific labels, use the labels search query term with a specific label ID. For example: 'labels/ LABEL_ID ' in labels . If successful, the response body contains all file instances where the label's applied.

    To search for files without a specific label ID: Not 'labels/ LABEL_ID ' in labels .

    You can also search for files based on specific field values. For example, to search for files with a text value: labels/ LABEL_ID .text_field_id =' TEXT ' .

    For more information, see Search for files with a specific label or field value .

    Search the corpora

    Searches that call the list method use the corpora of user by default. To search other corpora, such as files shared with a domain , set the corpora parameter.

    Multiple corpora may be searched in a single query, though incomplete results might be returned if the combined corpora is too large. If incompleteSearch is true in the response body, then all documents weren't returned. If this occurs, you should narrow your query by choosing a different corpora such as user or drive .
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: