Skip to content

Commit

Permalink
Update outdated info in Sheets landing page (#477)
Browse files Browse the repository at this point in the history 
* troubleshooting API

* Revert to gerund

Though the style guide says to just use imperatives, "get started" just sounds weird. Also this is more consistent with "troubleshooting"

* fixed egregiously out-of-date info and added mention of Sheets to the concepts doc

* overhaul Sheets index page

* fix few mis-wordings

* restore mention of Workspace Marketplace

* tweak procedure

* Revert "tweak procedure"

This reverts commit d35bc34.

* tweak procedure again
  • Loading branch information
@kmoscoe
kmoscoe authored Aug 16, 2024
1 parent f93adb4 commit 1f99989
Show file tree
Hide file tree
Showing 4 changed files with 38 additions and 55 deletions.
80 changes: 30 additions & 50 deletions api/sheets/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,76 +6,56 @@ parent: API
has_children: true
---

# Data Commons Sheets API
# Data Commons Sheets add-on

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.
The Data Commons Sheets is a Google Sheets add-on that allows you 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 several custom functions for importing data into a spreadsheet.

> **Note:**
> For more information on DCIDs, refer to the entry for [DCID in the Glossary](/glossary.html#dcid).
Read our [step-by-step guides](tutorials/) for examples on using the add-on for various analysis and visualization use cases.

Also read our [step-by-step guides](tutorials/) for more examples.
## Install and enable the Sheets add-on

## Installing and Enabling the Sheets Add-On
1. Go to the [Google Workspace Marketplace](https://workspace.google.com/marketplace/app/data_commons/454343067575) page for Data Commons.
1. Click **Install**.
1. To enable the Sheets add-on functions, follow the next procedure below to open the **Fill place dcids** feature and fill a place DCID.

Install and enable the Sheets add-on from Google Workspace Marketplace, as follows:
> **Note:** None of the Data Commons Sheets functions will work in a spreadsheet until you have enabled the add-on by opening the **Fill place dcids** sidebar.
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.
## Find a place's DCID {#find-dcid}

![Google Sheets menu bar](/assets/images/sheets/sheets_menu_bar.png)
The Data Commons Sheets add-on provides the ability to look up a place’s [DCID](/glossary.html#dcid) by using the **Fill place dcids** feature. To find a place’s DCID:

> **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.
1. In Google Sheets, open a new or existing spreadsheet.
1. Select the destination cell where you want to add a place’s DCID.
1. Select **Extensions** > **Data Commons** > **Fill place dcids**.

## Finding a Place’s DCID
![Sheets menu bar](/assets/images/sheets/sheets_menu_bar.png)

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:
1. In the **Fill place dcids for selected cells** sidebar that appears, start typing the name of the place you are searching for.
1. 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”.

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)

Note that this feature currently only supports places in the United States.
## Data Commons Sheets functions

## Introduction to the Sheets API Custom Functions

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.
The Data Commons Sheets add-on includes the five formulas listed in the following table. Click the links in the table for detailed information on each formula.

| **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. |

See the links in the preceding table to subsequent pages in this section for detailed descriptions of each API.

## Sorting your Results

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

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

<div>
<video width="960" height="520" controls>
<source src="/assets/video/sort.webm" type="video/webm">
Your browser does not support the video tag.
</video>
</div>
| [=DCPLACESIN(dcids, place_type)](/api/sheets/places_in.html) | Returns places contained in other places. |
| [=DCGET(dcids, variable_name, [date])](/api/sheets/get_variable.html) | Returns statistical observations. |
| [=DCPROPERTY(dcids, property)](/api/sheets/get_property.html) | Returns node property values. |
| [=DCCOHORTMEMBERS(dcids)](/api/sheets/get_cohort_members.html) | Gets the cohort members of a node. |

The preceding video performs the following steps in a blank Sheets document:
## Get started with Data Commons functions

1. Returns a list of DCIDs in column A that represent counties in California, using the formula <code><b>={"Place";DCPLACESIN(geoId/06", "County"}</b></code>.
2. Uses the DCIDs in column A to fill in the names of each county in column B using the <code><b>=DCGETNAME(A2)</b></code> formula.
3. Retrieves the population of the county in column C using the DCIDs in column A using the <code><b>=DCGET(A2, "Count_Person")</b></code> 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.
Here's a quick demo on using several of the Data Commons functions to get population data for all counties in the state of California:

To summarize, the steps for sorting Data Commons results with Google Sheets filter view feature are:
1. Open a new sheet and create 3 column headings: `DCID`, `County name`, and `Population`.
1. Select cell A2 and enter the following formula to get a list of the DCIDs of all counties in California, whose DCID is `geoId/06`: `=DCPLACESIN("geoId/06", "County")`. The column fills with 58 DCIDs.
1. Select cell B2 and enter the following formula to get the names corresponding to all the DCIDs: `=DCGETNAME(A2:A59)`
1. Select cell C3 and enter the following formula to get the populations of each of the counties, using the statistical variable `Count_Person`: `=DCGET(A2:A59, "Count_Person")`

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.
Your spreadsheet should now look like this:

![Sheets first demo](/assets/images/sheets/home_page_demo.png){: height="400"}
Binary file added assets/images/sheets/home_page_demo.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 6 additions & 3 deletions data_model.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ DCIDs are not restricted to entities; statistical variables also have DCIDs. For

Many Data Commons tools and APIs require that you provide a DCID as input for a query. There are a few ways to do this.

To find the DCID for a place:
To find the DCID for a place using the datacommons.org website:

1. Go to [https://docs.datacommons.org/place_types.html](https://docs.datacommons.org/place_types.html).
1. Click the link on the place type of interest and click its link to open the Knowledge Graph page for the entity; for example, **City**.
Expand All @@ -108,6 +108,11 @@ To find the DCID for a place:

![KG browser]({{site.url}}/assets/images/dc/concept8.png){: width="900"}

To find the DCID for a place using other methods:

- Use the [Google Sheets add-on](/api/sheets/index.html#find-dcid) **Fill place dcids** feature.
- Use the REST v2 [Resolve API](/api/rest/v2/resolve.html), either interactively (e.g. using curl or the browser address bar) or programmatically.

To find the DCID for a statistical variable:

1. Open the Statistical Variable Explorer.
Expand All @@ -116,8 +121,6 @@ To find the DCID for a statistical variable:

![Stat Var Explorer]({{site.url}}/assets/images/dc/concept9.png){: width="900"}

To find a DCID programmatically for both entities and variables, you can use the REST v2 [Resolve API](/api/rest/v2/resolve.html).

## Property

Every node also contains properties or characteristics that describe its entity, event, or statistical variable. Each property is actually an edge to another node, with a label. If the object node is a primitive type, such as a string, date, or number, it is a "leaf", or terminal node, which we call an _attribute_. Examples are properties such as `latitude`, `year`, various unique IDs and so on.
Expand Down
4 changes: 2 additions & 2 deletions glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@ The date of measurement. Specified in ISO 8601 format. Examples include `2011` (
### DCID
{: #dcid}

Every entity in the Data Commons graph has a unique identifier, called ‘DCID’ (short for Data Commons Identifier). So, for example, the DCID of California is [`geoId/06`](https://datacommons.org/browser/geoId/06) and of India is [`country/IND`](https://datacommons.org/browser/country/IND). DCIDs are not restricted to entities; every node in the graph has a DCID. Statistical variables have DCID, for example the DCID for the Gini Index of Economic Activity is [`GiniIndex_EconomicActivity`](https://datacommons.org/tools/statvar#GiniIndex_EconomicActivity).
Every entity in the Data Commons graph has a unique identifier, called "DCID" (short for "Data Commons Identifier"). So, for example, the DCID of California is [`geoId/06`](https://datacommons.org/browser/geoId/06) and of India is [`country/IND`](https://datacommons.org/browser/country/IND). DCIDs are not restricted to entities; every node in the graph has a DCID. Statistical variables have DCID, for example the DCID for the Gini Index of Economic Activity is [`GiniIndex_EconomicActivity`](https://datacommons.org/tools/statvar#GiniIndex_EconomicActivity).

You can find the DCID for a place by searching for it in the [Place Explorer tool](https://datacommons.org/place), and the DCID for statistical variables in the [Statistical Variable Explorer tool](https://datacommons.org/tools/statvar). All nodes have an entry in the [Knowledge Graph](https://datacommons.org/browser/).
To find a DCID for an entity or variable, see the [Key concepts](/data_model.html#find-dcid) page.

### Entity
{: #entity}
Expand Down

0 comments on commit 1f99989

Please sign in to comment.