In Using Drive SDK I described why you might want to use the SDK JSON API rather than the built in Apps Script Drive Class. Before you can start with this you need to authorize your access with OAUTH2, as all API requests need an access token. This one off exercise is straightforward and described here.

This page describes how to use the API from apps script in some detail. Nowadays there is built in access to Advanced Drive Service (this is not the same as the regular DriveApp service). All you have to is enable it in Advanced Services and the cloud console and authorize it, but this library uses the JSON API directly. 

The API can be a little intimidating and complicated, so I’ve created a library with most of the functions you’ll need to do basic operations directly with the API. A couple of concepts to start.

Results Object

This is a standard format I return from most operations. It looks like this


Left to its own devices the API returns an awful lot of stuff, most of which you don’t need. It provides a method of asking for partial responses. The methods I have implemented that return data from the API all accept an options parameter that can be used to limit the returned data to only what’s needed. I recommend you use it.


Drive seems to be organized around a flat system of linked IDS rather than the hierarchical structure we are used to with most file systems. Folder structures are emulated through linking to parents and children. You’ll see that this library provides methods for working with folder paths, which get translated into drive structures behind the scenes.

Metadata versus data

Most of the documentation here refers to the meta data associated with a file rather than the data itself. Strangely I took a while to actually find out how to do this. I’ve implemented simple uploading and getting, which you’ll find documented close to the end of this page.

Getting started

Once you have set up your oAuth2 environment, you are ready to go.  In the documentation below, I’ll show examples of how to use, and also sometimes show the code in the library for information. The full code of the latest library will be shown at the end, so there may have been some changes since I initially wrote this.

Getting a handle

It’s just as well to set up the accessToken right from the start when you take out the handle

Get a file’s metadata by ID

Each file has a unique ID. It’s the same as the one in the Drive UI.

However, this will return a huge amount of stuff, so if you know which fields you want, its better to say. This applies to all methods in this documentation that take an optFields argument. I wont repeat this for each one.

Library Code

Get the root folder’s metadata

Folders in Drive are not really different than files, except for MimeType.

library code


I provide various useful ENUMS that can be access via

Library Code

Get a collection of items that match a query

The API provides a comprehensive searching mechanism as described here. This query returns just the ids of all scripts in my drive that are owned by me

Library Code

Get a collection of child folders

Getting a collection of child folders is just a specialized form of query which includes the parentId in its url.

Library Code

Get a collection of folders by name

Getting a folder by name is just an additional query filter on getting a list of child folders.

Library code

Getting or creating a folder id by path 

If you are planning to organize by folders, which most of us still do, this is probably the most useful method, since it takes a path like /abc/def/ghi and retrieves the id of ‘ghi’. Optionally it will also take care of creating ‘abc’ and ‘def’ and ‘ghi’ if they don’t already exist.
get folder id or null

get folder id, and create folders if needed

Library Code

Creating a folder

Creating a folder needs the parentId of the folder that will hold it.

Creating a item

This is a more generalized form of creating an Item. createAFolder uses it

Library Code

Get files by name or create one if it doesn’t exist

This will find a file of the given name, or create it if it doesn’t exist.

Library Code

Recursively get all files in a folder and its sub folders that match a particular query

This will return the data of all script files owned by me under a particular folder and its sub folders

Library Code

Get the data in a file

Up till now we’ve been getting metadata from files. Eventually you’ll want to actually get (and write) some data. Here’s how.

Library Code

Update the data in a file

You should first create or find the file using one of the methods above, then update it using its id.

Library Code

You’ll find the other ‘behind the scenes code’ in the full source below

For more on drive SDK see Using Drive SDK

For help and more information join our community, follow the blog or follow me on Twitter