diff --git a/api/sheets/index.md b/api/sheets/index.md index 420e7e69f..d101a8dfb 100644 --- a/api/sheets/index.md +++ b/api/sheets/index.md @@ -8,38 +8,54 @@ has_children: true # Data Commons Sheets API -The **Data Commons Sheets API** is a Google Sheets add-on that enables Google Sheets -users to import data from the Data Commons knowledge graph. The add-on provides an -interface for finding a location's [DCID](/glossary.html), as well as some custom functions for -importing data to a spreadsheet. +The **Data Commons Sheets API** is a Google Sheets add-on that enables Google Sheets users to import data from the Data Commons knowledge graph. The add-on provides an interface for finding a location’s unique Data Commons identifier ([DCID](glossary.html#dcid)), and some custom functions for importing data into a spreadsheet. + +> **Note:** For more information on DCIDs, refer to [Unique Identifiers (dcid)](/bigquery/unique_identifiers.html). Also read our [step-by-step guides](tutorials/) for more examples. -## Getting started +## Installing and Enabling the Sheets Add-On + +Install and enable the Sheets add-on from Google Workspace Marketplace, as follows: + +1. Install the Sheets add-on from the **[Google Workspace Marketplace](https://gsuite.google.com/marketplace/app/data_commons/454343067575)** . +2. Enable the Sheets add-on by clicking the Google Sheets **Extensions** menu, pointing to **Data Commons**, and then by clicking **Fill place dcids**. +3. Use the resulting sidebar that appears on the right side of the page to start finding DCIDs in the United States. You can close and reopen the sidebar at any time. + +![Google Sheets menu bar](/assets/images/sheets/sheets_menu_bar.png) -Install the add-on from [G Suite Marketplace](https://gsuite.google.com/marketplace/app/data_commons/454343067575). To enable the add-on in a document, click "Add-ons > Data Commons > Fill place dcids". You may use the resulting sidebar to start [finding dcids](/api/sheets/get_dcid.html) in the United States, or close it and reopen it at any time. Note that none of the custom functions will work in a given document until you have enabled the add-on by choosing "Fill place dcids". +> **Note:** None of the custom Data Commons Sheets functions (described below) will work in a given document until you have enabled the add-on by opening the **Fill place dcids** sidebar. -![](/assets/images/sheets/sheets_menu_bar.png) +## Finding a Place’s DCID -## Finding a place's DCID +Data Commons’ Sheets add-on provides the ability to look up a place’s [DCID](/glossary.html#dcid), within the application by using the **Fill place dcids** feature. To use this feature to find a place’s DCID: -Data Commons' Sheets add-on ships with the ability to look up a location's [DCID](/glossary.html), or unique Data Commons identifier, within the application. To use this feature, select the final destination cell of the place [DCID](/glossary.html). Go to the Sheets menu bar, and click: +1. Select the destination cell where you want to add a place’s DCID. +2. Click in the search box for the **Fill place dcids for selected cells** section on the right side of the page to start finding DCIDs in the United States. +3. Start typing the name of the place you are searching for. From the drop-down menu, select the place you want, and its DCID appears in the cell that you selected. For example, the following image shows the place names that match “Hawaii”. + ![Google Sheets search box](/assets/images/sheets/sheets_search_box.png) -**"Add-ons > Data Commons > Fill place dcids"** +Note that this feature currently only supports places in the United States. -![](/assets/images/sheets/sheets_menu_bar.png) +## Introduction to the Sheets API Custom Functions -A sidebar will appear on the right of the sheet, with a search bar where you can start typing the name of the place you want. From the drop down menu, select the place you want, and its [DCID](/glossary.html) will appear in the cell that you selected. +The Data Commons Sheets API includes the five formulas listed in the following table. Click the links in the table for detailed information on each formula. -![](/assets/images/sheets/sheets_search_box.png) +| **Formula** | **Description** | +|----------------------------------------------------------------------------------------------|-------------------------------------------| +| [=DCGETNAME(dcids)](/api/sheets/get_name.html) | Returns the names associated with a DCID. | +| [=DCPLACESIN(dcids)](/api/sheets/places_in.html) | Returns child nodes | +| [=DCGET(dcids)](/api/sheets/get_variable.html) | Returns statistical variables. | +| [=DCPROPERTY(dcids)](/api/sheets/get_property.html) | Returns node property values. | +| [=DCCOHORTMEMBERS(dcids)](/api/sheets/get_cohort_members.html) | Gets the cohort members of a node. | -Note that this feature only supports places in the United States. +See the links in the preceding table to subsequent pages in this section for detailed descriptions of each API. -## Sorting your results +## Sorting your Results -

To sort columns of data from the API, we suggest using the "filter views" Google Sheet feature. +To sort columns of data from the API, use Google Sheets “filter views” feature, which allows you to alphabetically and numerically sort and filter data -

Please check the following video for a complete example:

+Take a look at the following video for a complete example:
-

To summarize, the steps are:

+The preceding video performs the following steps in a blank Sheets document: + +1. Returns a list of DCIDs in column A that represent counties in California, using the formula **={"Place";DCPLACESIN(geoId/06", "County"}. +2. Uses the DCIDs in column A to fill in the names of each county in column B using the =DCGETNAME(A2) formula. +3. Retrieves the population of the county in column C using the DCIDs in column A using the =DCGET(A2, "Count_Person") formula. +4. Highlights the entire sheet and click Data menu, Filter views, then Create new filter, or click the Create a filter icon on the toolbar. +5. Next, the filter is sorted by the Population column from A-Z and then from Z-A. The same sorts are then performed on the Name column. + +To summarize, the steps for sorting Data Commons results with Google Sheets filter view feature are: + +1. Populate the data columns with Data Commons Sheets API formulas. +2. Turn on filter views by clicking the **Data** menu**,** **Filter views**, then **Create new filter view**, or by clicking the **Create a filter** icon on the toolbar +3. Click the reverse triangle on each column to sort, excluding the header row. - \ No newline at end of file diff --git a/assets/images/sheets/sheets_menu_bar.png b/assets/images/sheets/sheets_menu_bar.png index a9fc94c3f..d645dc394 100644 Binary files a/assets/images/sheets/sheets_menu_bar.png and b/assets/images/sheets/sheets_menu_bar.png differ diff --git a/assets/images/sheets/sheets_search_box.png b/assets/images/sheets/sheets_search_box.png index 5f3d652b6..f3eb3fb39 100644 Binary files a/assets/images/sheets/sheets_search_box.png and b/assets/images/sheets/sheets_search_box.png differ