Updates to Sheets places_in.md file (datacommonsorg#367)

* Updates to Sheets places_in.md file

* Updated with Carolyn's edits

* Updates based on Carolyn's feedback

* Conformed file to get_name.md
* Added Returns section
* Added Error Returns section
* Replaced images with narrower versions
* Added steps to examples
* Updated Gemfiles

* Updates from Carolyn

* Text and example image updates

* Gemfile from HEAD

* update formatting of examples

---------

Co-authored-by: Carolyn Au <[email protected]>
Co-authored-by: Carolyn Au <[email protected]>

Gemfile.lock

@@ -281,4 +281,4 @@ DEPENDENCIES
   webrick (~> 1.8)
 
 BUNDLED WITH
-   2.4.21
+   2.4.21

api/sheets/places_in.md

@@ -1,58 +1,75 @@
 ---
 layout: default
-title: Places within a Place
+title: Places Contained Within Another Place
 nav_order: 2
 parent: Google Sheets
 grand_parent: API
 ---
 
-# Retrieve places contained within another place
+# Retrieving Places Contained Within Another Place
 
-Given a list of parent [`Place`](https://datacommons.org/browser/Place) [DCIDs](/glossary.html),
-(e.g. any [`State`](https://datacommons.org/browser/State), [`Country`](https://datacommons.org/browser/Country), etc.), return a list of child places
-contained within the specified DCIDs. Only returns children whose place type matches
-the request's `placeType` parameter.
+The `=DCPLACESIN(dcids, placeType)` formula returns lists of child places from a list of parent [Place](https://datacommons.org/browser/Place) [DCIDs](https://docs.datacommons.org/glossary.html#dcid). It only returns children with a place type that matches the `placeType` parameter, such as [State](https://datacommons.org/browser/State), [Country](https://datacommons.org/browser/Country), and so on.
 
-## General information about this endpoint
+> **Note**
+>
+> Be sure to follow the instructions for [Installing and Enabling the Sheets Add-On](/api/sheets/) before using this formula.
 
-**Formula**: `=DCPLACESIN(dcids, placeType)`
+## Formula
 
-**Required arguments**:
+```
+=DCPLACESIN(dcids, placeType)
+```
 
-*   `dcids`: A list of (parent) `Place` nodes, identified by their DCIDs.
+## Required Arguments
 
-*   `placeType`: The type of the contained (child) `Place` nodes to filter by. For example, `City` and `County` are contained within `State`. For a
-    full list of available types, see [the Data Commons graph browser entry for `Place`](https://datacommons.org/browser/Place).
+* `dcids`: A list of parent `Place` nodes, identified by their DCIDs.
+* `placeType`: The type of the contained child `Place` nodes to filter by. For example,`City` and `County`are contained within `State`. For a full list of available types, see [the Data Commons graph browser entry for Place](https://datacommons.org/browser/Place).
 
+## Returns
 
-## Assembling the information you will need to use this formula
+Lists of child places from a list of parent [Place](https://datacommons.org/browser/Place) [DCIDs](https://docs.datacommons.org/glossary.html#dcid). Returns a list of child places of the specified place DCIDs, of the specified place type.
 
-This endpoint requires the argument `dcids`. [DCIDs](/glossary.html) are unique node identifiers defined by Data Commons. Your query will need to specify the DCIDs for the parent places of interest.
-
-This endpoint also requires the argument `placeType`, specifying the type of the child places you desire in the response.
+> **Note**:
+> It’s best to minimize the number of function calls to `=DCPLACESIN(dcids, placeType)` by using a single call to get the names for a column of nodes. This is because a spreadsheet will make one call to a Google server [*per custom function call*](https://developers.google.com/apps-script/guides/sheets/functions#optimization). If your sheet contains many separate calls to `=DCPLACESIN(dcids, placeType)` you can expect it to be slow and return with errors.
 
 ## Examples
 
-Before trying this method out, make sure to follow the setup directions in [the main section for Sheets docs](/api/sheets/index.html).
+This section contains examples of using the `=DCPLACESIN(dcids, placeType)` formula.
+
+### Example 1: Retrieve a List of Counties in Delaware
+
+To retrieve a list of counties in Delaware, perform the following steps:
 
-### Example 1: Retrieve a list of the counties in Delaware.
+1. Place your cursor in the cell where you want to add the DCID for Delaware. In this case, cell A2.
+2. Enter the Delaware DCID of <code><b>geoId/10</b></code>.
+3. (Optional) In cell B2, enter <code><b>DCGETNAME(A2)</b></code> to retrieve Delaware's name from the DCID in cell A2.
+4. Move to the cell C3 and enter the formula <code><b>=DCPLACESIN(A2, "County")</b></code> to retrieve the county names. The DCIDs for the three Delaware counties populate column C.
+5. Retrieve the Delaware county names by entering the formula <code><b>=DCGETNAME(C2:C4)</b></code> into cell D2.
 
-![](/assets/images/sheets/sheets_places_in_counties_in_delaware.png)
+![Retrieving a List of Counties in Delaware](/assets/images/sheets/sheets_places_in_counties_in_delaware.png)
 
-### Example 2: Retrieve a list of congressional districts in Alaska and Hawaii.
+### Example 2: Retrieve Congressional Districts in Alaska and Hawaii
 
-![](/assets/images/sheets/sheets_places_in_congressional_districts_ak_hi.png)
+To retrieve the congressional districts in Alaska and Hawaii, perform the following steps:
+
+1. In cell A2, enter <code><b>geoId/02</b></code> for the DCID of Alaska and in Cell A3, enter <code><b>geoId/15</b></code> for the DCID of Hawaii.
+2. (Optional) Enter <code><b>=DCGETNAME(A2:A3)</b></code> in cell B1 to retrieve the names of Alaska and Hawaii into column B.
+3. Retrieve the DCIDs for the congressional districts by enter <code><b>=DCPLACESIN(A2:A3, "CongressionalDistrict")</b></code> into cell C2.
+4. Finally, retrieve the names of the congressional districts by entering <code><b>=DCGETNAMES(C2:C4)</b></code> into cell D2.
+
+![Retrieving Congressional Districts in Alaska and Hawaii](/assets/images/sheets/sheets_places_in_congressional_districts_ak_hi.png)
 
 ## Error Responses
 
-If you pass a bad DCID value, you will see a reference error appear:
+If a DCID does not exist, the `=DCPLACESIN(dcids, placeType)` formula returns a value of #REF!. For example, the `=DCPLACESIN(A1, "CongressionalDistrict")` formula should return the congressional districts for the DCID in cell A1. However, because the “geoId/123123123” DCID does not exist, an error of #REF! is returned to cell B1 in the following sheet:
+
+![alt_text](/assets/images/sheets/sheets_places_in_wrong_dcid.png)
 
-![](/assets/images/sheets/sheets_places_in_bad_dcid.png)
+If you provide an empty cell for a DCID, the `=DCPLACESIN(dcids, placeType)` formula returns a value of #ERROR!, as shown show in the following image:
 
-Likewise, if you pass a nonexistent place type, you will also see a reference error appear:
+![alt_text](/assets/images/sheets/sheets_places_in_no_input.png)
 
-![](/assets/images/sheets/sheets_places_in_bad_place_type.png)
+Finally, if you provide an invalid property to the `=DCPLACESIN(dcids, placeType)` formula, an error of #REF! is also returned, as follows:
 
-If you pass an empty DCID, an error will appear:
+![alt_text](/assets/images/sheets/sheets_places_in_bad_property.png)
 
-![](/assets/images/sheets/sheets_places_in_empty_cell.png)