Download and Search for Files

Learn how to download and search for files using the endpoints for the files namespace.

We'll cover the following

In this lesson, we’ll see two important endpoints that’ll help us download and search files from Dropbox. These endpoint operations are the following:

  • download
  • search_v2

Download a file

In this section, we’ll see how to download a file using the /files/download endpoint for the files namespace. We need to enable the files.content.read permission to make a call to this endpoint.

Request parameters

This endpoint takes only one required parameter, the path of the file we want to download. We can specify a path in multiple ways: with a descriptive name of the folder or file, using the id of the file as the path, or using the latest rev of the file. Any of these methods can work.

Press + to interact
import requests
import json
url = "https://content.dropboxapi.com/2/files/download"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Dropbox-API-Arg": "{\"path\":\"/home/TestFolder/demo.png\"}"
}
r = requests.post(url, headers=headers)
print(r)

In the code above, we see the following:

  • Line 4: This shows the URL for this endpoint. The base URL for this call is also different from the previous ones we’ve used. It has the base URL content.dropboxapi.com.
  • Line 8: We use Dropbox-API-Arg to specify the path of the file we want to download. We’ll download demo.png, which is a file that we’ve uploaded previously using the upload endpoint.
  • Line 11: This is the POST request.
  • Line 12: We print the status of our HTTP request.

Response

We won’t be able to download the file when we click the “Run” button because of Educative’s platform restrictions. But don’t worry! The returned status code of 200 shows that our request was successful.

Search for files and folders

The /files/search_v2 endpoint is used to make search queries for files and folders in the user’s Dropbox. It requires us to enable the files.metadata.read permission so that we can perform this operation.

Request parameters

Let’s see what parameters we can pass to this endpoint.

  • A query is a required parameter that takes what we want to search for as a string.
  • The options parameter is an optional parameter that’s used to be more targeted in search operations. It consists of the following parameters:
    • The path parameter is an optional parameter that is used to provide a specific location to search for our query. If the path isn’t defined, then a search operation will be performed throughout Dropbox.
    • The max_results parameter is an optional parameter that is used to limit our search results. By default, its value is 100. It takes the UInt64 value that ranges from 1 to 1000.
    • The order_by parameter is an optional parameter used to order our search results. We can use either relevance or last_modified_time as a value for this field. By default, results are sorted with respect to relevance.
    • The file_status parameter is an optional parameter that can also restrict our search to files of a specific status. By default, its value is active, but it can also be set to deleted.
    • The filename_only parameter is a boolean type optional parameter that restricts our search to file names only. Its default value is False.
    • The file_extensions parameter is an optional parameter that can restrict our search to file extensions if we want to search through specific extensions only. This only works for files with an active status.
    • The file_categories parameter is an optional parameter that works for active files only. We can restrict our search if we specify any of the given categories: image, document, pdf, spreadsheet, presentation, audio, video, folder, paper, and other.

Let’s search for a file using the search_v2 endpoint.

Press + to interact
import requests
import json
url = "https://api.dropboxapi.com/2/files/search_v2"
headers = {
    "Authorization": "Bearer {{TOKEN}}",
    "Content-Type": "application/json"
}
data = {
    "query": "demo",
    "options": {
        "path":"/home/TestFolder",
        # "max_results": 1,
        # "file_status": "active",
        # "file_categories":[{".tag":"image"}]
        }
}
r = requests.request("POST",url, headers=headers, data=json.dumps(data))
print(json.dumps(r.json(), indent=4))

In the code above, we see the following:

  • Lines 11–19: We define the data to be passed to the endpoint.
  • Line 12: This shows the term demo that we’ll use for our search query. We have a demo.png file in our TestFolder.
  • Lines 15–17: We add some more parameters to filter out the results. If you’d like, you can uncomment them and try them yourself!
  • Line 21: This is the HTTP request.
  • Line 22: This is the print statement.

Note: In order to experience the behavior of this endpoint more clearly, try to add more files that have the same name but different extensions. We’ve added another file, demo.docx, and created a new folder named Demo in our home/TestFolder directory.

Response

In response to the code above, we’ll get all the instances for our query. We’ll get all the metadata of the files and folders found in the specified location. In our case, they’re the demo.png file, the Demo folder, and the demo.docx file.