Updates to Sheets API index (datacommonsorg#365)

* Updates to Sheets index * New images for Sheets index * Updates to Sheets get_name.md doc * Updates to Sheets index.md and get_name.md files * Accept suggestion * Accept suggestion * Accept suggestion * Accept suggestion * Accept suggestion * Accept suggestion * Accept suggestion * Accept suggestion * Accept suggestion * Apply suggestions from code review * Update api/sheets/index.md Co-authored-by: Carolyn Au <[email protected]> * Update api/sheets/index.md Co-authored-by: Carolyn Au <[email protected]> * Image name change * Updates to index.md images * Removed get_name.md from the pull request * Removed get_name.md from the pull request * Deleted get_name.md and Gemfile.lock * Image updates Updated the two images so they aren't as wide and deleted the unnecessary images. * Restored get_name.md and Gemfile.lock files * Revert "Restored get_name.md and Gemfile.lock files" This reverts commit a0cd890. * Revert "Deleted get_name.md and Gemfile.lock" This reverts commit a091016. * Update Gemfile.lock revert to version at upstream/maser * Update get_name.md Revert to version at upstream/master * Additional changes from Carolyn * Added alt text to images * undo update to get_name.md * revert screenshot to remove fill place dcid panel when first installing plugin * Text / link / image edits * pr comments * small update to "notes" formatting --------- Co-authored-by: Carolyn Au <[email protected]> Co-authored-by: Carolyn Au <[email protected]>
miss-o-soup · Nov 3, 2023 · 4381777 · 4381777
1 parent b0c4bb6
commit 4381777
Show file tree

Hide file tree

Showing 3 changed files with 46 additions and 23 deletions.
diff --git 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
 
-<p>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
 
-<p>Please check the following video for a complete example:</p>
+Take a look at the following video for a complete example:
 
 <div>
 <video width="960" height="520" controls>
@@ -48,10 +64,17 @@ Your browser does not support the video tag.
 </video>
 </div>
 
-<p>To summarize, the steps are:</p>
+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 **<code>={"Place";DCPLACESIN(geoId/06", "County"}</code></strong>.
+2. Uses the DCIDs in column A to fill in the names of each county in column B using the <strong><code>=DCGETNAME(A2)</code></strong> formula.
+3. Retrieves the population of the county in column C using the DCIDs in column A using the <strong><code>=DCGET(A2, "Count_Person")</code></strong> formula.
+4. Highlights the entire sheet and click <strong>Data</strong> menu, <strong>Filter views</strong>, then <strong>Create new filter</strong>, or click the <strong>Create a filter</strong> icon on the toolbar.
+5. Next, the filter is sorted by the <strong>Population</strong> column from <strong>A-Z</strong> and then from <strong>Z-A</strong>. The same sorts are then performed on the <strong>Name</strong> 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.
 
-<ul>
-<li>Populate data columns with DataCommons Sheets API</li>
-<li>Turn on filter views (Data > Filter views).</li>
-<li>Click the reverse triangle on each column to sort by that column (and exclude header row).</li>
-</ul>
diff --git a/assets/images/sheets/sheets_menu_bar.png b/assets/images/sheets/sheets_menu_bar.png
diff --git a/assets/images/sheets/sheets_search_box.png b/assets/images/sheets/sheets_search_box.png