Repository: censusdis/censusdis (language: python)

Issue:
Multi-state geometry downloads
The `download()` function can retrieve census data for multiple states at a time. For instance, the following runs fine: 
```
GROUP = "B03002"
DATASET = "acs/acs5"
YEAR = 2020
CENSUS_API_KEY = None 

df_bg = ced.download(
    DATASET,
    YEAR,
    leaves_of_group=GROUP,
    state=["01", "02"],
    block_group="*",
    api_key=CENSUS_API_KEY)
```

However, adding `with_geometry = True` breaks the function with `Bad zip file retrieved from https://www2.census.gov/geo/tiger/GENZ2020/shp/cb_2020_01,02_bg_500k.zip.` The TIGER shapefiles are only supplied for each state and for the whole US, so these multi-state combinations don't work. The simplest solution is to download the full US data whenever more than one state is requested and filter the results. It would also be possible to implement a check such that when the number of states requested is below some threshold, the files are downloaded individually.


Discussion / hints:

Fix patch:
diff --git a/censusdis/data.py b/censusdis/data.py
index 5330bdc84..c05920a8e 100644
--- a/censusdis/data.py
+++ b/censusdis/data.py
@@ -441,23 +441,35 @@ def _add_geography(
     # If there is a single defined year then we can load the single
     # shapefile. If not, then we have to load multiple shapefiles,
     # one per year, and concatenate them.
+    #
+    # Whether there is a single or multiple years, there could also
+    # me mutliple scopes, e.g. states, for which we have to download
+    # shapefiles. If so, by the time we get here, they are encoded in
+    # one string with comma seperators.
     if isinstance(year, int):
-        gdf_shapefile = __shapefile_reader(year).read_cb_shapefile(
-            shapefile_scope,
-            shapefile_geo_level,
-        )
+        gdf_shapefile = gpd.GeoDataFrame()
+
+        for sub_scope in shapefile_scope.split(","):
+            gdf_shapefile = gdf_shapefile.append(
+                __shapefile_reader(year).read_cb_shapefile(
+                    sub_scope,
+                    shapefile_geo_level,
+                ),
+            )
         merge_gdf_on = gdf_on
     else:
         gdf_shapefiles = []
 
         for unique_year in df_data["YEAR"].unique():
             try:
-                gdf_shapefile_for_year = __shapefile_reader(
-                    unique_year
-                ).read_cb_shapefile(
-                    shapefile_scope,
-                    shapefile_geo_level,
-                )
+                gdf_shapefile_for_year = gpd.GeoDataFrame()
+                for sub_scope in shapefile_scope.split(","):
+                    gdf_shapefile_for_year = gdf_shapefile_for_year.append(
+                        __shapefile_reader(unique_year).read_cb_shapefile(
+                            sub_scope,
+                            shapefile_geo_level,
+                        )
+                    )
                 gdf_shapefile_for_year["YEAR"] = unique_year
                 gdf_shapefiles.append(gdf_shapefile_for_year)
             except cmap.MapException:
diff --git a/reports/coverage/coverage-badge.svg b/reports/coverage/coverage-badge.svg
index 4663fdb69..1badc7817 100644
--- a/reports/coverage/coverage-badge.svg
+++ b/reports/coverage/coverage-badge.svg
@@ -1,1 +1,1 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="114" height="20" role="img" aria-label="coverage: 95.10%"><title>coverage: 95.10%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">95.10%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">95.10%</text></g></svg>
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="114" height="20" role="img" aria-label="coverage: 95.12%"><title>coverage: 95.12%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">95.12%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">95.12%</text></g></svg>
\ No newline at end of file
diff --git a/reports/coverage/d_1ef9b076751c2c3b___init___py.html b/reports/coverage/d_1ef9b076751c2c3b___init___py.html
index 3627fbe74..0bdd0b280 100644
--- a/reports/coverage/d_1ef9b076751c2c3b___init___py.html
+++ b/reports/coverage/d_1ef9b076751c2c3b___init___py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b_exceptions_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -89,7 +89,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b_exceptions_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_1ef9b076751c2c3b_exceptions_py.html b/reports/coverage/d_1ef9b076751c2c3b_exceptions_py.html
index 89c48d4f8..1e94fc1ae 100644
--- a/reports/coverage/d_1ef9b076751c2c3b_exceptions_py.html
+++ b/reports/coverage/d_1ef9b076751c2c3b_exceptions_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b_fetch_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -97,7 +97,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b_fetch_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_1ef9b076751c2c3b_fetch_py.html b/reports/coverage/d_1ef9b076751c2c3b_fetch_py.html
index 93a331866..ce6d91c83 100644
--- a/reports/coverage/d_1ef9b076751c2c3b_fetch_py.html
+++ b/reports/coverage/d_1ef9b076751c2c3b_fetch_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b_varcache_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -148,7 +148,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b_varcache_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_1ef9b076751c2c3b_varcache_py.html b/reports/coverage/d_1ef9b076751c2c3b_varcache_py.html
index 8e71fa7c9..eea93c8eb 100644
--- a/reports/coverage/d_1ef9b076751c2c3b_varcache_py.html
+++ b/reports/coverage/d_1ef9b076751c2c3b_varcache_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_aea9b701da09b1b0___init___py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -782,7 +782,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_aea9b701da09b1b0___init___py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_5a366ca900b21d9c___init___py.html b/reports/coverage/d_5a366ca900b21d9c___init___py.html
index a015ca119..1ae7e359e 100644
--- a/reports/coverage/d_5a366ca900b21d9c___init___py.html
+++ b/reports/coverage/d_5a366ca900b21d9c___init___py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_data_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -92,7 +92,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_data_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_5a366ca900b21d9c_data_py.html b/reports/coverage/d_5a366ca900b21d9c_data_py.html
index 640de76fa..0d63a234d 100644
--- a/reports/coverage/d_5a366ca900b21d9c_data_py.html
+++ b/reports/coverage/d_5a366ca900b21d9c_data_py.html
@@ -54,8 +54,8 @@ <h1>
             </div>
         </aside>
         <h2>
-            <span class="text">214 statements &nbsp;</span>
-            <button type="button" class="run button_toggle_run" value="run" data-shortcut="r" title="Toggle lines run">207<span class="text"> run</span></button>
+            <span class="text">218 statements &nbsp;</span>
+            <button type="button" class="run button_toggle_run" value="run" data-shortcut="r" title="Toggle lines run">211<span class="text"> run</span></button>
             <button type="button" class="mis show_mis button_toggle_mis" value="mis" data-shortcut="m" title="Toggle lines missing">7<span class="text"> missing</span></button>
             <button type="button" class="exc show_exc button_toggle_exc" value="exc" data-shortcut="x" title="Toggle lines excluded">0<span class="text"> excluded</span></button>
         </h2>
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_geography_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -523,738 +523,750 @@ <h2>
     <p class="pln"><span class="n"><a id="t441" href="#t441">441</a></span><span class="t">    <span class="com"># If there is a single defined year then we can load the single</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t442" href="#t442">442</a></span><span class="t">    <span class="com"># shapefile. If not, then we have to load multiple shapefiles,</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t443" href="#t443">443</a></span><span class="t">    <span class="com"># one per year, and concatenate them.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t444" href="#t444">444</a></span><span class="t">    <span class="key">if</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">year</span><span class="op">,</span> <span class="nam">int</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t445" href="#t445">445</a></span><span class="t">        <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">__shapefile_reader</span><span class="op">(</span><span class="nam">year</span><span class="op">)</span><span class="op">.</span><span class="nam">read_cb_shapefile</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t446" href="#t446">446</a></span><span class="t">            <span class="nam">shapefile_scope</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t447" href="#t447">447</a></span><span class="t">            <span class="nam">shapefile_geo_level</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t448" href="#t448">448</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t449" href="#t449">449</a></span><span class="t">        <span class="nam">merge_gdf_on</span> <span class="op">=</span> <span class="nam">gdf_on</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t450" href="#t450">450</a></span><span class="t">    <span class="key">else</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t451" href="#t451">451</a></span><span class="t">        <span class="nam">gdf_shapefiles</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t452" href="#t452">452</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t453" href="#t453">453</a></span><span class="t">        <span class="key">for</span> <span class="nam">unique_year</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span><span class="op">.</span><span class="nam">unique</span><span class="op">(</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t454" href="#t454">454</a></span><span class="t">            <span class="key">try</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t455" href="#t455">455</a></span><span class="t">                <span class="nam">gdf_shapefile_for_year</span> <span class="op">=</span> <span class="nam">__shapefile_reader</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t456" href="#t456">456</a></span><span class="t">                    <span class="nam">unique_year</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t457" href="#t457">457</a></span><span class="t">                <span class="op">)</span><span class="op">.</span><span class="nam">read_cb_shapefile</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t458" href="#t458">458</a></span><span class="t">                    <span class="nam">shapefile_scope</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t459" href="#t459">459</a></span><span class="t">                    <span class="nam">shapefile_geo_level</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t460" href="#t460">460</a></span><span class="t">                <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t461" href="#t461">461</a></span><span class="t">                <span class="nam">gdf_shapefile_for_year</span><span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span> <span class="op">=</span> <span class="nam">unique_year</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t462" href="#t462">462</a></span><span class="t">                <span class="nam">gdf_shapefiles</span><span class="op">.</span><span class="nam">append</span><span class="op">(</span><span class="nam">gdf_shapefile_for_year</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t463" href="#t463">463</a></span><span class="t">            <span class="key">except</span> <span class="nam">cmap</span><span class="op">.</span><span class="nam">MapException</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t464" href="#t464">464</a></span><span class="t">                <span class="nam">logger</span><span class="op">.</span><span class="nam">info</span><span class="op">(</span><span class="str">"Unable to load shapefile for year %d"</span><span class="op">,</span> <span class="nam">unique_year</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t465" href="#t465">465</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t466" href="#t466">466</a></span><span class="t">        <span class="key">if</span> <span class="nam">len</span><span class="op">(</span><span class="nam">gdf_shapefiles</span><span class="op">)</span> <span class="op">==</span> <span class="num">0</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t467" href="#t467">467</a></span><span class="t">            <span class="com"># None of the years matched, so we add None for geometry to all.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t468" href="#t468">468</a></span><span class="t">            <span class="nam">gdf</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">copy</span><span class="op">=</span><span class="key">True</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t469" href="#t469">469</a></span><span class="t">            <span class="nam">gdf</span><span class="op">[</span><span class="str">"geometry"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t470" href="#t470">470</a></span><span class="t">            <span class="key">return</span> <span class="nam">gdf</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t471" href="#t471">471</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t472" href="#t472">472</a></span><span class="t">        <span class="com"># gpd.concat does not exist, so we have to pd.concat and</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t473" href="#t473">473</a></span><span class="t">        <span class="com"># then turn the df into a gdf.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t474" href="#t474">474</a></span><span class="t">        <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">concat</span><span class="op">(</span><span class="nam">gdf_shapefiles</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t475" href="#t475">475</a></span><span class="t">        <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="nam">gdf_shapefile</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t476" href="#t476">476</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t477" href="#t477">477</a></span><span class="t">        <span class="nam">merge_gdf_on</span> <span class="op">=</span> <span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span> <span class="op">+</span> <span class="nam">gdf_on</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t478" href="#t478">478</a></span><span class="t">        <span class="nam">df_on</span> <span class="op">=</span> <span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span> <span class="op">+</span> <span class="nam">df_on</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t479" href="#t479">479</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t480" href="#t480">480</a></span><span class="t">    <span class="nam">gdf_data</span> <span class="op">=</span> <span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t481" href="#t481">481</a></span><span class="t">        <span class="nam">gdf_shapefile</span><span class="op">[</span><span class="nam">merge_gdf_on</span> <span class="op">+</span> <span class="op">[</span><span class="str">"geometry"</span><span class="op">]</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t482" href="#t482">482</a></span><span class="t">        <span class="op">.</span><span class="nam">merge</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">how</span><span class="op">=</span><span class="str">"right"</span><span class="op">,</span> <span class="nam">left_on</span><span class="op">=</span><span class="nam">merge_gdf_on</span><span class="op">,</span> <span class="nam">right_on</span><span class="op">=</span><span class="nam">df_on</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t483" href="#t483">483</a></span><span class="t">        <span class="op">.</span><span class="nam">drop</span><span class="op">(</span><span class="nam">gdf_on</span><span class="op">,</span> <span class="nam">axis</span><span class="op">=</span><span class="str">"columns"</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t484" href="#t484">484</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t485" href="#t485">485</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t486" href="#t486">486</a></span><span class="t">    <span class="com"># Rearrange columns so geometry is at the end.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t487" href="#t487">487</a></span><span class="t">    <span class="nam">gdf_data</span> <span class="op">=</span> <span class="nam">gdf_data</span><span class="op">[</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t488" href="#t488">488</a></span><span class="t">        <span class="op">[</span><span class="nam">col</span> <span class="key">for</span> <span class="nam">col</span> <span class="key">in</span> <span class="nam">gdf_data</span><span class="op">.</span><span class="nam">columns</span> <span class="key">if</span> <span class="nam">col</span> <span class="op">!=</span> <span class="str">"geometry"</span><span class="op">]</span> <span class="op">+</span> <span class="op">[</span><span class="str">"geometry"</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t489" href="#t489">489</a></span><span class="t">    <span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t490" href="#t490">490</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t491" href="#t491">491</a></span><span class="t">    <span class="key">return</span> <span class="nam">gdf_data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t492" href="#t492">492</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t493" href="#t493">493</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t494" href="#t494">494</a></span><span class="t"><span class="key">def</span> <span class="nam">infer_geo_level</span><span class="op">(</span><span class="nam">df_data</span><span class="op">:</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">)</span> <span class="op">-></span> <span class="nam">str</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t495" href="#t495">495</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t496" href="#t496">496</a></span><span class="t"><span class="str">    Infer the geography level based on columns names.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t444" href="#t444">444</a></span><span class="t">    <span class="com">#</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t445" href="#t445">445</a></span><span class="t">    <span class="com"># Whether there is a single or multiple years, there could also</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t446" href="#t446">446</a></span><span class="t">    <span class="com"># me mutliple scopes, e.g. states, for which we have to download</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t447" href="#t447">447</a></span><span class="t">    <span class="com"># shapefiles. If so, by the time we get here, they are encoded in</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t448" href="#t448">448</a></span><span class="t">    <span class="com"># one string with comma seperators.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t449" href="#t449">449</a></span><span class="t">    <span class="key">if</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">year</span><span class="op">,</span> <span class="nam">int</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t450" href="#t450">450</a></span><span class="t">        <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t451" href="#t451">451</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t452" href="#t452">452</a></span><span class="t">        <span class="key">for</span> <span class="nam">sub_scope</span> <span class="key">in</span> <span class="nam">shapefile_scope</span><span class="op">.</span><span class="nam">split</span><span class="op">(</span><span class="str">","</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t453" href="#t453">453</a></span><span class="t">            <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">gdf_shapefile</span><span class="op">.</span><span class="nam">append</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t454" href="#t454">454</a></span><span class="t">                <span class="nam">__shapefile_reader</span><span class="op">(</span><span class="nam">year</span><span class="op">)</span><span class="op">.</span><span class="nam">read_cb_shapefile</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t455" href="#t455">455</a></span><span class="t">                    <span class="nam">sub_scope</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t456" href="#t456">456</a></span><span class="t">                    <span class="nam">shapefile_geo_level</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t457" href="#t457">457</a></span><span class="t">                <span class="op">)</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t458" href="#t458">458</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t459" href="#t459">459</a></span><span class="t">        <span class="nam">merge_gdf_on</span> <span class="op">=</span> <span class="nam">gdf_on</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t460" href="#t460">460</a></span><span class="t">    <span class="key">else</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t461" href="#t461">461</a></span><span class="t">        <span class="nam">gdf_shapefiles</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t462" href="#t462">462</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t463" href="#t463">463</a></span><span class="t">        <span class="key">for</span> <span class="nam">unique_year</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span><span class="op">.</span><span class="nam">unique</span><span class="op">(</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t464" href="#t464">464</a></span><span class="t">            <span class="key">try</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t465" href="#t465">465</a></span><span class="t">                <span class="nam">gdf_shapefile_for_year</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t466" href="#t466">466</a></span><span class="t">                <span class="key">for</span> <span class="nam">sub_scope</span> <span class="key">in</span> <span class="nam">shapefile_scope</span><span class="op">.</span><span class="nam">split</span><span class="op">(</span><span class="str">","</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t467" href="#t467">467</a></span><span class="t">                    <span class="nam">gdf_shapefile_for_year</span> <span class="op">=</span> <span class="nam">gdf_shapefile_for_year</span><span class="op">.</span><span class="nam">append</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t468" href="#t468">468</a></span><span class="t">                        <span class="nam">__shapefile_reader</span><span class="op">(</span><span class="nam">unique_year</span><span class="op">)</span><span class="op">.</span><span class="nam">read_cb_shapefile</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t469" href="#t469">469</a></span><span class="t">                            <span class="nam">sub_scope</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t470" href="#t470">470</a></span><span class="t">                            <span class="nam">shapefile_geo_level</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t471" href="#t471">471</a></span><span class="t">                        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t472" href="#t472">472</a></span><span class="t">                    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t473" href="#t473">473</a></span><span class="t">                <span class="nam">gdf_shapefile_for_year</span><span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span> <span class="op">=</span> <span class="nam">unique_year</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t474" href="#t474">474</a></span><span class="t">                <span class="nam">gdf_shapefiles</span><span class="op">.</span><span class="nam">append</span><span class="op">(</span><span class="nam">gdf_shapefile_for_year</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t475" href="#t475">475</a></span><span class="t">            <span class="key">except</span> <span class="nam">cmap</span><span class="op">.</span><span class="nam">MapException</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t476" href="#t476">476</a></span><span class="t">                <span class="nam">logger</span><span class="op">.</span><span class="nam">info</span><span class="op">(</span><span class="str">"Unable to load shapefile for year %d"</span><span class="op">,</span> <span class="nam">unique_year</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t477" href="#t477">477</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t478" href="#t478">478</a></span><span class="t">        <span class="key">if</span> <span class="nam">len</span><span class="op">(</span><span class="nam">gdf_shapefiles</span><span class="op">)</span> <span class="op">==</span> <span class="num">0</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t479" href="#t479">479</a></span><span class="t">            <span class="com"># None of the years matched, so we add None for geometry to all.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t480" href="#t480">480</a></span><span class="t">            <span class="nam">gdf</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">copy</span><span class="op">=</span><span class="key">True</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t481" href="#t481">481</a></span><span class="t">            <span class="nam">gdf</span><span class="op">[</span><span class="str">"geometry"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t482" href="#t482">482</a></span><span class="t">            <span class="key">return</span> <span class="nam">gdf</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t483" href="#t483">483</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t484" href="#t484">484</a></span><span class="t">        <span class="com"># gpd.concat does not exist, so we have to pd.concat and</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t485" href="#t485">485</a></span><span class="t">        <span class="com"># then turn the df into a gdf.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t486" href="#t486">486</a></span><span class="t">        <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">concat</span><span class="op">(</span><span class="nam">gdf_shapefiles</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t487" href="#t487">487</a></span><span class="t">        <span class="nam">gdf_shapefile</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="nam">gdf_shapefile</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t488" href="#t488">488</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t489" href="#t489">489</a></span><span class="t">        <span class="nam">merge_gdf_on</span> <span class="op">=</span> <span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span> <span class="op">+</span> <span class="nam">gdf_on</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t490" href="#t490">490</a></span><span class="t">        <span class="nam">df_on</span> <span class="op">=</span> <span class="op">[</span><span class="str">"YEAR"</span><span class="op">]</span> <span class="op">+</span> <span class="nam">df_on</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t491" href="#t491">491</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t492" href="#t492">492</a></span><span class="t">    <span class="nam">gdf_data</span> <span class="op">=</span> <span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t493" href="#t493">493</a></span><span class="t">        <span class="nam">gdf_shapefile</span><span class="op">[</span><span class="nam">merge_gdf_on</span> <span class="op">+</span> <span class="op">[</span><span class="str">"geometry"</span><span class="op">]</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t494" href="#t494">494</a></span><span class="t">        <span class="op">.</span><span class="nam">merge</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">how</span><span class="op">=</span><span class="str">"right"</span><span class="op">,</span> <span class="nam">left_on</span><span class="op">=</span><span class="nam">merge_gdf_on</span><span class="op">,</span> <span class="nam">right_on</span><span class="op">=</span><span class="nam">df_on</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t495" href="#t495">495</a></span><span class="t">        <span class="op">.</span><span class="nam">drop</span><span class="op">(</span><span class="nam">gdf_on</span><span class="op">,</span> <span class="nam">axis</span><span class="op">=</span><span class="str">"columns"</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t496" href="#t496">496</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t497" href="#t497">497</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t498" href="#t498">498</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t499" href="#t499">499</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t500" href="#t500">500</a></span><span class="t"><span class="str">    df_data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t501" href="#t501">501</a></span><span class="t"><span class="str">        A dataframe of variables with one or more columns that</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t502" href="#t502">502</a></span><span class="t"><span class="str">        can be used to infer what geometry level the rows represent.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t503" href="#t503">503</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t504" href="#t504">504</a></span><span class="t"><span class="str">        For example, if the column `"STATE"` exists, we could infer that</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t505" href="#t505">505</a></span><span class="t"><span class="str">        the data in on a state by state basis. But if there are</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t506" href="#t506">506</a></span><span class="t"><span class="str">        columns for both `"STATE"` and `"COUNTY"`, the data is probably</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t507" href="#t507">507</a></span><span class="t"><span class="str">        at the county level.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t508" href="#t508">508</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t509" href="#t509">509</a></span><span class="t"><span class="str">        If, on the other hand, there is a `"COUNTY" column but not a</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t510" href="#t510">510</a></span><span class="t"><span class="str">        `"STATE"` column, then there is some ambiguity. The data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t511" href="#t511">511</a></span><span class="t"><span class="str">        probably corresponds to counties, but the same county ID can</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t512" href="#t512">512</a></span><span class="t"><span class="str">        exist in multiple states, so we will raise a</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t513" href="#t513">513</a></span><span class="t"><span class="str">        :py:class:`~CensusApiException` with an error message expalining</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t514" href="#t514">514</a></span><span class="t"><span class="str">        the situation.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t498" href="#t498">498</a></span><span class="t">    <span class="com"># Rearrange columns so geometry is at the end.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t499" href="#t499">499</a></span><span class="t">    <span class="nam">gdf_data</span> <span class="op">=</span> <span class="nam">gdf_data</span><span class="op">[</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t500" href="#t500">500</a></span><span class="t">        <span class="op">[</span><span class="nam">col</span> <span class="key">for</span> <span class="nam">col</span> <span class="key">in</span> <span class="nam">gdf_data</span><span class="op">.</span><span class="nam">columns</span> <span class="key">if</span> <span class="nam">col</span> <span class="op">!=</span> <span class="str">"geometry"</span><span class="op">]</span> <span class="op">+</span> <span class="op">[</span><span class="str">"geometry"</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t501" href="#t501">501</a></span><span class="t">    <span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t502" href="#t502">502</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t503" href="#t503">503</a></span><span class="t">    <span class="key">return</span> <span class="nam">gdf_data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t504" href="#t504">504</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t505" href="#t505">505</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t506" href="#t506">506</a></span><span class="t"><span class="key">def</span> <span class="nam">infer_geo_level</span><span class="op">(</span><span class="nam">df_data</span><span class="op">:</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">)</span> <span class="op">-></span> <span class="nam">str</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t507" href="#t507">507</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t508" href="#t508">508</a></span><span class="t"><span class="str">    Infer the geography level based on columns names.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t509" href="#t509">509</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t510" href="#t510">510</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t511" href="#t511">511</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t512" href="#t512">512</a></span><span class="t"><span class="str">    df_data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t513" href="#t513">513</a></span><span class="t"><span class="str">        A dataframe of variables with one or more columns that</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t514" href="#t514">514</a></span><span class="t"><span class="str">        can be used to infer what geometry level the rows represent.</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t515" href="#t515">515</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t516" href="#t516">516</a></span><span class="t"><span class="str">        If there is no match, we will also raise an exception. Again we</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t517" href="#t517">517</a></span><span class="t"><span class="str">        do this, rather than for example, returning `None`, so that we</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t518" href="#t518">518</a></span><span class="t"><span class="str">        can provide an informative error message about the likely cause</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t519" href="#t519">519</a></span><span class="t"><span class="str">        and what to do about it.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t516" href="#t516">516</a></span><span class="t"><span class="str">        For example, if the column `"STATE"` exists, we could infer that</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t517" href="#t517">517</a></span><span class="t"><span class="str">        the data in on a state by state basis. But if there are</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t518" href="#t518">518</a></span><span class="t"><span class="str">        columns for both `"STATE"` and `"COUNTY"`, the data is probably</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t519" href="#t519">519</a></span><span class="t"><span class="str">        at the county level.</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t520" href="#t520">520</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t521" href="#t521">521</a></span><span class="t"><span class="str">        This function is not often called directly, but rather from</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t522" href="#t522">522</a></span><span class="t"><span class="str">        :py:func:`~add_inferred_geography`, which infers the geography</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t523" href="#t523">523</a></span><span class="t"><span class="str">        level and then adds a `geometry` column containing the appropriate</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t524" href="#t524">524</a></span><span class="t"><span class="str">        geography for each row.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t525" href="#t525">525</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t526" href="#t526">526</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t527" href="#t527">527</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t528" href="#t528">528</a></span><span class="t"><span class="str">        The name of the geography level.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t529" href="#t529">529</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t530" href="#t530">530</a></span><span class="t">    <span class="nam">match_key</span> <span class="op">=</span> <span class="key">None</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t531" href="#t531">531</a></span><span class="t">    <span class="nam">match_on_len</span> <span class="op">=</span> <span class="num">0</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t532" href="#t532">532</a></span><span class="t">    <span class="nam">partial_match_keys</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t533" href="#t533">533</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t534" href="#t534">534</a></span><span class="t">    <span class="key">for</span> <span class="nam">k</span><span class="op">,</span> <span class="op">(</span><span class="nam">_</span><span class="op">,</span> <span class="nam">_</span><span class="op">,</span> <span class="nam">df_on</span><span class="op">,</span> <span class="nam">_</span><span class="op">)</span> <span class="key">in</span> <span class="nam">_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO</span><span class="op">.</span><span class="nam">items</span><span class="op">(</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t535" href="#t535">535</a></span><span class="t">        <span class="key">if</span> <span class="nam">all</span><span class="op">(</span><span class="nam">col</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">columns</span> <span class="key">for</span> <span class="nam">col</span> <span class="key">in</span> <span class="nam">df_on</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t536" href="#t536">536</a></span><span class="t">            <span class="com"># Full match. We want the longest full match</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t537" href="#t537">537</a></span><span class="t">            <span class="com"># we find.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t538" href="#t538">538</a></span><span class="t">            <span class="key">if</span> <span class="nam">match_key</span> <span class="key">is</span> <span class="key">None</span> <span class="key">or</span> <span class="nam">len</span><span class="op">(</span><span class="nam">df_on</span><span class="op">)</span> <span class="op">></span> <span class="nam">match_on_len</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t539" href="#t539">539</a></span><span class="t">                <span class="nam">match_key</span> <span class="op">=</span> <span class="nam">k</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t540" href="#t540">540</a></span><span class="t">        <span class="key">elif</span> <span class="nam">df_on</span><span class="op">[</span><span class="op">-</span><span class="num">1</span><span class="op">]</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">columns</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t541" href="#t541">541</a></span><span class="t">            <span class="com"># Partial match. This could result in us</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t542" href="#t542">542</a></span><span class="t">            <span class="com"># not getting what we expect. Like if we</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t543" href="#t543">543</a></span><span class="t">            <span class="com"># have STATE and TRACT, but not COUNTY, we will</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t544" href="#t544">544</a></span><span class="t">            <span class="com"># get a partial match on [STATE, COUNTY. TRACT]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t545" href="#t545">545</a></span><span class="t">            <span class="com"># and a full match on [STATE]. We probably did</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t546" href="#t546">546</a></span><span class="t">            <span class="com"># not mean to match [STATE], we just lost the</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t547" href="#t547">547</a></span><span class="t">            <span class="com"># COUNTY column somewhere along the way.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t548" href="#t548">548</a></span><span class="t">            <span class="nam">partial_match_keys</span><span class="op">.</span><span class="nam">append</span><span class="op">(</span><span class="nam">k</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t549" href="#t549">549</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t550" href="#t550">550</a></span><span class="t">    <span class="key">if</span> <span class="nam">match_key</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t551" href="#t551">551</a></span><span class="t">        <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t552" href="#t552">552</a></span><span class="t">            <span class="str">f"Unable to infer geometry. Was not able to locate any of the "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t553" href="#t553">553</a></span><span class="t">            <span class="str">"known sets of columns "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t554" href="#t554">554</a></span><span class="t">            <span class="str">f"{tuple(df_on for _, _, df_on, _ in _GEO_QUERY_FROM_DATA_QUERY_INNER_GEO.values())} "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t555" href="#t555">555</a></span><span class="t">            <span class="str">f"in the columns {list(df_data.columns)}."</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t556" href="#t556">556</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t557" href="#t557">557</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t558" href="#t558">558</a></span><span class="t">    <span class="key">if</span> <span class="nam">partial_match_keys</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t559" href="#t559">559</a></span><span class="t">        <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t560" href="#t560">560</a></span><span class="t">            <span class="str">f"Unable to infer geometry. Geometry matched {match_key} on columns "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t561" href="#t561">561</a></span><span class="t">            <span class="str">f"{_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO[match_key][2]} "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t562" href="#t562">562</a></span><span class="t">            <span class="str">"but also partially matched one or more candidates "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t563" href="#t563">563</a></span><span class="t">            <span class="str">f"{tuple(_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO[k][2] for k in partial_match_keys)}. "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t564" href="#t564">564</a></span><span class="t">            <span class="str">"Partial matches are usually unintended. Either add columns to allow a "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t565" href="#t565">565</a></span><span class="t">            <span class="str">"full match or rename some columns to prevent the undesired partial match."</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t566" href="#t566">566</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t567" href="#t567">567</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t568" href="#t568">568</a></span><span class="t">    <span class="key">return</span> <span class="nam">match_key</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t521" href="#t521">521</a></span><span class="t"><span class="str">        If, on the other hand, there is a `"COUNTY" column but not a</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t522" href="#t522">522</a></span><span class="t"><span class="str">        `"STATE"` column, then there is some ambiguity. The data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t523" href="#t523">523</a></span><span class="t"><span class="str">        probably corresponds to counties, but the same county ID can</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t524" href="#t524">524</a></span><span class="t"><span class="str">        exist in multiple states, so we will raise a</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t525" href="#t525">525</a></span><span class="t"><span class="str">        :py:class:`~CensusApiException` with an error message expalining</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t526" href="#t526">526</a></span><span class="t"><span class="str">        the situation.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t527" href="#t527">527</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t528" href="#t528">528</a></span><span class="t"><span class="str">        If there is no match, we will also raise an exception. Again we</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t529" href="#t529">529</a></span><span class="t"><span class="str">        do this, rather than for example, returning `None`, so that we</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t530" href="#t530">530</a></span><span class="t"><span class="str">        can provide an informative error message about the likely cause</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t531" href="#t531">531</a></span><span class="t"><span class="str">        and what to do about it.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t532" href="#t532">532</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t533" href="#t533">533</a></span><span class="t"><span class="str">        This function is not often called directly, but rather from</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t534" href="#t534">534</a></span><span class="t"><span class="str">        :py:func:`~add_inferred_geography`, which infers the geography</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t535" href="#t535">535</a></span><span class="t"><span class="str">        level and then adds a `geometry` column containing the appropriate</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t536" href="#t536">536</a></span><span class="t"><span class="str">        geography for each row.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t537" href="#t537">537</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t538" href="#t538">538</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t539" href="#t539">539</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t540" href="#t540">540</a></span><span class="t"><span class="str">        The name of the geography level.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t541" href="#t541">541</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t542" href="#t542">542</a></span><span class="t">    <span class="nam">match_key</span> <span class="op">=</span> <span class="key">None</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t543" href="#t543">543</a></span><span class="t">    <span class="nam">match_on_len</span> <span class="op">=</span> <span class="num">0</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t544" href="#t544">544</a></span><span class="t">    <span class="nam">partial_match_keys</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t545" href="#t545">545</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t546" href="#t546">546</a></span><span class="t">    <span class="key">for</span> <span class="nam">k</span><span class="op">,</span> <span class="op">(</span><span class="nam">_</span><span class="op">,</span> <span class="nam">_</span><span class="op">,</span> <span class="nam">df_on</span><span class="op">,</span> <span class="nam">_</span><span class="op">)</span> <span class="key">in</span> <span class="nam">_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO</span><span class="op">.</span><span class="nam">items</span><span class="op">(</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t547" href="#t547">547</a></span><span class="t">        <span class="key">if</span> <span class="nam">all</span><span class="op">(</span><span class="nam">col</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">columns</span> <span class="key">for</span> <span class="nam">col</span> <span class="key">in</span> <span class="nam">df_on</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t548" href="#t548">548</a></span><span class="t">            <span class="com"># Full match. We want the longest full match</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t549" href="#t549">549</a></span><span class="t">            <span class="com"># we find.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t550" href="#t550">550</a></span><span class="t">            <span class="key">if</span> <span class="nam">match_key</span> <span class="key">is</span> <span class="key">None</span> <span class="key">or</span> <span class="nam">len</span><span class="op">(</span><span class="nam">df_on</span><span class="op">)</span> <span class="op">></span> <span class="nam">match_on_len</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t551" href="#t551">551</a></span><span class="t">                <span class="nam">match_key</span> <span class="op">=</span> <span class="nam">k</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t552" href="#t552">552</a></span><span class="t">        <span class="key">elif</span> <span class="nam">df_on</span><span class="op">[</span><span class="op">-</span><span class="num">1</span><span class="op">]</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">columns</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t553" href="#t553">553</a></span><span class="t">            <span class="com"># Partial match. This could result in us</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t554" href="#t554">554</a></span><span class="t">            <span class="com"># not getting what we expect. Like if we</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t555" href="#t555">555</a></span><span class="t">            <span class="com"># have STATE and TRACT, but not COUNTY, we will</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t556" href="#t556">556</a></span><span class="t">            <span class="com"># get a partial match on [STATE, COUNTY. TRACT]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t557" href="#t557">557</a></span><span class="t">            <span class="com"># and a full match on [STATE]. We probably did</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t558" href="#t558">558</a></span><span class="t">            <span class="com"># not mean to match [STATE], we just lost the</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t559" href="#t559">559</a></span><span class="t">            <span class="com"># COUNTY column somewhere along the way.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t560" href="#t560">560</a></span><span class="t">            <span class="nam">partial_match_keys</span><span class="op">.</span><span class="nam">append</span><span class="op">(</span><span class="nam">k</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t561" href="#t561">561</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t562" href="#t562">562</a></span><span class="t">    <span class="key">if</span> <span class="nam">match_key</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t563" href="#t563">563</a></span><span class="t">        <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t564" href="#t564">564</a></span><span class="t">            <span class="str">f"Unable to infer geometry. Was not able to locate any of the "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t565" href="#t565">565</a></span><span class="t">            <span class="str">"known sets of columns "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t566" href="#t566">566</a></span><span class="t">            <span class="str">f"{tuple(df_on for _, _, df_on, _ in _GEO_QUERY_FROM_DATA_QUERY_INNER_GEO.values())} "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t567" href="#t567">567</a></span><span class="t">            <span class="str">f"in the columns {list(df_data.columns)}."</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t568" href="#t568">568</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t569" href="#t569">569</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t570" href="#t570">570</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t571" href="#t571">571</a></span><span class="t"><span class="key">def</span> <span class="nam">add_inferred_geography</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t572" href="#t572">572</a></span><span class="t">    <span class="nam">df_data</span><span class="op">:</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">year</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">int</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t573" href="#t573">573</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t574" href="#t574">574</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t575" href="#t575">575</a></span><span class="t"><span class="str">    Infer the geography level of the given dataframe and</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t576" href="#t576">576</a></span><span class="t"><span class="str">    add geometry to each row for that level.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t577" href="#t577">577</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t578" href="#t578">578</a></span><span class="t"><span class="str">    See Also</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t579" href="#t579">579</a></span><span class="t"><span class="str">    --------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t580" href="#t580">580</a></span><span class="t"><span class="str">        :py:ref:`~infer_geo_level` for more on how inference is done.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t570" href="#t570">570</a></span><span class="t">    <span class="key">if</span> <span class="nam">partial_match_keys</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t571" href="#t571">571</a></span><span class="t">        <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t572" href="#t572">572</a></span><span class="t">            <span class="str">f"Unable to infer geometry. Geometry matched {match_key} on columns "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t573" href="#t573">573</a></span><span class="t">            <span class="str">f"{_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO[match_key][2]} "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t574" href="#t574">574</a></span><span class="t">            <span class="str">"but also partially matched one or more candidates "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t575" href="#t575">575</a></span><span class="t">            <span class="str">f"{tuple(_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO[k][2] for k in partial_match_keys)}. "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t576" href="#t576">576</a></span><span class="t">            <span class="str">"Partial matches are usually unintended. Either add columns to allow a "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t577" href="#t577">577</a></span><span class="t">            <span class="str">"full match or rename some columns to prevent the undesired partial match."</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t578" href="#t578">578</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t579" href="#t579">579</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t580" href="#t580">580</a></span><span class="t">    <span class="key">return</span> <span class="nam">match_key</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t581" href="#t581">581</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t582" href="#t582">582</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t583" href="#t583">583</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t584" href="#t584">584</a></span><span class="t"><span class="str">    df_data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t585" href="#t585">585</a></span><span class="t"><span class="str">        A dataframe of variables with one or more columns that</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t586" href="#t586">586</a></span><span class="t"><span class="str">        can be used to infer what geometry level the rows represent.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t587" href="#t587">587</a></span><span class="t"><span class="str">    year</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t588" href="#t588">588</a></span><span class="t"><span class="str">        The year for which to fetch geometries. We need this</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t589" href="#t589">589</a></span><span class="t"><span class="str">        because they change over time. If `None`, look for a</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t590" href="#t590">590</a></span><span class="t"><span class="str">        `'YEAR'` column in `df_data` and possibly add different</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t591" href="#t591">591</a></span><span class="t"><span class="str">        geometries for different years as needed.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t592" href="#t592">592</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t593" href="#t593">593</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t594" href="#t594">594</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t595" href="#t595">595</a></span><span class="t"><span class="str">        A geo data frame containing the original data augmented with</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t596" href="#t596">596</a></span><span class="t"><span class="str">        the appropriate geometry for each row.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t597" href="#t597">597</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t598" href="#t598">598</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t599" href="#t599">599</a></span><span class="t">    <span class="nam">geo_level</span> <span class="op">=</span> <span class="nam">infer_geo_level</span><span class="op">(</span><span class="nam">df_data</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t600" href="#t600">600</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t601" href="#t601">601</a></span><span class="t">    <span class="nam">shapefile_scope</span> <span class="op">=</span> <span class="nam">_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO</span><span class="op">[</span><span class="nam">geo_level</span><span class="op">]</span><span class="op">[</span><span class="num">0</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t602" href="#t602">602</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t603" href="#t603">603</a></span><span class="t">    <span class="key">if</span> <span class="nam">shapefile_scope</span> <span class="key">is</span> <span class="key">not</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t604" href="#t604">604</a></span><span class="t">        <span class="com"># The scope is the same across the board.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t605" href="#t605">605</a></span><span class="t">        <span class="nam">gdf</span> <span class="op">=</span> <span class="nam">_add_geography</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">year</span><span class="op">,</span> <span class="nam">shapefile_scope</span><span class="op">,</span> <span class="nam">geo_level</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t606" href="#t606">606</a></span><span class="t">        <span class="key">return</span> <span class="nam">gdf</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t607" href="#t607">607</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t608" href="#t608">608</a></span><span class="t">    <span class="com"># We have to group by different values of the shapefile</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t609" href="#t609">609</a></span><span class="t">    <span class="com"># scope from the appropriate column and add the right</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t610" href="#t610">610</a></span><span class="t">    <span class="com"># geography to each group.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t611" href="#t611">611</a></span><span class="t">    <span class="nam">shapefile_scope_column</span> <span class="op">=</span> <span class="nam">_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO</span><span class="op">[</span><span class="nam">geo_level</span><span class="op">]</span><span class="op">[</span><span class="num">2</span><span class="op">]</span><span class="op">[</span><span class="num">0</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t582" href="#t582">582</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t583" href="#t583">583</a></span><span class="t"><span class="key">def</span> <span class="nam">add_inferred_geography</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t584" href="#t584">584</a></span><span class="t">    <span class="nam">df_data</span><span class="op">:</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">year</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">int</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t585" href="#t585">585</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t586" href="#t586">586</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t587" href="#t587">587</a></span><span class="t"><span class="str">    Infer the geography level of the given dataframe and</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t588" href="#t588">588</a></span><span class="t"><span class="str">    add geometry to each row for that level.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t589" href="#t589">589</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t590" href="#t590">590</a></span><span class="t"><span class="str">    See Also</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t591" href="#t591">591</a></span><span class="t"><span class="str">    --------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t592" href="#t592">592</a></span><span class="t"><span class="str">        :py:ref:`~infer_geo_level` for more on how inference is done.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t593" href="#t593">593</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t594" href="#t594">594</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t595" href="#t595">595</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t596" href="#t596">596</a></span><span class="t"><span class="str">    df_data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t597" href="#t597">597</a></span><span class="t"><span class="str">        A dataframe of variables with one or more columns that</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t598" href="#t598">598</a></span><span class="t"><span class="str">        can be used to infer what geometry level the rows represent.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t599" href="#t599">599</a></span><span class="t"><span class="str">    year</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t600" href="#t600">600</a></span><span class="t"><span class="str">        The year for which to fetch geometries. We need this</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t601" href="#t601">601</a></span><span class="t"><span class="str">        because they change over time. If `None`, look for a</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t602" href="#t602">602</a></span><span class="t"><span class="str">        `'YEAR'` column in `df_data` and possibly add different</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t603" href="#t603">603</a></span><span class="t"><span class="str">        geometries for different years as needed.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t604" href="#t604">604</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t605" href="#t605">605</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t606" href="#t606">606</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t607" href="#t607">607</a></span><span class="t"><span class="str">        A geo data frame containing the original data augmented with</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t608" href="#t608">608</a></span><span class="t"><span class="str">        the appropriate geometry for each row.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t609" href="#t609">609</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t610" href="#t610">610</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t611" href="#t611">611</a></span><span class="t">    <span class="nam">geo_level</span> <span class="op">=</span> <span class="nam">infer_geo_level</span><span class="op">(</span><span class="nam">df_data</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t612" href="#t612">612</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t613" href="#t613">613</a></span><span class="t">    <span class="nam">df_with_geo</span> <span class="op">=</span> <span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t614" href="#t614">614</a></span><span class="t">        <span class="nam">df_data</span><span class="op">.</span><span class="nam">groupby</span><span class="op">(</span><span class="nam">shapefile_scope_column</span><span class="op">,</span> <span class="nam">group_keys</span><span class="op">=</span><span class="key">False</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t615" href="#t615">615</a></span><span class="t">        <span class="op">.</span><span class="nam">apply</span><span class="op">(</span><span class="key">lambda</span> <span class="nam">g</span><span class="op">:</span> <span class="nam">_add_geography</span><span class="op">(</span><span class="nam">g</span><span class="op">,</span> <span class="nam">year</span><span class="op">,</span> <span class="nam">g</span><span class="op">.</span><span class="nam">name</span><span class="op">,</span> <span class="nam">geo_level</span><span class="op">)</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t616" href="#t616">616</a></span><span class="t">        <span class="op">.</span><span class="nam">reset_index</span><span class="op">(</span><span class="nam">drop</span><span class="op">=</span><span class="key">True</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t617" href="#t617">617</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t618" href="#t618">618</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t619" href="#t619">619</a></span><span class="t">    <span class="nam">gdf</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="nam">df_with_geo</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t620" href="#t620">620</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t621" href="#t621">621</a></span><span class="t">    <span class="key">return</span> <span class="nam">gdf</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t622" href="#t622">622</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t623" href="#t623">623</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t624" href="#t624">624</a></span><span class="t"><span class="key">def</span> <span class="nam">download_detail</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t625" href="#t625">625</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t626" href="#t626">626</a></span><span class="t">    <span class="nam">year</span><span class="op">:</span> <span class="nam">int</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t627" href="#t627">627</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t628" href="#t628">628</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t629" href="#t629">629</a></span><span class="t">    <span class="nam">with_geometry</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">False</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t630" href="#t630">630</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t631" href="#t631">631</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="str">"VariableCache"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t632" href="#t632">632</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">:</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">InSpecType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t633" href="#t633">633</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Union</span><span class="op">[</span><span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t634" href="#t634">634</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t635" href="#t635">635</a></span><span class="t"><span class="str">    Deprecated version of :py:func:`~download`; use `download` instead.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t636" href="#t636">636</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t637" href="#t637">637</a></span><span class="t"><span class="str">    This function offers a subset of the current functionality of</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t638" href="#t638">638</a></span><span class="t"><span class="str">    :py:func:`~download` but under the old name.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t639" href="#t639">639</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t640" href="#t640">640</a></span><span class="t"><span class="str">    Back in the pre-history of `censusdis`, this function started life as a</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t641" href="#t641">641</a></span><span class="t"><span class="str">    way to download ACS detail tables. It evolved significantly since then and</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t642" href="#t642">642</a></span><span class="t"><span class="str">    does much more now. Hence, the name was changed.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t643" href="#t643">643</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t644" href="#t644">644</a></span><span class="t"><span class="str">    This function will disappear completely no later than version 1.0.0.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t645" href="#t645">645</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t646" href="#t646">646</a></span><span class="t">    <span class="nam">warnings</span><span class="op">.</span><span class="nam">warn</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t647" href="#t647">647</a></span><span class="t">        <span class="str">"censusdis.data.download_detail is deprecated. "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t648" href="#t648">648</a></span><span class="t">        <span class="str">"Please use censusdis.data.download instead."</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t649" href="#t649">649</a></span><span class="t">        <span class="nam">DeprecationWarning</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t650" href="#t650">650</a></span><span class="t">        <span class="num">2</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t651" href="#t651">651</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t652" href="#t652">652</a></span><span class="t">    <span class="key">return</span> <span class="nam">download</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t653" href="#t653">653</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t654" href="#t654">654</a></span><span class="t">        <span class="nam">year</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t655" href="#t655">655</a></span><span class="t">        <span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t656" href="#t656">656</a></span><span class="t">        <span class="nam">with_geometry</span><span class="op">=</span><span class="nam">with_geometry</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t657" href="#t657">657</a></span><span class="t">        <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t658" href="#t658">658</a></span><span class="t">        <span class="nam">variable_cache</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t659" href="#t659">659</a></span><span class="t">        <span class="op">**</span><span class="nam">kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t660" href="#t660">660</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t661" href="#t661">661</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t662" href="#t662">662</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t663" href="#t663">663</a></span><span class="t"><span class="key">def</span> <span class="nam">download</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t664" href="#t664">664</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t665" href="#t665">665</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t666" href="#t666">666</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t667" href="#t667">667</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t668" href="#t668">668</a></span><span class="t">    <span class="nam">group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t669" href="#t669">669</a></span><span class="t">    <span class="nam">leaves_of_group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t670" href="#t670">670</a></span><span class="t">    <span class="nam">set_to_nan</span><span class="op">:</span> <span class="nam">Union</span><span class="op">[</span><span class="nam">bool</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">int</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t671" href="#t671">671</a></span><span class="t">    <span class="nam">skip_annotations</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t672" href="#t672">672</a></span><span class="t">    <span class="nam">with_geometry</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">False</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t673" href="#t673">673</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t674" href="#t674">674</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="str">"VariableCache"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t675" href="#t675">675</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">:</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">InSpecType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t676" href="#t676">676</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Union</span><span class="op">[</span><span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t677" href="#t677">677</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t678" href="#t678">678</a></span><span class="t"><span class="str">    Download data from the US Census API.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t679" href="#t679">679</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t680" href="#t680">680</a></span><span class="t"><span class="str">    This is the main API for downloading US Census data with the</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t681" href="#t681">681</a></span><span class="t"><span class="str">    `censusdis` package. There are many examples of how to use</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t682" href="#t682">682</a></span><span class="t"><span class="str">    this in the demo notebooks provided with the package at</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t683" href="#t683">683</a></span><span class="t"><span class="str">    https://github.com/vengroff/censusdis/tree/main/notebooks.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t684" href="#t684">684</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t685" href="#t685">685</a></span><span class="t"><span class="str">    *A note on variables and groups*: there are multiple ways to specify the</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t686" href="#t686">686</a></span><span class="t"><span class="str">    variables you want to download, either individually in `download_variables`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t687" href="#t687">687</a></span><span class="t"><span class="str">    by one or more groups in `group`, and by the leaves of one or more groups</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t688" href="#t688">688</a></span><span class="t"><span class="str">    in `leaves_of_group`. Note that these three sources af variables are</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t689" href="#t689">689</a></span><span class="t"><span class="str">    deduplicated, so you will only get one column for a variable no matter</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t690" href="#t690">690</a></span><span class="t"><span class="str">    how many times it is specified.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t613" href="#t613">613</a></span><span class="t">    <span class="nam">shapefile_scope</span> <span class="op">=</span> <span class="nam">_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO</span><span class="op">[</span><span class="nam">geo_level</span><span class="op">]</span><span class="op">[</span><span class="num">0</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t614" href="#t614">614</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t615" href="#t615">615</a></span><span class="t">    <span class="key">if</span> <span class="nam">shapefile_scope</span> <span class="key">is</span> <span class="key">not</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t616" href="#t616">616</a></span><span class="t">        <span class="com"># The scope is the same across the board.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t617" href="#t617">617</a></span><span class="t">        <span class="nam">gdf</span> <span class="op">=</span> <span class="nam">_add_geography</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">year</span><span class="op">,</span> <span class="nam">shapefile_scope</span><span class="op">,</span> <span class="nam">geo_level</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t618" href="#t618">618</a></span><span class="t">        <span class="key">return</span> <span class="nam">gdf</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t619" href="#t619">619</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t620" href="#t620">620</a></span><span class="t">    <span class="com"># We have to group by different values of the shapefile</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t621" href="#t621">621</a></span><span class="t">    <span class="com"># scope from the appropriate column and add the right</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t622" href="#t622">622</a></span><span class="t">    <span class="com"># geography to each group.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t623" href="#t623">623</a></span><span class="t">    <span class="nam">shapefile_scope_column</span> <span class="op">=</span> <span class="nam">_GEO_QUERY_FROM_DATA_QUERY_INNER_GEO</span><span class="op">[</span><span class="nam">geo_level</span><span class="op">]</span><span class="op">[</span><span class="num">2</span><span class="op">]</span><span class="op">[</span><span class="num">0</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t624" href="#t624">624</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t625" href="#t625">625</a></span><span class="t">    <span class="nam">df_with_geo</span> <span class="op">=</span> <span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t626" href="#t626">626</a></span><span class="t">        <span class="nam">df_data</span><span class="op">.</span><span class="nam">groupby</span><span class="op">(</span><span class="nam">shapefile_scope_column</span><span class="op">,</span> <span class="nam">group_keys</span><span class="op">=</span><span class="key">False</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t627" href="#t627">627</a></span><span class="t">        <span class="op">.</span><span class="nam">apply</span><span class="op">(</span><span class="key">lambda</span> <span class="nam">g</span><span class="op">:</span> <span class="nam">_add_geography</span><span class="op">(</span><span class="nam">g</span><span class="op">,</span> <span class="nam">year</span><span class="op">,</span> <span class="nam">g</span><span class="op">.</span><span class="nam">name</span><span class="op">,</span> <span class="nam">geo_level</span><span class="op">)</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t628" href="#t628">628</a></span><span class="t">        <span class="op">.</span><span class="nam">reset_index</span><span class="op">(</span><span class="nam">drop</span><span class="op">=</span><span class="key">True</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t629" href="#t629">629</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t630" href="#t630">630</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t631" href="#t631">631</a></span><span class="t">    <span class="nam">gdf</span> <span class="op">=</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">(</span><span class="nam">df_with_geo</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t632" href="#t632">632</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t633" href="#t633">633</a></span><span class="t">    <span class="key">return</span> <span class="nam">gdf</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t634" href="#t634">634</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t635" href="#t635">635</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t636" href="#t636">636</a></span><span class="t"><span class="key">def</span> <span class="nam">download_detail</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t637" href="#t637">637</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t638" href="#t638">638</a></span><span class="t">    <span class="nam">year</span><span class="op">:</span> <span class="nam">int</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t639" href="#t639">639</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t640" href="#t640">640</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t641" href="#t641">641</a></span><span class="t">    <span class="nam">with_geometry</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">False</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t642" href="#t642">642</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t643" href="#t643">643</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="str">"VariableCache"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t644" href="#t644">644</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">:</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">InSpecType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t645" href="#t645">645</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Union</span><span class="op">[</span><span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t646" href="#t646">646</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t647" href="#t647">647</a></span><span class="t"><span class="str">    Deprecated version of :py:func:`~download`; use `download` instead.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t648" href="#t648">648</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t649" href="#t649">649</a></span><span class="t"><span class="str">    This function offers a subset of the current functionality of</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t650" href="#t650">650</a></span><span class="t"><span class="str">    :py:func:`~download` but under the old name.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t651" href="#t651">651</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t652" href="#t652">652</a></span><span class="t"><span class="str">    Back in the pre-history of `censusdis`, this function started life as a</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t653" href="#t653">653</a></span><span class="t"><span class="str">    way to download ACS detail tables. It evolved significantly since then and</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t654" href="#t654">654</a></span><span class="t"><span class="str">    does much more now. Hence, the name was changed.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t655" href="#t655">655</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t656" href="#t656">656</a></span><span class="t"><span class="str">    This function will disappear completely no later than version 1.0.0.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t657" href="#t657">657</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t658" href="#t658">658</a></span><span class="t">    <span class="nam">warnings</span><span class="op">.</span><span class="nam">warn</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t659" href="#t659">659</a></span><span class="t">        <span class="str">"censusdis.data.download_detail is deprecated. "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t660" href="#t660">660</a></span><span class="t">        <span class="str">"Please use censusdis.data.download instead."</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t661" href="#t661">661</a></span><span class="t">        <span class="nam">DeprecationWarning</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t662" href="#t662">662</a></span><span class="t">        <span class="num">2</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t663" href="#t663">663</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t664" href="#t664">664</a></span><span class="t">    <span class="key">return</span> <span class="nam">download</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t665" href="#t665">665</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t666" href="#t666">666</a></span><span class="t">        <span class="nam">year</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t667" href="#t667">667</a></span><span class="t">        <span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t668" href="#t668">668</a></span><span class="t">        <span class="nam">with_geometry</span><span class="op">=</span><span class="nam">with_geometry</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t669" href="#t669">669</a></span><span class="t">        <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t670" href="#t670">670</a></span><span class="t">        <span class="nam">variable_cache</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t671" href="#t671">671</a></span><span class="t">        <span class="op">**</span><span class="nam">kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t672" href="#t672">672</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t673" href="#t673">673</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t674" href="#t674">674</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t675" href="#t675">675</a></span><span class="t"><span class="key">def</span> <span class="nam">download</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t676" href="#t676">676</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t677" href="#t677">677</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t678" href="#t678">678</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t679" href="#t679">679</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t680" href="#t680">680</a></span><span class="t">    <span class="nam">group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t681" href="#t681">681</a></span><span class="t">    <span class="nam">leaves_of_group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t682" href="#t682">682</a></span><span class="t">    <span class="nam">set_to_nan</span><span class="op">:</span> <span class="nam">Union</span><span class="op">[</span><span class="nam">bool</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">int</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t683" href="#t683">683</a></span><span class="t">    <span class="nam">skip_annotations</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t684" href="#t684">684</a></span><span class="t">    <span class="nam">with_geometry</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">False</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t685" href="#t685">685</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t686" href="#t686">686</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="str">"VariableCache"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t687" href="#t687">687</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">:</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">InSpecType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t688" href="#t688">688</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Union</span><span class="op">[</span><span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t689" href="#t689">689</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t690" href="#t690">690</a></span><span class="t"><span class="str">    Download data from the US Census API.</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t691" href="#t691">691</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t692" href="#t692">692</a></span><span class="t"><span class="str">    *Specifying census geographies*: censusdis provides access to many</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t693" href="#t693">693</a></span><span class="t"><span class="str">    census datasets, each of which can be retrieved at a particular set of</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t694" href="#t694">694</a></span><span class="t"><span class="str">    geographic grains. To accomodate this, `download()` takes a set</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t695" href="#t695">695</a></span><span class="t"><span class="str">    of kwargs to define the geographic level of the returned data. You can check</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t696" href="#t696">696</a></span><span class="t"><span class="str">    which geographies are available for a particular dataset with the</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t697" href="#t697">697</a></span><span class="t"><span class="str">    `geographies()`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t698" href="#t698">698</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t699" href="#t699">699</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t700" href="#t700">700</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t701" href="#t701">701</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t702" href="#t702">702</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t703" href="#t703">703</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t704" href="#t704">704</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t705" href="#t705">705</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t706" href="#t706">706</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t707" href="#t707">707</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t708" href="#t708">708</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t709" href="#t709">709</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t710" href="#t710">710</a></span><span class="t"><span class="str">    group</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t711" href="#t711">711</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t712" href="#t712">712</a></span><span class="t"><span class="str">        whose variable values should be downloaded. These are in addition to</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t713" href="#t713">713</a></span><span class="t"><span class="str">        any specified in `download_variables`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t714" href="#t714">714</a></span><span class="t"><span class="str">    leaves_of_group</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t715" href="#t715">715</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t716" href="#t716">716</a></span><span class="t"><span class="str">        whose leaf variable values should be downloaded.These are in addition to</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t717" href="#t717">717</a></span><span class="t"><span class="str">        any specified in `download_variables` or `group`. See</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t718" href="#t718">718</a></span><span class="t"><span class="str">        :py:meth:`VariableCache.group_leaves` for more details on the semantics of</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t719" href="#t719">719</a></span><span class="t"><span class="str">        leaves vs. non-leaf group variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t720" href="#t720">720</a></span><span class="t"><span class="str">    set_to_nan</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t721" href="#t721">721</a></span><span class="t"><span class="str">        A list of values that should be set to NaN. Normally these are special</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t722" href="#t722">722</a></span><span class="t"><span class="str">        values that the U.S. Census API sometimes returns. If `True`, then all</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t723" href="#t723">723</a></span><span class="t"><span class="str">        values in :py:ref:`censusdis.values.ALL_SPECIAL_VALUES` will be replaced.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t724" href="#t724">724</a></span><span class="t"><span class="str">        If `False`, no replacements will be made.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t725" href="#t725">725</a></span><span class="t"><span class="str">    skip_annotations</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t726" href="#t726">726</a></span><span class="t"><span class="str">        If `True` try to filter out `group` or `leaves_of_group` variables that are</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t727" href="#t727">727</a></span><span class="t"><span class="str">        annotations rather than actual values. See :py:meth:`VariableCache.group_variables`</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t728" href="#t728">728</a></span><span class="t"><span class="str">        for more details. Variable names passed in `download_variables` are not</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t729" href="#t729">729</a></span><span class="t"><span class="str">        affected by this flag.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t730" href="#t730">730</a></span><span class="t"><span class="str">    with_geometry</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t731" href="#t731">731</a></span><span class="t"><span class="str">        If `True` a :py:class:`gpd.GeoDataFrame` will be returned and each row</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t732" href="#t732">732</a></span><span class="t"><span class="str">        will have a geometry that is a cartographic boundary suitable for platting</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t733" href="#t733">733</a></span><span class="t"><span class="str">        a map. See https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t734" href="#t734">734</a></span><span class="t"><span class="str">        for details of the shapefiles that will be downloaded on your behalf to</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t735" href="#t735">735</a></span><span class="t"><span class="str">        generate these boundaries.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t736" href="#t736">736</a></span><span class="t"><span class="str">    api_key</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t737" href="#t737">737</a></span><span class="t"><span class="str">        An optional API key. If you don't have or don't use a key, the number</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t738" href="#t738">738</a></span><span class="t"><span class="str">        of calls you can make will be limited to 500 per day.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t739" href="#t739">739</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t740" href="#t740">740</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t741" href="#t741">741</a></span><span class="t"><span class="str">    kwargs</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t742" href="#t742">742</a></span><span class="t"><span class="str">        A specification of the geometry that we want data for. For example,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t743" href="#t743">743</a></span><span class="t"><span class="str">        `state = "*", county = "*"` will download county-level data for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t744" href="#t744">744</a></span><span class="t"><span class="str">        the entire US.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t745" href="#t745">745</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t746" href="#t746">746</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t747" href="#t747">747</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t748" href="#t748">748</a></span><span class="t"><span class="str">        A :py:class:`~pd.DataFrame` containing the requested US Census data.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t749" href="#t749">749</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t750" href="#t750">750</a></span><span class="t">    <span class="key">if</span> <span class="nam">variable_cache</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t751" href="#t751">751</a></span><span class="t">        <span class="nam">variable_cache</span> <span class="op">=</span> <span class="nam">variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t752" href="#t752">752</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t753" href="#t753">753</a></span><span class="t">    <span class="com"># The side effect here is to prime the cache.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t754" href="#t754">754</a></span><span class="t">    <span class="nam">cgeo</span><span class="op">.</span><span class="nam">geo_path_snake_specs</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t755" href="#t755">755</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t756" href="#t756">756</a></span><span class="t">    <span class="key">if</span> <span class="nam">set_to_nan</span> <span class="key">is</span> <span class="key">True</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t757" href="#t757">757</a></span><span class="t">        <span class="nam">set_to_nan</span> <span class="op">=</span> <span class="nam">ALL_SPECIAL_VALUES</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t758" href="#t758">758</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t759" href="#t759">759</a></span><span class="t">    <span class="com"># In case they came to us in py format, as kwargs often do.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t760" href="#t760">760</a></span><span class="t">    <span class="nam">kwargs</span> <span class="op">=</span> <span class="op">{</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t761" href="#t761">761</a></span><span class="t">        <span class="nam">cgeo</span><span class="op">.</span><span class="nam">path_component_from_snake</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">k</span><span class="op">)</span><span class="op">:</span> <span class="nam">v</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t762" href="#t762">762</a></span><span class="t">        <span class="key">for</span> <span class="nam">k</span><span class="op">,</span> <span class="nam">v</span> <span class="key">in</span> <span class="nam">kwargs</span><span class="op">.</span><span class="nam">items</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t763" href="#t763">763</a></span><span class="t">    <span class="op">}</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t692" href="#t692">692</a></span><span class="t"><span class="str">    This is the main API for downloading US Census data with the</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t693" href="#t693">693</a></span><span class="t"><span class="str">    `censusdis` package. There are many examples of how to use</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t694" href="#t694">694</a></span><span class="t"><span class="str">    this in the demo notebooks provided with the package at</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t695" href="#t695">695</a></span><span class="t"><span class="str">    https://github.com/vengroff/censusdis/tree/main/notebooks.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t696" href="#t696">696</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t697" href="#t697">697</a></span><span class="t"><span class="str">    *A note on variables and groups*: there are multiple ways to specify the</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t698" href="#t698">698</a></span><span class="t"><span class="str">    variables you want to download, either individually in `download_variables`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t699" href="#t699">699</a></span><span class="t"><span class="str">    by one or more groups in `group`, and by the leaves of one or more groups</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t700" href="#t700">700</a></span><span class="t"><span class="str">    in `leaves_of_group`. Note that these three sources af variables are</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t701" href="#t701">701</a></span><span class="t"><span class="str">    deduplicated, so you will only get one column for a variable no matter</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t702" href="#t702">702</a></span><span class="t"><span class="str">    how many times it is specified.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t703" href="#t703">703</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t704" href="#t704">704</a></span><span class="t"><span class="str">    *Specifying census geographies*: censusdis provides access to many</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t705" href="#t705">705</a></span><span class="t"><span class="str">    census datasets, each of which can be retrieved at a particular set of</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t706" href="#t706">706</a></span><span class="t"><span class="str">    geographic grains. To accomodate this, `download()` takes a set</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t707" href="#t707">707</a></span><span class="t"><span class="str">    of kwargs to define the geographic level of the returned data. You can check</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t708" href="#t708">708</a></span><span class="t"><span class="str">    which geographies are available for a particular dataset with the</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t709" href="#t709">709</a></span><span class="t"><span class="str">    `geographies()`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t710" href="#t710">710</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t711" href="#t711">711</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t712" href="#t712">712</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t713" href="#t713">713</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t714" href="#t714">714</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t715" href="#t715">715</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t716" href="#t716">716</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t717" href="#t717">717</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t718" href="#t718">718</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t719" href="#t719">719</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t720" href="#t720">720</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t721" href="#t721">721</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t722" href="#t722">722</a></span><span class="t"><span class="str">    group</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t723" href="#t723">723</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t724" href="#t724">724</a></span><span class="t"><span class="str">        whose variable values should be downloaded. These are in addition to</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t725" href="#t725">725</a></span><span class="t"><span class="str">        any specified in `download_variables`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t726" href="#t726">726</a></span><span class="t"><span class="str">    leaves_of_group</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t727" href="#t727">727</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t728" href="#t728">728</a></span><span class="t"><span class="str">        whose leaf variable values should be downloaded.These are in addition to</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t729" href="#t729">729</a></span><span class="t"><span class="str">        any specified in `download_variables` or `group`. See</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t730" href="#t730">730</a></span><span class="t"><span class="str">        :py:meth:`VariableCache.group_leaves` for more details on the semantics of</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t731" href="#t731">731</a></span><span class="t"><span class="str">        leaves vs. non-leaf group variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t732" href="#t732">732</a></span><span class="t"><span class="str">    set_to_nan</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t733" href="#t733">733</a></span><span class="t"><span class="str">        A list of values that should be set to NaN. Normally these are special</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t734" href="#t734">734</a></span><span class="t"><span class="str">        values that the U.S. Census API sometimes returns. If `True`, then all</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t735" href="#t735">735</a></span><span class="t"><span class="str">        values in :py:ref:`censusdis.values.ALL_SPECIAL_VALUES` will be replaced.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t736" href="#t736">736</a></span><span class="t"><span class="str">        If `False`, no replacements will be made.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t737" href="#t737">737</a></span><span class="t"><span class="str">    skip_annotations</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t738" href="#t738">738</a></span><span class="t"><span class="str">        If `True` try to filter out `group` or `leaves_of_group` variables that are</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t739" href="#t739">739</a></span><span class="t"><span class="str">        annotations rather than actual values. See :py:meth:`VariableCache.group_variables`</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t740" href="#t740">740</a></span><span class="t"><span class="str">        for more details. Variable names passed in `download_variables` are not</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t741" href="#t741">741</a></span><span class="t"><span class="str">        affected by this flag.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t742" href="#t742">742</a></span><span class="t"><span class="str">    with_geometry</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t743" href="#t743">743</a></span><span class="t"><span class="str">        If `True` a :py:class:`gpd.GeoDataFrame` will be returned and each row</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t744" href="#t744">744</a></span><span class="t"><span class="str">        will have a geometry that is a cartographic boundary suitable for platting</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t745" href="#t745">745</a></span><span class="t"><span class="str">        a map. See https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t746" href="#t746">746</a></span><span class="t"><span class="str">        for details of the shapefiles that will be downloaded on your behalf to</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t747" href="#t747">747</a></span><span class="t"><span class="str">        generate these boundaries.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t748" href="#t748">748</a></span><span class="t"><span class="str">    api_key</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t749" href="#t749">749</a></span><span class="t"><span class="str">        An optional API key. If you don't have or don't use a key, the number</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t750" href="#t750">750</a></span><span class="t"><span class="str">        of calls you can make will be limited to 500 per day.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t751" href="#t751">751</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t752" href="#t752">752</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t753" href="#t753">753</a></span><span class="t"><span class="str">    kwargs</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t754" href="#t754">754</a></span><span class="t"><span class="str">        A specification of the geometry that we want data for. For example,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t755" href="#t755">755</a></span><span class="t"><span class="str">        `state = "*", county = "*"` will download county-level data for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t756" href="#t756">756</a></span><span class="t"><span class="str">        the entire US.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t757" href="#t757">757</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t758" href="#t758">758</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t759" href="#t759">759</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t760" href="#t760">760</a></span><span class="t"><span class="str">        A :py:class:`~pd.DataFrame` containing the requested US Census data.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t761" href="#t761">761</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t762" href="#t762">762</a></span><span class="t">    <span class="key">if</span> <span class="nam">variable_cache</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t763" href="#t763">763</a></span><span class="t">        <span class="nam">variable_cache</span> <span class="op">=</span> <span class="nam">variables</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t764" href="#t764">764</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t765" href="#t765">765</a></span><span class="t">    <span class="com"># Parse out the download variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t766" href="#t766">766</a></span><span class="t">    <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">_parse_download_variables</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t767" href="#t767">767</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t768" href="#t768">768</a></span><span class="t">        <span class="nam">vintage</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t769" href="#t769">769</a></span><span class="t">        <span class="nam">download_variables</span><span class="op">=</span><span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t770" href="#t770">770</a></span><span class="t">        <span class="nam">group</span><span class="op">=</span><span class="nam">group</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t771" href="#t771">771</a></span><span class="t">        <span class="nam">leaves_of_group</span><span class="op">=</span><span class="nam">leaves_of_group</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t772" href="#t772">772</a></span><span class="t">        <span class="nam">skip_annotations</span><span class="op">=</span><span class="nam">skip_annotations</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t773" href="#t773">773</a></span><span class="t">        <span class="nam">variable_cache</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t774" href="#t774">774</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t775" href="#t775">775</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t776" href="#t776">776</a></span><span class="t">    <span class="com"># Special case if we are trying to get too many fields.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t777" href="#t777">777</a></span><span class="t">    <span class="key">if</span> <span class="nam">len</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span> <span class="op">></span> <span class="nam">_MAX_VARIABLES_PER_DOWNLOAD</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t778" href="#t778">778</a></span><span class="t">        <span class="key">return</span> <span class="nam">_download_multiple</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t779" href="#t779">779</a></span><span class="t">            <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t780" href="#t780">780</a></span><span class="t">            <span class="nam">vintage</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t781" href="#t781">781</a></span><span class="t">            <span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t782" href="#t782">782</a></span><span class="t">            <span class="nam">key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t783" href="#t783">783</a></span><span class="t">            <span class="nam">census_variables</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t784" href="#t784">784</a></span><span class="t">            <span class="nam">with_geometry</span><span class="op">=</span><span class="nam">with_geometry</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t785" href="#t785">785</a></span><span class="t">            <span class="op">**</span><span class="nam">kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t786" href="#t786">786</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t765" href="#t765">765</a></span><span class="t">    <span class="com"># The side effect here is to prime the cache.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t766" href="#t766">766</a></span><span class="t">    <span class="nam">cgeo</span><span class="op">.</span><span class="nam">geo_path_snake_specs</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t767" href="#t767">767</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t768" href="#t768">768</a></span><span class="t">    <span class="key">if</span> <span class="nam">set_to_nan</span> <span class="key">is</span> <span class="key">True</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t769" href="#t769">769</a></span><span class="t">        <span class="nam">set_to_nan</span> <span class="op">=</span> <span class="nam">ALL_SPECIAL_VALUES</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t770" href="#t770">770</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t771" href="#t771">771</a></span><span class="t">    <span class="com"># In case they came to us in py format, as kwargs often do.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t772" href="#t772">772</a></span><span class="t">    <span class="nam">kwargs</span> <span class="op">=</span> <span class="op">{</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t773" href="#t773">773</a></span><span class="t">        <span class="nam">cgeo</span><span class="op">.</span><span class="nam">path_component_from_snake</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">k</span><span class="op">)</span><span class="op">:</span> <span class="nam">v</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t774" href="#t774">774</a></span><span class="t">        <span class="key">for</span> <span class="nam">k</span><span class="op">,</span> <span class="nam">v</span> <span class="key">in</span> <span class="nam">kwargs</span><span class="op">.</span><span class="nam">items</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t775" href="#t775">775</a></span><span class="t">    <span class="op">}</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t776" href="#t776">776</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t777" href="#t777">777</a></span><span class="t">    <span class="com"># Parse out the download variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t778" href="#t778">778</a></span><span class="t">    <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">_parse_download_variables</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t779" href="#t779">779</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t780" href="#t780">780</a></span><span class="t">        <span class="nam">vintage</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t781" href="#t781">781</a></span><span class="t">        <span class="nam">download_variables</span><span class="op">=</span><span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t782" href="#t782">782</a></span><span class="t">        <span class="nam">group</span><span class="op">=</span><span class="nam">group</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t783" href="#t783">783</a></span><span class="t">        <span class="nam">leaves_of_group</span><span class="op">=</span><span class="nam">leaves_of_group</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t784" href="#t784">784</a></span><span class="t">        <span class="nam">skip_annotations</span><span class="op">=</span><span class="nam">skip_annotations</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t785" href="#t785">785</a></span><span class="t">        <span class="nam">variable_cache</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t786" href="#t786">786</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t787" href="#t787">787</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t788" href="#t788">788</a></span><span class="t">    <span class="com"># Prefetch all the types before we load the data.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t789" href="#t789">789</a></span><span class="t">    <span class="com"># That way we fail fast if a field is not known.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t790" href="#t790">790</a></span><span class="t">    <span class="nam">_prefetch_variable_types</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">download_variables</span><span class="op">,</span> <span class="nam">variable_cache</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t791" href="#t791">791</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t792" href="#t792">792</a></span><span class="t">    <span class="com"># If we were given a list, join it together into</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t793" href="#t793">793</a></span><span class="t">    <span class="com"># a comma-separated string.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t794" href="#t794">794</a></span><span class="t">    <span class="nam">string_kwargs</span> <span class="op">=</span> <span class="op">{</span><span class="nam">k</span><span class="op">:</span> <span class="nam">_gf2s</span><span class="op">(</span><span class="nam">v</span><span class="op">)</span> <span class="key">for</span> <span class="nam">k</span><span class="op">,</span> <span class="nam">v</span> <span class="key">in</span> <span class="nam">kwargs</span><span class="op">.</span><span class="nam">items</span><span class="op">(</span><span class="op">)</span><span class="op">}</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t795" href="#t795">795</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t796" href="#t796">796</a></span><span class="t">    <span class="key">return</span> <span class="nam">_download_remote</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t797" href="#t797">797</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t798" href="#t798">798</a></span><span class="t">        <span class="nam">vintage</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t799" href="#t799">799</a></span><span class="t">        <span class="nam">download_variables</span><span class="op">=</span><span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t800" href="#t800">800</a></span><span class="t">        <span class="nam">set_to_nan</span><span class="op">=</span><span class="nam">set_to_nan</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t801" href="#t801">801</a></span><span class="t">        <span class="nam">with_geometry</span><span class="op">=</span><span class="nam">with_geometry</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t802" href="#t802">802</a></span><span class="t">        <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t803" href="#t803">803</a></span><span class="t">        <span class="nam">variable_cache</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t804" href="#t804">804</a></span><span class="t">        <span class="op">**</span><span class="nam">string_kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t805" href="#t805">805</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t806" href="#t806">806</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t788" href="#t788">788</a></span><span class="t">    <span class="com"># Special case if we are trying to get too many fields.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t789" href="#t789">789</a></span><span class="t">    <span class="key">if</span> <span class="nam">len</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span> <span class="op">></span> <span class="nam">_MAX_VARIABLES_PER_DOWNLOAD</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t790" href="#t790">790</a></span><span class="t">        <span class="key">return</span> <span class="nam">_download_multiple</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t791" href="#t791">791</a></span><span class="t">            <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t792" href="#t792">792</a></span><span class="t">            <span class="nam">vintage</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t793" href="#t793">793</a></span><span class="t">            <span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t794" href="#t794">794</a></span><span class="t">            <span class="nam">key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t795" href="#t795">795</a></span><span class="t">            <span class="nam">census_variables</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t796" href="#t796">796</a></span><span class="t">            <span class="nam">with_geometry</span><span class="op">=</span><span class="nam">with_geometry</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t797" href="#t797">797</a></span><span class="t">            <span class="op">**</span><span class="nam">kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t798" href="#t798">798</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t799" href="#t799">799</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t800" href="#t800">800</a></span><span class="t">    <span class="com"># Prefetch all the types before we load the data.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t801" href="#t801">801</a></span><span class="t">    <span class="com"># That way we fail fast if a field is not known.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t802" href="#t802">802</a></span><span class="t">    <span class="nam">_prefetch_variable_types</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">download_variables</span><span class="op">,</span> <span class="nam">variable_cache</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t803" href="#t803">803</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t804" href="#t804">804</a></span><span class="t">    <span class="com"># If we were given a list, join it together into</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t805" href="#t805">805</a></span><span class="t">    <span class="com"># a comma-separated string.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t806" href="#t806">806</a></span><span class="t">    <span class="nam">string_kwargs</span> <span class="op">=</span> <span class="op">{</span><span class="nam">k</span><span class="op">:</span> <span class="nam">_gf2s</span><span class="op">(</span><span class="nam">v</span><span class="op">)</span> <span class="key">for</span> <span class="nam">k</span><span class="op">,</span> <span class="nam">v</span> <span class="key">in</span> <span class="nam">kwargs</span><span class="op">.</span><span class="nam">items</span><span class="op">(</span><span class="op">)</span><span class="op">}</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t807" href="#t807">807</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t808" href="#t808">808</a></span><span class="t"><span class="key">def</span> <span class="nam">_download_remote</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t809" href="#t809">809</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t810" href="#t810">810</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t811" href="#t811">811</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t812" href="#t812">812</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t813" href="#t813">813</a></span><span class="t">    <span class="nam">set_to_nan</span><span class="op">:</span> <span class="nam">Union</span><span class="op">[</span><span class="nam">bool</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">float</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t814" href="#t814">814</a></span><span class="t">    <span class="nam">with_geometry</span><span class="op">:</span> <span class="nam">bool</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t815" href="#t815">815</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t816" href="#t816">816</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="str">"VariableCache"</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t817" href="#t817">817</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t818" href="#t818">818</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Union</span><span class="op">[</span><span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t819" href="#t819">819</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t820" href="#t820">820</a></span><span class="t"><span class="str">    Make the actual remote call to download the data.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t821" href="#t821">821</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t822" href="#t822">822</a></span><span class="t"><span class="str">    This is the final step after we have parsed out and</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t823" href="#t823">823</a></span><span class="t"><span class="str">    validated the variables and geometry.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t824" href="#t824">824</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t825" href="#t825">825</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t826" href="#t826">826</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t827" href="#t827">827</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t828" href="#t828">828</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t829" href="#t829">829</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t830" href="#t830">830</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t831" href="#t831">831</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t832" href="#t832">832</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t833" href="#t833">833</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t834" href="#t834">834</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t835" href="#t835">835</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t836" href="#t836">836</a></span><span class="t"><span class="str">    set_to_nan</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t837" href="#t837">837</a></span><span class="t"><span class="str">        A list of values that should be set to NaN. Normally these are special</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t838" href="#t838">838</a></span><span class="t"><span class="str">        values that the U.S. Census API sometimes returns. If `True`, then all</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t839" href="#t839">839</a></span><span class="t"><span class="str">        values in :py:ref:`censusdis.values.ALL_SPECIAL_VALUES` will be replaced.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t840" href="#t840">840</a></span><span class="t"><span class="str">        If `False`, no replacements will be made.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t841" href="#t841">841</a></span><span class="t"><span class="str">    with_geometry</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t842" href="#t842">842</a></span><span class="t"><span class="str">        If `True` a :py:class:`gpd.GeoDataFrame` will be returned and each row</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t843" href="#t843">843</a></span><span class="t"><span class="str">        will have a geometry that is a cartographic boundary suitable for platting</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t844" href="#t844">844</a></span><span class="t"><span class="str">        a map. See https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t845" href="#t845">845</a></span><span class="t"><span class="str">        for details of the shapefiles that will be downloaded on your behalf to</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t846" href="#t846">846</a></span><span class="t"><span class="str">        generate these boundaries.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t847" href="#t847">847</a></span><span class="t"><span class="str">    api_key</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t848" href="#t848">848</a></span><span class="t"><span class="str">        An optional API key. If you don't have or don't use a key, the number</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t849" href="#t849">849</a></span><span class="t"><span class="str">        of calls you can make will be limited.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t850" href="#t850">850</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t851" href="#t851">851</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t852" href="#t852">852</a></span><span class="t"><span class="str">    kwargs</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t853" href="#t853">853</a></span><span class="t"><span class="str">        A specification of the geometry that we want data for.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t854" href="#t854">854</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t855" href="#t855">855</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t856" href="#t856">856</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t857" href="#t857">857</a></span><span class="t"><span class="str">        The downloaded variables, with or without added geometry, as</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t858" href="#t858">858</a></span><span class="t"><span class="str">        either a `pd.DataFrame` or `gpd.GeoDataFrame`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t859" href="#t859">859</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t860" href="#t860">860</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t861" href="#t861">861</a></span><span class="t">    <span class="nam">url</span><span class="op">,</span> <span class="nam">params</span><span class="op">,</span> <span class="nam">bound_path</span> <span class="op">=</span> <span class="nam">census_table_url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t862" href="#t862">862</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">download_variables</span><span class="op">,</span> <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span> <span class="op">**</span><span class="nam">kwargs</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t863" href="#t863">863</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t864" href="#t864">864</a></span><span class="t">    <span class="nam">df_data</span> <span class="op">=</span> <span class="nam">data_from_url</span><span class="op">(</span><span class="nam">url</span><span class="op">,</span> <span class="nam">params</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t865" href="#t865">865</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t866" href="#t866">866</a></span><span class="t">    <span class="com"># Coerce the types based on metadata about the variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t867" href="#t867">867</a></span><span class="t">    <span class="nam">_coerce_downloaded_variable_types</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t868" href="#t868">868</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">download_variables</span><span class="op">,</span> <span class="nam">df_data</span><span class="op">,</span> <span class="nam">variable_cache</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t869" href="#t869">869</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t870" href="#t870">870</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t871" href="#t871">871</a></span><span class="t">    <span class="nam">download_variables_upper</span> <span class="op">=</span> <span class="op">[</span><span class="nam">dv</span><span class="op">.</span><span class="nam">upper</span><span class="op">(</span><span class="op">)</span> <span class="key">for</span> <span class="nam">dv</span> <span class="key">in</span> <span class="nam">download_variables</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t808" href="#t808">808</a></span><span class="t">    <span class="key">return</span> <span class="nam">_download_remote</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t809" href="#t809">809</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t810" href="#t810">810</a></span><span class="t">        <span class="nam">vintage</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t811" href="#t811">811</a></span><span class="t">        <span class="nam">download_variables</span><span class="op">=</span><span class="nam">download_variables</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t812" href="#t812">812</a></span><span class="t">        <span class="nam">set_to_nan</span><span class="op">=</span><span class="nam">set_to_nan</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t813" href="#t813">813</a></span><span class="t">        <span class="nam">with_geometry</span><span class="op">=</span><span class="nam">with_geometry</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t814" href="#t814">814</a></span><span class="t">        <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t815" href="#t815">815</a></span><span class="t">        <span class="nam">variable_cache</span><span class="op">=</span><span class="nam">variable_cache</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t816" href="#t816">816</a></span><span class="t">        <span class="op">**</span><span class="nam">string_kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t817" href="#t817">817</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t818" href="#t818">818</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t819" href="#t819">819</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t820" href="#t820">820</a></span><span class="t"><span class="key">def</span> <span class="nam">_download_remote</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t821" href="#t821">821</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t822" href="#t822">822</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t823" href="#t823">823</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t824" href="#t824">824</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t825" href="#t825">825</a></span><span class="t">    <span class="nam">set_to_nan</span><span class="op">:</span> <span class="nam">Union</span><span class="op">[</span><span class="nam">bool</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">float</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t826" href="#t826">826</a></span><span class="t">    <span class="nam">with_geometry</span><span class="op">:</span> <span class="nam">bool</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t827" href="#t827">827</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t828" href="#t828">828</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="str">"VariableCache"</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t829" href="#t829">829</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t830" href="#t830">830</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Union</span><span class="op">[</span><span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span> <span class="nam">gpd</span><span class="op">.</span><span class="nam">GeoDataFrame</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t831" href="#t831">831</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t832" href="#t832">832</a></span><span class="t"><span class="str">    Make the actual remote call to download the data.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t833" href="#t833">833</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t834" href="#t834">834</a></span><span class="t"><span class="str">    This is the final step after we have parsed out and</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t835" href="#t835">835</a></span><span class="t"><span class="str">    validated the variables and geometry.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t836" href="#t836">836</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t837" href="#t837">837</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t838" href="#t838">838</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t839" href="#t839">839</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t840" href="#t840">840</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t841" href="#t841">841</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t842" href="#t842">842</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t843" href="#t843">843</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t844" href="#t844">844</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t845" href="#t845">845</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t846" href="#t846">846</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t847" href="#t847">847</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t848" href="#t848">848</a></span><span class="t"><span class="str">    set_to_nan</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t849" href="#t849">849</a></span><span class="t"><span class="str">        A list of values that should be set to NaN. Normally these are special</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t850" href="#t850">850</a></span><span class="t"><span class="str">        values that the U.S. Census API sometimes returns. If `True`, then all</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t851" href="#t851">851</a></span><span class="t"><span class="str">        values in :py:ref:`censusdis.values.ALL_SPECIAL_VALUES` will be replaced.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t852" href="#t852">852</a></span><span class="t"><span class="str">        If `False`, no replacements will be made.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t853" href="#t853">853</a></span><span class="t"><span class="str">    with_geometry</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t854" href="#t854">854</a></span><span class="t"><span class="str">        If `True` a :py:class:`gpd.GeoDataFrame` will be returned and each row</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t855" href="#t855">855</a></span><span class="t"><span class="str">        will have a geometry that is a cartographic boundary suitable for platting</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t856" href="#t856">856</a></span><span class="t"><span class="str">        a map. See https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.2020.html</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t857" href="#t857">857</a></span><span class="t"><span class="str">        for details of the shapefiles that will be downloaded on your behalf to</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t858" href="#t858">858</a></span><span class="t"><span class="str">        generate these boundaries.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t859" href="#t859">859</a></span><span class="t"><span class="str">    api_key</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t860" href="#t860">860</a></span><span class="t"><span class="str">        An optional API key. If you don't have or don't use a key, the number</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t861" href="#t861">861</a></span><span class="t"><span class="str">        of calls you can make will be limited.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t862" href="#t862">862</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t863" href="#t863">863</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t864" href="#t864">864</a></span><span class="t"><span class="str">    kwargs</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t865" href="#t865">865</a></span><span class="t"><span class="str">        A specification of the geometry that we want data for.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t866" href="#t866">866</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t867" href="#t867">867</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t868" href="#t868">868</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t869" href="#t869">869</a></span><span class="t"><span class="str">        The downloaded variables, with or without added geometry, as</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t870" href="#t870">870</a></span><span class="t"><span class="str">        either a `pd.DataFrame` or `gpd.GeoDataFrame`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t871" href="#t871">871</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t872" href="#t872">872</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t873" href="#t873">873</a></span><span class="t">    <span class="com"># Put the geo fields (STATE, COUNTY, etc...) that came back up front.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t874" href="#t874">874</a></span><span class="t">    <span class="nam">df_data</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t875" href="#t875">875</a></span><span class="t">        <span class="op">[</span><span class="nam">col</span> <span class="key">for</span> <span class="nam">col</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">columns</span> <span class="key">if</span> <span class="nam">col</span> <span class="key">not</span> <span class="key">in</span> <span class="nam">download_variables_upper</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t876" href="#t876">876</a></span><span class="t">        <span class="op">+</span> <span class="nam">download_variables_upper</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t877" href="#t877">877</a></span><span class="t">    <span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t878" href="#t878">878</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t879" href="#t879">879</a></span><span class="t">    <span class="com"># NaN out as requested.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t880" href="#t880">880</a></span><span class="t">    <span class="key">if</span> <span class="nam">set_to_nan</span> <span class="key">is</span> <span class="key">True</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="mis show_mis"><span class="n"><a id="t881" href="#t881">881</a></span><span class="t">        <span class="nam">set_to_nan</span> <span class="op">=</span> <span class="nam">ALL_SPECIAL_VALUES</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t882" href="#t882">882</a></span><span class="t">    <span class="key">if</span> <span class="nam">set_to_nan</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t883" href="#t883">883</a></span><span class="t">        <span class="nam">df_data</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">replace</span><span class="op">(</span><span class="nam">list</span><span class="op">(</span><span class="nam">set_to_nan</span><span class="op">)</span><span class="op">,</span> <span class="nam">np</span><span class="op">.</span><span class="nam">nan</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t873" href="#t873">873</a></span><span class="t">    <span class="nam">url</span><span class="op">,</span> <span class="nam">params</span><span class="op">,</span> <span class="nam">bound_path</span> <span class="op">=</span> <span class="nam">census_table_url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t874" href="#t874">874</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">download_variables</span><span class="op">,</span> <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span><span class="op">,</span> <span class="op">**</span><span class="nam">kwargs</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t875" href="#t875">875</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t876" href="#t876">876</a></span><span class="t">    <span class="nam">df_data</span> <span class="op">=</span> <span class="nam">data_from_url</span><span class="op">(</span><span class="nam">url</span><span class="op">,</span> <span class="nam">params</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t877" href="#t877">877</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t878" href="#t878">878</a></span><span class="t">    <span class="com"># Coerce the types based on metadata about the variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t879" href="#t879">879</a></span><span class="t">    <span class="nam">_coerce_downloaded_variable_types</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t880" href="#t880">880</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">download_variables</span><span class="op">,</span> <span class="nam">df_data</span><span class="op">,</span> <span class="nam">variable_cache</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t881" href="#t881">881</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t882" href="#t882">882</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t883" href="#t883">883</a></span><span class="t">    <span class="nam">download_variables_upper</span> <span class="op">=</span> <span class="op">[</span><span class="nam">dv</span><span class="op">.</span><span class="nam">upper</span><span class="op">(</span><span class="op">)</span> <span class="key">for</span> <span class="nam">dv</span> <span class="key">in</span> <span class="nam">download_variables</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t884" href="#t884">884</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t885" href="#t885">885</a></span><span class="t">    <span class="key">if</span> <span class="nam">with_geometry</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t886" href="#t886">886</a></span><span class="t">        <span class="com"># We need to get the geometry and merge it in.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t887" href="#t887">887</a></span><span class="t">        <span class="nam">geo_level</span> <span class="op">=</span> <span class="nam">bound_path</span><span class="op">.</span><span class="nam">path_spec</span><span class="op">.</span><span class="nam">path</span><span class="op">[</span><span class="op">-</span><span class="num">1</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t888" href="#t888">888</a></span><span class="t">        <span class="nam">shapefile_scope</span> <span class="op">=</span> <span class="nam">bound_path</span><span class="op">.</span><span class="nam">bindings</span><span class="op">[</span><span class="nam">bound_path</span><span class="op">.</span><span class="nam">path_spec</span><span class="op">.</span><span class="nam">path</span><span class="op">[</span><span class="num">0</span><span class="op">]</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t889" href="#t889">889</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t890" href="#t890">890</a></span><span class="t">        <span class="nam">gdf_data</span> <span class="op">=</span> <span class="nam">_add_geography</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">shapefile_scope</span><span class="op">,</span> <span class="nam">geo_level</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t891" href="#t891">891</a></span><span class="t">        <span class="key">return</span> <span class="nam">gdf_data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t892" href="#t892">892</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t893" href="#t893">893</a></span><span class="t">    <span class="key">return</span> <span class="nam">df_data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t894" href="#t894">894</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t895" href="#t895">895</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t896" href="#t896">896</a></span><span class="t"><span class="key">def</span> <span class="nam">_coerce_downloaded_variable_types</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t897" href="#t897">897</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t898" href="#t898">898</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t899" href="#t899">899</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t900" href="#t900">900</a></span><span class="t">    <span class="nam">df_data</span><span class="op">:</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t901" href="#t901">901</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="str">"VariableCache"</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t902" href="#t902">902</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t903" href="#t903">903</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t904" href="#t904">904</a></span><span class="t"><span class="str">    Coerce the type of each returned variable (column) in a data frame.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t905" href="#t905">905</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t906" href="#t906">906</a></span><span class="t"><span class="str">    We look up the type in the metadata in `variable_cache`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t885" href="#t885">885</a></span><span class="t">    <span class="com"># Put the geo fields (STATE, COUNTY, etc...) that came back up front.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t886" href="#t886">886</a></span><span class="t">    <span class="nam">df_data</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t887" href="#t887">887</a></span><span class="t">        <span class="op">[</span><span class="nam">col</span> <span class="key">for</span> <span class="nam">col</span> <span class="key">in</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">columns</span> <span class="key">if</span> <span class="nam">col</span> <span class="key">not</span> <span class="key">in</span> <span class="nam">download_variables_upper</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t888" href="#t888">888</a></span><span class="t">        <span class="op">+</span> <span class="nam">download_variables_upper</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t889" href="#t889">889</a></span><span class="t">    <span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t890" href="#t890">890</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t891" href="#t891">891</a></span><span class="t">    <span class="com"># NaN out as requested.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t892" href="#t892">892</a></span><span class="t">    <span class="key">if</span> <span class="nam">set_to_nan</span> <span class="key">is</span> <span class="key">True</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="mis show_mis"><span class="n"><a id="t893" href="#t893">893</a></span><span class="t">        <span class="nam">set_to_nan</span> <span class="op">=</span> <span class="nam">ALL_SPECIAL_VALUES</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t894" href="#t894">894</a></span><span class="t">    <span class="key">if</span> <span class="nam">set_to_nan</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t895" href="#t895">895</a></span><span class="t">        <span class="nam">df_data</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">.</span><span class="nam">replace</span><span class="op">(</span><span class="nam">list</span><span class="op">(</span><span class="nam">set_to_nan</span><span class="op">)</span><span class="op">,</span> <span class="nam">np</span><span class="op">.</span><span class="nam">nan</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t896" href="#t896">896</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t897" href="#t897">897</a></span><span class="t">    <span class="key">if</span> <span class="nam">with_geometry</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t898" href="#t898">898</a></span><span class="t">        <span class="com"># We need to get the geometry and merge it in.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t899" href="#t899">899</a></span><span class="t">        <span class="nam">geo_level</span> <span class="op">=</span> <span class="nam">bound_path</span><span class="op">.</span><span class="nam">path_spec</span><span class="op">.</span><span class="nam">path</span><span class="op">[</span><span class="op">-</span><span class="num">1</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t900" href="#t900">900</a></span><span class="t">        <span class="nam">shapefile_scope</span> <span class="op">=</span> <span class="nam">bound_path</span><span class="op">.</span><span class="nam">bindings</span><span class="op">[</span><span class="nam">bound_path</span><span class="op">.</span><span class="nam">path_spec</span><span class="op">.</span><span class="nam">path</span><span class="op">[</span><span class="num">0</span><span class="op">]</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t901" href="#t901">901</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t902" href="#t902">902</a></span><span class="t">        <span class="nam">gdf_data</span> <span class="op">=</span> <span class="nam">_add_geography</span><span class="op">(</span><span class="nam">df_data</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">shapefile_scope</span><span class="op">,</span> <span class="nam">geo_level</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t903" href="#t903">903</a></span><span class="t">        <span class="key">return</span> <span class="nam">gdf_data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t904" href="#t904">904</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t905" href="#t905">905</a></span><span class="t">    <span class="key">return</span> <span class="nam">df_data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t906" href="#t906">906</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t907" href="#t907">907</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t908" href="#t908">908</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t909" href="#t909">909</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t910" href="#t910">910</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t911" href="#t911">911</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t912" href="#t912">912</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t913" href="#t913">913</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t914" href="#t914">914</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t915" href="#t915">915</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t916" href="#t916">916</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t917" href="#t917">917</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t918" href="#t918">918</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t919" href="#t919">919</a></span><span class="t"><span class="str">    df_data</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t920" href="#t920">920</a></span><span class="t"><span class="str">        The data that came back in JSON form from the census API.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t921" href="#t921">921</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t922" href="#t922">922</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t923" href="#t923">923</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t924" href="#t924">924</a></span><span class="t">    <span class="key">for</span> <span class="nam">variable</span> <span class="key">in</span> <span class="nam">download_variables</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t925" href="#t925">925</a></span><span class="t">        <span class="com"># predicateType does not exist in some older data sets like acs/acs3</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t926" href="#t926">926</a></span><span class="t">        <span class="com"># So in that case we just go with what we got in the JSON. But if we</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t927" href="#t927">927</a></span><span class="t">        <span class="com"># have it try to set the type.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t928" href="#t928">928</a></span><span class="t">        <span class="key">if</span> <span class="str">"predicateType"</span> <span class="key">in</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">get</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t929" href="#t929">929</a></span><span class="t">            <span class="nam">field_type</span> <span class="op">=</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">get</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">)</span><span class="op">[</span><span class="str">"predicateType"</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t930" href="#t930">930</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t931" href="#t931">931</a></span><span class="t">            <span class="key">if</span> <span class="nam">field_type</span> <span class="op">==</span> <span class="str">"int"</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t932" href="#t932">932</a></span><span class="t">                <span class="key">if</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">isnull</span><span class="op">(</span><span class="op">)</span><span class="op">.</span><span class="nam">any</span><span class="op">(</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t933" href="#t933">933</a></span><span class="t">                    <span class="com"># Some Census data sets put in null in int fields.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t934" href="#t934">934</a></span><span class="t">                    <span class="com"># We have to go with a float to make this a NaN.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t935" href="#t935">935</a></span><span class="t">                    <span class="com"># Int has no representation for NaN or None.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t936" href="#t936">936</a></span><span class="t">                    <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">float</span><span class="op">,</span> <span class="nam">errors</span><span class="op">=</span><span class="str">"ignore"</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t937" href="#t937">937</a></span><span class="t">                <span class="key">else</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t938" href="#t938">938</a></span><span class="t">                    <span class="key">try</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t939" href="#t939">939</a></span><span class="t">                        <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">int</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t940" href="#t940">940</a></span><span class="t">                    <span class="key">except</span> <span class="nam">ValueError</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t941" href="#t941">941</a></span><span class="t">                        <span class="com"># Sometimes census metadata says int, but they</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t942" href="#t942">942</a></span><span class="t">                        <span class="com"># put in float values anyway, so fall back on</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t943" href="#t943">943</a></span><span class="t">                        <span class="com"># trying to get them as floats.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t944" href="#t944">944</a></span><span class="t">                        <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t945" href="#t945">945</a></span><span class="t">                            <span class="nam">float</span><span class="op">,</span> <span class="nam">errors</span><span class="op">=</span><span class="str">"ignore"</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t946" href="#t946">946</a></span><span class="t">                        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t947" href="#t947">947</a></span><span class="t">                    <span class="key">except</span> <span class="nam">OverflowError</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t948" href="#t948">948</a></span><span class="t">                        <span class="com"># Some long IDs are actually better handled as strings.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t949" href="#t949">949</a></span><span class="t">                        <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">str</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t950" href="#t950">950</a></span><span class="t">            <span class="key">elif</span> <span class="nam">field_type</span> <span class="op">==</span> <span class="str">"float"</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t951" href="#t951">951</a></span><span class="t">                <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">float</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t952" href="#t952">952</a></span><span class="t">            <span class="key">elif</span> <span class="nam">field_type</span> <span class="op">==</span> <span class="str">"string"</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t953" href="#t953">953</a></span><span class="t">                <span class="key">pass</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t954" href="#t954">954</a></span><span class="t">            <span class="key">else</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t955" href="#t955">955</a></span><span class="t">                <span class="com"># Leave it as an object?</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t956" href="#t956">956</a></span><span class="t">                <span class="key">pass</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t957" href="#t957">957</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t958" href="#t958">958</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t959" href="#t959">959</a></span><span class="t"><span class="key">def</span> <span class="nam">_prefetch_variable_types</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t960" href="#t960">960</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t961" href="#t961">961</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t962" href="#t962">962</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t963" href="#t963">963</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="str">"VariableCache"</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t964" href="#t964">964</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t965" href="#t965">965</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t966" href="#t966">966</a></span><span class="t"><span class="str">    Prefetch the types of all the variables we are going to try to download.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t967" href="#t967">967</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t968" href="#t968">968</a></span><span class="t"><span class="str">    This enables us to fail fast and have a better error message about the</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t969" href="#t969">969</a></span><span class="t"><span class="str">    root cause of the issue than if we just blindly put in the variable names</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t970" href="#t970">970</a></span><span class="t"><span class="str">    in the census API request and wait for it to fail.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t971" href="#t971">971</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t972" href="#t972">972</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t973" href="#t973">973</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t974" href="#t974">974</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t975" href="#t975">975</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t976" href="#t976">976</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t977" href="#t977">977</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t978" href="#t978">978</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t979" href="#t979">979</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t980" href="#t980">980</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t981" href="#t981">981</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t982" href="#t982">982</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t983" href="#t983">983</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t984" href="#t984">984</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t985" href="#t985">985</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t986" href="#t986">986</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t987" href="#t987">987</a></span><span class="t">    <span class="key">for</span> <span class="nam">variable</span> <span class="key">in</span> <span class="nam">download_variables</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t988" href="#t988">988</a></span><span class="t">        <span class="key">try</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t989" href="#t989">989</a></span><span class="t">            <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">get</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t990" href="#t990">990</a></span><span class="t">        <span class="key">except</span> <span class="nam">Exception</span> <span class="key">as</span> <span class="nam">exc</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t991" href="#t991">991</a></span><span class="t">            <span class="nam">census_url</span> <span class="op">=</span> <span class="nam">CensusApiVariableSource</span><span class="op">.</span><span class="nam">url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t992" href="#t992">992</a></span><span class="t">                <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">,</span> <span class="nam">response_format</span><span class="op">=</span><span class="str">"html"</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t993" href="#t993">993</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t994" href="#t994">994</a></span><span class="t">            <span class="nam">census_variables_url</span> <span class="op">=</span> <span class="nam">CensusApiVariableSource</span><span class="op">.</span><span class="nam">variables_url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t995" href="#t995">995</a></span><span class="t">                <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">response_format</span><span class="op">=</span><span class="str">"html"</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t996" href="#t996">996</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t997" href="#t997">997</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t998" href="#t998">998</a></span><span class="t">            <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t999" href="#t999">999</a></span><span class="t">                <span class="str">f"Unable to get metadata on the variable {variable} from the "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1000" href="#t1000">1000</a></span><span class="t">                <span class="str">f"dataset {dataset} for year {vintage} from the census API. "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1001" href="#t1001">1001</a></span><span class="t">                <span class="str">f"Check the census URL for the variable ({census_url}) to ensure it exists. "</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1002" href="#t1002">1002</a></span><span class="t">                <span class="str">f"If not found, check {census_variables_url} for all variables in the dataset."</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1003" href="#t1003">1003</a></span><span class="t">            <span class="op">)</span> <span class="key">from</span> <span class="nam">exc</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1004" href="#t1004">1004</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1005" href="#t1005">1005</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1006" href="#t1006">1006</a></span><span class="t"><span class="key">def</span> <span class="nam">_parse_download_variables</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1007" href="#t1007">1007</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1008" href="#t1008">1008</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1009" href="#t1009">1009</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1010" href="#t1010">1010</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1011" href="#t1011">1011</a></span><span class="t">    <span class="nam">group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1012" href="#t1012">1012</a></span><span class="t">    <span class="nam">leaves_of_group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1013" href="#t1013">1013</a></span><span class="t">    <span class="nam">skip_annotations</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1014" href="#t1014">1014</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="str">"VariableCache"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1015" href="#t1015">1015</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1016" href="#t1016">1016</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1017" href="#t1017">1017</a></span><span class="t"><span class="str">    Parse out the full set of download variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1018" href="#t1018">1018</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1019" href="#t1019">1019</a></span><span class="t"><span class="str">    These may be encoded in `download_variables`, `group`, and/or `leaves_of_group`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1020" href="#t1020">1020</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1021" href="#t1021">1021</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1022" href="#t1022">1022</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1023" href="#t1023">1023</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1024" href="#t1024">1024</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1025" href="#t1025">1025</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1026" href="#t1026">1026</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1027" href="#t1027">1027</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1028" href="#t1028">1028</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1029" href="#t1029">1029</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1030" href="#t1030">1030</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1031" href="#t1031">1031</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1032" href="#t1032">1032</a></span><span class="t"><span class="str">    group</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1033" href="#t1033">1033</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1034" href="#t1034">1034</a></span><span class="t"><span class="str">        whose variable values should be downloaded. These are in addition to</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1035" href="#t1035">1035</a></span><span class="t"><span class="str">        any specified in `download_variables`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1036" href="#t1036">1036</a></span><span class="t"><span class="str">    leaves_of_group</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1037" href="#t1037">1037</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1038" href="#t1038">1038</a></span><span class="t"><span class="str">        whose leaf variable values should be downloaded.These are in addition to</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1039" href="#t1039">1039</a></span><span class="t"><span class="str">        any specified in `download_variables` or `group`. See</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1040" href="#t1040">1040</a></span><span class="t"><span class="str">        :py:meth:`VariableCache.group_leaves` for more details on the semantics of</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1041" href="#t1041">1041</a></span><span class="t"><span class="str">        leaves vs. non-leaf group variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1042" href="#t1042">1042</a></span><span class="t"><span class="str">    skip_annotations</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1043" href="#t1043">1043</a></span><span class="t"><span class="str">        If `True` try to filter out `group` or `leaves_of_group` variables that are</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1044" href="#t1044">1044</a></span><span class="t"><span class="str">        annotations rather than actual values. See :py:meth:`VariableCache.group_variables`</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1045" href="#t1045">1045</a></span><span class="t"><span class="str">        for more details. Variable names passed in `download_variables` are not</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1046" href="#t1046">1046</a></span><span class="t"><span class="str">        affected by this flag.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1047" href="#t1047">1047</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1048" href="#t1048">1048</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1049" href="#t1049">1049</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1050" href="#t1050">1050</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1051" href="#t1051">1051</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1052" href="#t1052">1052</a></span><span class="t"><span class="str">        The fully expanded list of variables to download.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1053" href="#t1053">1053</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1054" href="#t1054">1054</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1055" href="#t1055">1055</a></span><span class="t">    <span class="com"># Turn the variables we were given into a list if they are not already.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1056" href="#t1056">1056</a></span><span class="t">    <span class="key">if</span> <span class="nam">download_variables</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1057" href="#t1057">1057</a></span><span class="t">        <span class="nam">download_variables</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1058" href="#t1058">1058</a></span><span class="t">    <span class="key">elif</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">,</span> <span class="nam">str</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1059" href="#t1059">1059</a></span><span class="t">        <span class="nam">download_variables</span> <span class="op">=</span> <span class="op">[</span><span class="nam">download_variables</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1060" href="#t1060">1060</a></span><span class="t">    <span class="key">elif</span> <span class="key">not</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">,</span> <span class="nam">list</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="mis show_mis"><span class="n"><a id="t1061" href="#t1061">1061</a></span><span class="t">        <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">list</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1062" href="#t1062">1062</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1063" href="#t1063">1063</a></span><span class="t">    <span class="key">if</span> <span class="nam">group</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1064" href="#t1064">1064</a></span><span class="t">        <span class="nam">group</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1065" href="#t1065">1065</a></span><span class="t">    <span class="key">elif</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">group</span><span class="op">,</span> <span class="nam">str</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1066" href="#t1066">1066</a></span><span class="t">        <span class="nam">group</span> <span class="op">=</span> <span class="op">[</span><span class="nam">group</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1067" href="#t1067">1067</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1068" href="#t1068">1068</a></span><span class="t">    <span class="key">if</span> <span class="nam">leaves_of_group</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1069" href="#t1069">1069</a></span><span class="t">        <span class="nam">leaves_of_group</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1070" href="#t1070">1070</a></span><span class="t">    <span class="key">elif</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">leaves_of_group</span><span class="op">,</span> <span class="nam">str</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1071" href="#t1071">1071</a></span><span class="t">        <span class="nam">leaves_of_group</span> <span class="op">=</span> <span class="op">[</span><span class="nam">leaves_of_group</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1072" href="#t1072">1072</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1073" href="#t1073">1073</a></span><span class="t">    <span class="com"># Add group variables and leaves as appropriate.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1074" href="#t1074">1074</a></span><span class="t">    <span class="nam">group_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1075" href="#t1075">1075</a></span><span class="t">    <span class="key">for</span> <span class="nam">group_name</span> <span class="key">in</span> <span class="nam">group</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1076" href="#t1076">1076</a></span><span class="t">        <span class="nam">group_variables</span> <span class="op">=</span> <span class="nam">group_variables</span> <span class="op">+</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">group_variables</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1077" href="#t1077">1077</a></span><span class="t">            <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">group_name</span><span class="op">,</span> <span class="nam">skip_annotations</span><span class="op">=</span><span class="nam">skip_annotations</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1078" href="#t1078">1078</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1079" href="#t1079">1079</a></span><span class="t">    <span class="nam">group_leaf_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1080" href="#t1080">1080</a></span><span class="t">    <span class="key">for</span> <span class="nam">group_name</span> <span class="key">in</span> <span class="nam">leaves_of_group</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1081" href="#t1081">1081</a></span><span class="t">        <span class="nam">group_leaf_variables</span> <span class="op">=</span> <span class="nam">group_leaf_variables</span> <span class="op">+</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">group_leaves</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1082" href="#t1082">1082</a></span><span class="t">            <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">group_name</span><span class="op">,</span> <span class="nam">skip_annotations</span><span class="op">=</span><span class="nam">skip_annotations</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1083" href="#t1083">1083</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t908" href="#t908">908</a></span><span class="t"><span class="key">def</span> <span class="nam">_coerce_downloaded_variable_types</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t909" href="#t909">909</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t910" href="#t910">910</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t911" href="#t911">911</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t912" href="#t912">912</a></span><span class="t">    <span class="nam">df_data</span><span class="op">:</span> <span class="nam">pd</span><span class="op">.</span><span class="nam">DataFrame</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t913" href="#t913">913</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="str">"VariableCache"</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t914" href="#t914">914</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t915" href="#t915">915</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t916" href="#t916">916</a></span><span class="t"><span class="str">    Coerce the type of each returned variable (column) in a data frame.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t917" href="#t917">917</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t918" href="#t918">918</a></span><span class="t"><span class="str">    We look up the type in the metadata in `variable_cache`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t919" href="#t919">919</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t920" href="#t920">920</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t921" href="#t921">921</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t922" href="#t922">922</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t923" href="#t923">923</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t924" href="#t924">924</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t925" href="#t925">925</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t926" href="#t926">926</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t927" href="#t927">927</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t928" href="#t928">928</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t929" href="#t929">929</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t930" href="#t930">930</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t931" href="#t931">931</a></span><span class="t"><span class="str">    df_data</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t932" href="#t932">932</a></span><span class="t"><span class="str">        The data that came back in JSON form from the census API.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t933" href="#t933">933</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t934" href="#t934">934</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t935" href="#t935">935</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t936" href="#t936">936</a></span><span class="t">    <span class="key">for</span> <span class="nam">variable</span> <span class="key">in</span> <span class="nam">download_variables</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t937" href="#t937">937</a></span><span class="t">        <span class="com"># predicateType does not exist in some older data sets like acs/acs3</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t938" href="#t938">938</a></span><span class="t">        <span class="com"># So in that case we just go with what we got in the JSON. But if we</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t939" href="#t939">939</a></span><span class="t">        <span class="com"># have it try to set the type.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t940" href="#t940">940</a></span><span class="t">        <span class="key">if</span> <span class="str">"predicateType"</span> <span class="key">in</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">get</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t941" href="#t941">941</a></span><span class="t">            <span class="nam">field_type</span> <span class="op">=</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">get</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">)</span><span class="op">[</span><span class="str">"predicateType"</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t942" href="#t942">942</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t943" href="#t943">943</a></span><span class="t">            <span class="key">if</span> <span class="nam">field_type</span> <span class="op">==</span> <span class="str">"int"</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t944" href="#t944">944</a></span><span class="t">                <span class="key">if</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">isnull</span><span class="op">(</span><span class="op">)</span><span class="op">.</span><span class="nam">any</span><span class="op">(</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t945" href="#t945">945</a></span><span class="t">                    <span class="com"># Some Census data sets put in null in int fields.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t946" href="#t946">946</a></span><span class="t">                    <span class="com"># We have to go with a float to make this a NaN.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t947" href="#t947">947</a></span><span class="t">                    <span class="com"># Int has no representation for NaN or None.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t948" href="#t948">948</a></span><span class="t">                    <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">float</span><span class="op">,</span> <span class="nam">errors</span><span class="op">=</span><span class="str">"ignore"</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t949" href="#t949">949</a></span><span class="t">                <span class="key">else</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t950" href="#t950">950</a></span><span class="t">                    <span class="key">try</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t951" href="#t951">951</a></span><span class="t">                        <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">int</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t952" href="#t952">952</a></span><span class="t">                    <span class="key">except</span> <span class="nam">ValueError</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t953" href="#t953">953</a></span><span class="t">                        <span class="com"># Sometimes census metadata says int, but they</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t954" href="#t954">954</a></span><span class="t">                        <span class="com"># put in float values anyway, so fall back on</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t955" href="#t955">955</a></span><span class="t">                        <span class="com"># trying to get them as floats.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t956" href="#t956">956</a></span><span class="t">                        <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t957" href="#t957">957</a></span><span class="t">                            <span class="nam">float</span><span class="op">,</span> <span class="nam">errors</span><span class="op">=</span><span class="str">"ignore"</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t958" href="#t958">958</a></span><span class="t">                        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t959" href="#t959">959</a></span><span class="t">                    <span class="key">except</span> <span class="nam">OverflowError</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t960" href="#t960">960</a></span><span class="t">                        <span class="com"># Some long IDs are actually better handled as strings.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t961" href="#t961">961</a></span><span class="t">                        <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">str</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t962" href="#t962">962</a></span><span class="t">            <span class="key">elif</span> <span class="nam">field_type</span> <span class="op">==</span> <span class="str">"float"</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t963" href="#t963">963</a></span><span class="t">                <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span> <span class="op">=</span> <span class="nam">df_data</span><span class="op">[</span><span class="nam">variable</span><span class="op">]</span><span class="op">.</span><span class="nam">astype</span><span class="op">(</span><span class="nam">float</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t964" href="#t964">964</a></span><span class="t">            <span class="key">elif</span> <span class="nam">field_type</span> <span class="op">==</span> <span class="str">"string"</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t965" href="#t965">965</a></span><span class="t">                <span class="key">pass</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t966" href="#t966">966</a></span><span class="t">            <span class="key">else</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t967" href="#t967">967</a></span><span class="t">                <span class="com"># Leave it as an object?</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t968" href="#t968">968</a></span><span class="t">                <span class="key">pass</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t969" href="#t969">969</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t970" href="#t970">970</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t971" href="#t971">971</a></span><span class="t"><span class="key">def</span> <span class="nam">_prefetch_variable_types</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t972" href="#t972">972</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t973" href="#t973">973</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t974" href="#t974">974</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t975" href="#t975">975</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="str">"VariableCache"</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t976" href="#t976">976</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t977" href="#t977">977</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t978" href="#t978">978</a></span><span class="t"><span class="str">    Prefetch the types of all the variables we are going to try to download.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t979" href="#t979">979</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t980" href="#t980">980</a></span><span class="t"><span class="str">    This enables us to fail fast and have a better error message about the</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t981" href="#t981">981</a></span><span class="t"><span class="str">    root cause of the issue than if we just blindly put in the variable names</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t982" href="#t982">982</a></span><span class="t"><span class="str">    in the census API request and wait for it to fail.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t983" href="#t983">983</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t984" href="#t984">984</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t985" href="#t985">985</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t986" href="#t986">986</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t987" href="#t987">987</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t988" href="#t988">988</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t989" href="#t989">989</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t990" href="#t990">990</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t991" href="#t991">991</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t992" href="#t992">992</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t993" href="#t993">993</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t994" href="#t994">994</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t995" href="#t995">995</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t996" href="#t996">996</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t997" href="#t997">997</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t998" href="#t998">998</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t999" href="#t999">999</a></span><span class="t">    <span class="key">for</span> <span class="nam">variable</span> <span class="key">in</span> <span class="nam">download_variables</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1000" href="#t1000">1000</a></span><span class="t">        <span class="key">try</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1001" href="#t1001">1001</a></span><span class="t">            <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">get</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1002" href="#t1002">1002</a></span><span class="t">        <span class="key">except</span> <span class="nam">Exception</span> <span class="key">as</span> <span class="nam">exc</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1003" href="#t1003">1003</a></span><span class="t">            <span class="nam">census_url</span> <span class="op">=</span> <span class="nam">CensusApiVariableSource</span><span class="op">.</span><span class="nam">url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1004" href="#t1004">1004</a></span><span class="t">                <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">variable</span><span class="op">,</span> <span class="nam">response_format</span><span class="op">=</span><span class="str">"html"</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1005" href="#t1005">1005</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1006" href="#t1006">1006</a></span><span class="t">            <span class="nam">census_variables_url</span> <span class="op">=</span> <span class="nam">CensusApiVariableSource</span><span class="op">.</span><span class="nam">variables_url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1007" href="#t1007">1007</a></span><span class="t">                <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">response_format</span><span class="op">=</span><span class="str">"html"</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1008" href="#t1008">1008</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1009" href="#t1009">1009</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1010" href="#t1010">1010</a></span><span class="t">            <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1011" href="#t1011">1011</a></span><span class="t">                <span class="str">f"Unable to get metadata on the variable {variable} from the "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1012" href="#t1012">1012</a></span><span class="t">                <span class="str">f"dataset {dataset} for year {vintage} from the census API. "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1013" href="#t1013">1013</a></span><span class="t">                <span class="str">f"Check the census URL for the variable ({census_url}) to ensure it exists. "</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1014" href="#t1014">1014</a></span><span class="t">                <span class="str">f"If not found, check {census_variables_url} for all variables in the dataset."</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1015" href="#t1015">1015</a></span><span class="t">            <span class="op">)</span> <span class="key">from</span> <span class="nam">exc</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1016" href="#t1016">1016</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1017" href="#t1017">1017</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1018" href="#t1018">1018</a></span><span class="t"><span class="key">def</span> <span class="nam">_parse_download_variables</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1019" href="#t1019">1019</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1020" href="#t1020">1020</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1021" href="#t1021">1021</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1022" href="#t1022">1022</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1023" href="#t1023">1023</a></span><span class="t">    <span class="nam">group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1024" href="#t1024">1024</a></span><span class="t">    <span class="nam">leaves_of_group</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">Union</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1025" href="#t1025">1025</a></span><span class="t">    <span class="nam">skip_annotations</span><span class="op">:</span> <span class="nam">bool</span> <span class="op">=</span> <span class="key">True</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1026" href="#t1026">1026</a></span><span class="t">    <span class="nam">variable_cache</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="str">"VariableCache"</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1027" href="#t1027">1027</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1028" href="#t1028">1028</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1029" href="#t1029">1029</a></span><span class="t"><span class="str">    Parse out the full set of download variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1030" href="#t1030">1030</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1031" href="#t1031">1031</a></span><span class="t"><span class="str">    These may be encoded in `download_variables`, `group`, and/or `leaves_of_group`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1032" href="#t1032">1032</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1033" href="#t1033">1033</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1034" href="#t1034">1034</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1035" href="#t1035">1035</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1036" href="#t1036">1036</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1037" href="#t1037">1037</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1038" href="#t1038">1038</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1039" href="#t1039">1039</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1040" href="#t1040">1040</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1041" href="#t1041">1041</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1042" href="#t1042">1042</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1043" href="#t1043">1043</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1044" href="#t1044">1044</a></span><span class="t"><span class="str">    group</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1045" href="#t1045">1045</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1046" href="#t1046">1046</a></span><span class="t"><span class="str">        whose variable values should be downloaded. These are in addition to</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1047" href="#t1047">1047</a></span><span class="t"><span class="str">        any specified in `download_variables`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1048" href="#t1048">1048</a></span><span class="t"><span class="str">    leaves_of_group</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1049" href="#t1049">1049</a></span><span class="t"><span class="str">        One or more groups (as defined by the U.S. Census for the data set)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1050" href="#t1050">1050</a></span><span class="t"><span class="str">        whose leaf variable values should be downloaded.These are in addition to</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1051" href="#t1051">1051</a></span><span class="t"><span class="str">        any specified in `download_variables` or `group`. See</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1052" href="#t1052">1052</a></span><span class="t"><span class="str">        :py:meth:`VariableCache.group_leaves` for more details on the semantics of</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1053" href="#t1053">1053</a></span><span class="t"><span class="str">        leaves vs. non-leaf group variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1054" href="#t1054">1054</a></span><span class="t"><span class="str">    skip_annotations</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1055" href="#t1055">1055</a></span><span class="t"><span class="str">        If `True` try to filter out `group` or `leaves_of_group` variables that are</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1056" href="#t1056">1056</a></span><span class="t"><span class="str">        annotations rather than actual values. See :py:meth:`VariableCache.group_variables`</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1057" href="#t1057">1057</a></span><span class="t"><span class="str">        for more details. Variable names passed in `download_variables` are not</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1058" href="#t1058">1058</a></span><span class="t"><span class="str">        affected by this flag.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1059" href="#t1059">1059</a></span><span class="t"><span class="str">    variable_cache</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1060" href="#t1060">1060</a></span><span class="t"><span class="str">        A cache of metadata about variables.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1061" href="#t1061">1061</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1062" href="#t1062">1062</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1063" href="#t1063">1063</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1064" href="#t1064">1064</a></span><span class="t"><span class="str">        The fully expanded list of variables to download.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1065" href="#t1065">1065</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1066" href="#t1066">1066</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1067" href="#t1067">1067</a></span><span class="t">    <span class="com"># Turn the variables we were given into a list if they are not already.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1068" href="#t1068">1068</a></span><span class="t">    <span class="key">if</span> <span class="nam">download_variables</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1069" href="#t1069">1069</a></span><span class="t">        <span class="nam">download_variables</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1070" href="#t1070">1070</a></span><span class="t">    <span class="key">elif</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">,</span> <span class="nam">str</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1071" href="#t1071">1071</a></span><span class="t">        <span class="nam">download_variables</span> <span class="op">=</span> <span class="op">[</span><span class="nam">download_variables</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1072" href="#t1072">1072</a></span><span class="t">    <span class="key">elif</span> <span class="key">not</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">,</span> <span class="nam">list</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="mis show_mis"><span class="n"><a id="t1073" href="#t1073">1073</a></span><span class="t">        <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">list</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1074" href="#t1074">1074</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1075" href="#t1075">1075</a></span><span class="t">    <span class="key">if</span> <span class="nam">group</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1076" href="#t1076">1076</a></span><span class="t">        <span class="nam">group</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1077" href="#t1077">1077</a></span><span class="t">    <span class="key">elif</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">group</span><span class="op">,</span> <span class="nam">str</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1078" href="#t1078">1078</a></span><span class="t">        <span class="nam">group</span> <span class="op">=</span> <span class="op">[</span><span class="nam">group</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1079" href="#t1079">1079</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1080" href="#t1080">1080</a></span><span class="t">    <span class="key">if</span> <span class="nam">leaves_of_group</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1081" href="#t1081">1081</a></span><span class="t">        <span class="nam">leaves_of_group</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1082" href="#t1082">1082</a></span><span class="t">    <span class="key">elif</span> <span class="nam">isinstance</span><span class="op">(</span><span class="nam">leaves_of_group</span><span class="op">,</span> <span class="nam">str</span><span class="op">)</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1083" href="#t1083">1083</a></span><span class="t">        <span class="nam">leaves_of_group</span> <span class="op">=</span> <span class="op">[</span><span class="nam">leaves_of_group</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t1084" href="#t1084">1084</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1085" href="#t1085">1085</a></span><span class="t">    <span class="com"># Concatenate them all.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1086" href="#t1086">1086</a></span><span class="t">    <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">download_variables</span> <span class="op">+</span> <span class="nam">group_variables</span> <span class="op">+</span> <span class="nam">group_leaf_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1087" href="#t1087">1087</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1088" href="#t1088">1088</a></span><span class="t">    <span class="com"># Dedup and maintain order.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1089" href="#t1089">1089</a></span><span class="t">    <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">list</span><span class="op">(</span><span class="nam">dict</span><span class="op">.</span><span class="nam">fromkeys</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1090" href="#t1090">1090</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1091" href="#t1091">1091</a></span><span class="t">    <span class="key">return</span> <span class="nam">download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1092" href="#t1092">1092</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1093" href="#t1093">1093</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1094" href="#t1094">1094</a></span><span class="t"><span class="key">def</span> <span class="nam">census_table_url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1095" href="#t1095">1095</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1096" href="#t1096">1096</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1097" href="#t1097">1097</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1098" href="#t1098">1098</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1099" href="#t1099">1099</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1100" href="#t1100">1100</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">:</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">InSpecType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1101" href="#t1101">1101</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Tuple</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Mapping</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">str</span><span class="op">]</span><span class="op">,</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">BoundGeographyPath</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1102" href="#t1102">1102</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1103" href="#t1103">1103</a></span><span class="t"><span class="str">    Construct the URL to download data from the U.S. Census API.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1085" href="#t1085">1085</a></span><span class="t">    <span class="com"># Add group variables and leaves as appropriate.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1086" href="#t1086">1086</a></span><span class="t">    <span class="nam">group_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1087" href="#t1087">1087</a></span><span class="t">    <span class="key">for</span> <span class="nam">group_name</span> <span class="key">in</span> <span class="nam">group</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1088" href="#t1088">1088</a></span><span class="t">        <span class="nam">group_variables</span> <span class="op">=</span> <span class="nam">group_variables</span> <span class="op">+</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">group_variables</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1089" href="#t1089">1089</a></span><span class="t">            <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">group_name</span><span class="op">,</span> <span class="nam">skip_annotations</span><span class="op">=</span><span class="nam">skip_annotations</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1090" href="#t1090">1090</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1091" href="#t1091">1091</a></span><span class="t">    <span class="nam">group_leaf_variables</span><span class="op">:</span> <span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="op">[</span><span class="op">]</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1092" href="#t1092">1092</a></span><span class="t">    <span class="key">for</span> <span class="nam">group_name</span> <span class="key">in</span> <span class="nam">leaves_of_group</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1093" href="#t1093">1093</a></span><span class="t">        <span class="nam">group_leaf_variables</span> <span class="op">=</span> <span class="nam">group_leaf_variables</span> <span class="op">+</span> <span class="nam">variable_cache</span><span class="op">.</span><span class="nam">group_leaves</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1094" href="#t1094">1094</a></span><span class="t">            <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">group_name</span><span class="op">,</span> <span class="nam">skip_annotations</span><span class="op">=</span><span class="nam">skip_annotations</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1095" href="#t1095">1095</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1096" href="#t1096">1096</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1097" href="#t1097">1097</a></span><span class="t">    <span class="com"># Concatenate them all.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1098" href="#t1098">1098</a></span><span class="t">    <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">download_variables</span> <span class="op">+</span> <span class="nam">group_variables</span> <span class="op">+</span> <span class="nam">group_leaf_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1099" href="#t1099">1099</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1100" href="#t1100">1100</a></span><span class="t">    <span class="com"># Dedup and maintain order.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1101" href="#t1101">1101</a></span><span class="t">    <span class="nam">download_variables</span> <span class="op">=</span> <span class="nam">list</span><span class="op">(</span><span class="nam">dict</span><span class="op">.</span><span class="nam">fromkeys</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1102" href="#t1102">1102</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1103" href="#t1103">1103</a></span><span class="t">    <span class="key">return</span> <span class="nam">download_variables</span>&nbsp;</span><span class="r"></span></p>
     <p class="pln"><span class="n"><a id="t1104" href="#t1104">1104</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1105" href="#t1105">1105</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1106" href="#t1106">1106</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1107" href="#t1107">1107</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1108" href="#t1108">1108</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1109" href="#t1109">1109</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1110" href="#t1110">1110</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1111" href="#t1111">1111</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1112" href="#t1112">1112</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1113" href="#t1113">1113</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1114" href="#t1114">1114</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1115" href="#t1115">1115</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1116" href="#t1116">1116</a></span><span class="t"><span class="str">    api_key</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1117" href="#t1117">1117</a></span><span class="t"><span class="str">        An optional API key. If you don't have or don't use a key, the number</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1118" href="#t1118">1118</a></span><span class="t"><span class="str">        of calls you can make will be limited.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1119" href="#t1119">1119</a></span><span class="t"><span class="str">    kwargs</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1120" href="#t1120">1120</a></span><span class="t"><span class="str">        A specification of the geometry that we want data for.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1121" href="#t1121">1121</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1122" href="#t1122">1122</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1123" href="#t1123">1123</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1124" href="#t1124">1124</a></span><span class="t"><span class="str">        The URL, parameters and bound path.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1125" href="#t1125">1125</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1126" href="#t1126">1126</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1127" href="#t1127">1127</a></span><span class="t">    <span class="nam">bound_path</span> <span class="op">=</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">PathSpec</span><span class="op">.</span><span class="nam">partial_prefix_match</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="op">**</span><span class="nam">kwargs</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1128" href="#t1128">1128</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1129" href="#t1129">1129</a></span><span class="t">    <span class="key">if</span> <span class="nam">bound_path</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="mis show_mis"><span class="n"><a id="t1130" href="#t1130">1130</a></span><span class="t">        <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1131" href="#t1131">1131</a></span><span class="t">            <span class="str">f"Unable to match the geography specification {kwargs}.\n"</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1132" href="#t1132">1132</a></span><span class="t">            <span class="str">f"Supported geographies for dataset='{dataset}' in year={vintage} are:\n"</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1133" href="#t1133">1133</a></span><span class="t">            <span class="op">+</span> <span class="str">"\n"</span><span class="op">.</span><span class="nam">join</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1134" href="#t1134">1134</a></span><span class="t">                <span class="str">f"{path_spec}"</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1135" href="#t1135">1135</a></span><span class="t">                <span class="key">for</span> <span class="nam">path_spec</span> <span class="key">in</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">geo_path_snake_specs</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">)</span><span class="op">.</span><span class="nam">values</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1136" href="#t1136">1136</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1137" href="#t1137">1137</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1138" href="#t1138">1138</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1139" href="#t1139">1139</a></span><span class="t">    <span class="nam">query_spec</span> <span class="op">=</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">CensusGeographyQuerySpec</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1140" href="#t1140">1140</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">list</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span><span class="op">,</span> <span class="nam">bound_path</span><span class="op">,</span> <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1141" href="#t1141">1141</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1142" href="#t1142">1142</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1143" href="#t1143">1143</a></span><span class="t">    <span class="nam">url</span><span class="op">,</span> <span class="nam">params</span> <span class="op">=</span> <span class="nam">query_spec</span><span class="op">.</span><span class="nam">table_url</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1144" href="#t1144">1144</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1145" href="#t1145">1145</a></span><span class="t">    <span class="key">return</span> <span class="nam">url</span><span class="op">,</span> <span class="nam">params</span><span class="op">,</span> <span class="nam">bound_path</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1146" href="#t1146">1146</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1147" href="#t1147">1147</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1148" href="#t1148">1148</a></span><span class="t"><span class="key">def</span> <span class="nam">geographies</span><span class="op">(</span><span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">)</span> <span class="op">-></span> <span class="nam">List</span><span class="op">[</span><span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1149" href="#t1149">1149</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1150" href="#t1150">1150</a></span><span class="t"><span class="str">    What geographies are supported for a dataset and vintage?</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1151" href="#t1151">1151</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1152" href="#t1152">1152</a></span><span class="t"><span class="str">    This utility gives us a list of the different geography</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1153" href="#t1153">1153</a></span><span class="t"><span class="str">    keywords we can use in calls to :py:func:`download` with</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1154" href="#t1154">1154</a></span><span class="t"><span class="str">    for the given dataset and vintage.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1155" href="#t1155">1155</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1156" href="#t1156">1156</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1157" href="#t1157">1157</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1158" href="#t1158">1158</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1159" href="#t1159">1159</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1160" href="#t1160">1160</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1161" href="#t1161">1161</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1162" href="#t1162">1162</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1163" href="#t1163">1163</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1164" href="#t1164">1164</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1165" href="#t1165">1165</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1166" href="#t1166">1166</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1167" href="#t1167">1167</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1168" href="#t1168">1168</a></span><span class="t"><span class="str">        A list of lists of geography keywords. Each element</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1169" href="#t1169">1169</a></span><span class="t"><span class="str">        of the outer list is a list of keywords that can be</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1170" href="#t1170">1170</a></span><span class="t"><span class="str">        used together.</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1171" href="#t1171">1171</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
-    <p class="mis show_mis"><span class="n"><a id="t1172" href="#t1172">1172</a></span><span class="t">    <span class="key">return</span> <span class="nam">list</span><span class="op">(</span><span class="nam">cgeo</span><span class="op">.</span><span class="nam">geo_path_snake_specs</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">)</span><span class="op">.</span><span class="nam">values</span><span class="op">(</span><span class="op">)</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1173" href="#t1173">1173</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="pln"><span class="n"><a id="t1174" href="#t1174">1174</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
-    <p class="run"><span class="n"><a id="t1175" href="#t1175">1175</a></span><span class="t"><span class="nam">variables</span> <span class="op">=</span> <span class="nam">VariableCache</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1105" href="#t1105">1105</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1106" href="#t1106">1106</a></span><span class="t"><span class="key">def</span> <span class="nam">census_table_url</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1107" href="#t1107">1107</a></span><span class="t">    <span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1108" href="#t1108">1108</a></span><span class="t">    <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1109" href="#t1109">1109</a></span><span class="t">    <span class="nam">download_variables</span><span class="op">:</span> <span class="nam">Iterable</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1110" href="#t1110">1110</a></span><span class="t">    <span class="op">*</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1111" href="#t1111">1111</a></span><span class="t">    <span class="nam">api_key</span><span class="op">:</span> <span class="nam">Optional</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span> <span class="op">=</span> <span class="key">None</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1112" href="#t1112">1112</a></span><span class="t">    <span class="op">**</span><span class="nam">kwargs</span><span class="op">:</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">InSpecType</span><span class="op">,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1113" href="#t1113">1113</a></span><span class="t"><span class="op">)</span> <span class="op">-></span> <span class="nam">Tuple</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">Mapping</span><span class="op">[</span><span class="nam">str</span><span class="op">,</span> <span class="nam">str</span><span class="op">]</span><span class="op">,</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">BoundGeographyPath</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1114" href="#t1114">1114</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1115" href="#t1115">1115</a></span><span class="t"><span class="str">    Construct the URL to download data from the U.S. Census API.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1116" href="#t1116">1116</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1117" href="#t1117">1117</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1118" href="#t1118">1118</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1119" href="#t1119">1119</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1120" href="#t1120">1120</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1121" href="#t1121">1121</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1122" href="#t1122">1122</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1123" href="#t1123">1123</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1124" href="#t1124">1124</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1125" href="#t1125">1125</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1126" href="#t1126">1126</a></span><span class="t"><span class="str">    download_variables</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1127" href="#t1127">1127</a></span><span class="t"><span class="str">        The census variables to download, for example `["NAME", "B01001_001E"]`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1128" href="#t1128">1128</a></span><span class="t"><span class="str">    api_key</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1129" href="#t1129">1129</a></span><span class="t"><span class="str">        An optional API key. If you don't have or don't use a key, the number</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1130" href="#t1130">1130</a></span><span class="t"><span class="str">        of calls you can make will be limited.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1131" href="#t1131">1131</a></span><span class="t"><span class="str">    kwargs</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1132" href="#t1132">1132</a></span><span class="t"><span class="str">        A specification of the geometry that we want data for.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1133" href="#t1133">1133</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1134" href="#t1134">1134</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1135" href="#t1135">1135</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1136" href="#t1136">1136</a></span><span class="t"><span class="str">        The URL, parameters and bound path.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1137" href="#t1137">1137</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1138" href="#t1138">1138</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1139" href="#t1139">1139</a></span><span class="t">    <span class="nam">bound_path</span> <span class="op">=</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">PathSpec</span><span class="op">.</span><span class="nam">partial_prefix_match</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="op">**</span><span class="nam">kwargs</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1140" href="#t1140">1140</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1141" href="#t1141">1141</a></span><span class="t">    <span class="key">if</span> <span class="nam">bound_path</span> <span class="key">is</span> <span class="key">None</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="mis show_mis"><span class="n"><a id="t1142" href="#t1142">1142</a></span><span class="t">        <span class="key">raise</span> <span class="nam">CensusApiException</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1143" href="#t1143">1143</a></span><span class="t">            <span class="str">f"Unable to match the geography specification {kwargs}.\n"</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1144" href="#t1144">1144</a></span><span class="t">            <span class="str">f"Supported geographies for dataset='{dataset}' in year={vintage} are:\n"</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1145" href="#t1145">1145</a></span><span class="t">            <span class="op">+</span> <span class="str">"\n"</span><span class="op">.</span><span class="nam">join</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1146" href="#t1146">1146</a></span><span class="t">                <span class="str">f"{path_spec}"</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1147" href="#t1147">1147</a></span><span class="t">                <span class="key">for</span> <span class="nam">path_spec</span> <span class="key">in</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">geo_path_snake_specs</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">)</span><span class="op">.</span><span class="nam">values</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1148" href="#t1148">1148</a></span><span class="t">            <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1149" href="#t1149">1149</a></span><span class="t">        <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1150" href="#t1150">1150</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1151" href="#t1151">1151</a></span><span class="t">    <span class="nam">query_spec</span> <span class="op">=</span> <span class="nam">cgeo</span><span class="op">.</span><span class="nam">CensusGeographyQuerySpec</span><span class="op">(</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1152" href="#t1152">1152</a></span><span class="t">        <span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">,</span> <span class="nam">list</span><span class="op">(</span><span class="nam">download_variables</span><span class="op">)</span><span class="op">,</span> <span class="nam">bound_path</span><span class="op">,</span> <span class="nam">api_key</span><span class="op">=</span><span class="nam">api_key</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1153" href="#t1153">1153</a></span><span class="t">    <span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1154" href="#t1154">1154</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1155" href="#t1155">1155</a></span><span class="t">    <span class="nam">url</span><span class="op">,</span> <span class="nam">params</span> <span class="op">=</span> <span class="nam">query_spec</span><span class="op">.</span><span class="nam">table_url</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1156" href="#t1156">1156</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1157" href="#t1157">1157</a></span><span class="t">    <span class="key">return</span> <span class="nam">url</span><span class="op">,</span> <span class="nam">params</span><span class="op">,</span> <span class="nam">bound_path</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1158" href="#t1158">1158</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1159" href="#t1159">1159</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1160" href="#t1160">1160</a></span><span class="t"><span class="key">def</span> <span class="nam">geographies</span><span class="op">(</span><span class="nam">dataset</span><span class="op">:</span> <span class="nam">str</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">:</span> <span class="nam">VintageType</span><span class="op">)</span> <span class="op">-></span> <span class="nam">List</span><span class="op">[</span><span class="nam">List</span><span class="op">[</span><span class="nam">str</span><span class="op">]</span><span class="op">]</span><span class="op">:</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1161" href="#t1161">1161</a></span><span class="t">    <span class="str">"""</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1162" href="#t1162">1162</a></span><span class="t"><span class="str">    What geographies are supported for a dataset and vintage?</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1163" href="#t1163">1163</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1164" href="#t1164">1164</a></span><span class="t"><span class="str">    This utility gives us a list of the different geography</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1165" href="#t1165">1165</a></span><span class="t"><span class="str">    keywords we can use in calls to :py:func:`download` with</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1166" href="#t1166">1166</a></span><span class="t"><span class="str">    for the given dataset and vintage.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1167" href="#t1167">1167</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1168" href="#t1168">1168</a></span><span class="t"><span class="str">    Parameters</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1169" href="#t1169">1169</a></span><span class="t"><span class="str">    ----------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1170" href="#t1170">1170</a></span><span class="t"><span class="str">    dataset</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1171" href="#t1171">1171</a></span><span class="t"><span class="str">        The dataset to download from. For example `"acs/acs5"`,</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1172" href="#t1172">1172</a></span><span class="t"><span class="str">        `"dec/pl"`, or `"timeseries/poverty/saipe/schdist"`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1173" href="#t1173">1173</a></span><span class="t"><span class="str">    vintage</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1174" href="#t1174">1174</a></span><span class="t"><span class="str">        The vintage to download data for. For most data sets this is</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1175" href="#t1175">1175</a></span><span class="t"><span class="str">        an integer year, for example, `2020`. But for</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1176" href="#t1176">1176</a></span><span class="t"><span class="str">        a timeseries data set, pass the string `'timeseries'`.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1177" href="#t1177">1177</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1178" href="#t1178">1178</a></span><span class="t"><span class="str">    Returns</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1179" href="#t1179">1179</a></span><span class="t"><span class="str">    -------</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1180" href="#t1180">1180</a></span><span class="t"><span class="str">        A list of lists of geography keywords. Each element</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1181" href="#t1181">1181</a></span><span class="t"><span class="str">        of the outer list is a list of keywords that can be</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1182" href="#t1182">1182</a></span><span class="t"><span class="str">        used together.</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1183" href="#t1183">1183</a></span><span class="t"><span class="str">    """</span>&nbsp;</span><span class="r"></span></p>
+    <p class="mis show_mis"><span class="n"><a id="t1184" href="#t1184">1184</a></span><span class="t">    <span class="key">return</span> <span class="nam">list</span><span class="op">(</span><span class="nam">cgeo</span><span class="op">.</span><span class="nam">geo_path_snake_specs</span><span class="op">(</span><span class="nam">dataset</span><span class="op">,</span> <span class="nam">vintage</span><span class="op">)</span><span class="op">.</span><span class="nam">values</span><span class="op">(</span><span class="op">)</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1185" href="#t1185">1185</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="pln"><span class="n"><a id="t1186" href="#t1186">1186</a></span><span class="t">&nbsp;</span><span class="r"></span></p>
+    <p class="run"><span class="n"><a id="t1187" href="#t1187">1187</a></span><span class="t"><span class="nam">variables</span> <span class="op">=</span> <span class="nam">VariableCache</span><span class="op">(</span><span class="op">)</span>&nbsp;</span><span class="r"></span></p>
 </main>
 <footer>
     <div class="content">
@@ -1264,7 +1276,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_geography_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_5a366ca900b21d9c_geography_py.html b/reports/coverage/d_5a366ca900b21d9c_geography_py.html
index 586e65ff3..d90304a91 100644
--- a/reports/coverage/d_5a366ca900b21d9c_geography_py.html
+++ b/reports/coverage/d_5a366ca900b21d9c_geography_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b___init___py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -462,7 +462,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_1ef9b076751c2c3b___init___py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_5a366ca900b21d9c_maps_py.html b/reports/coverage/d_5a366ca900b21d9c_maps_py.html
index 5af6ed1e5..275be946e 100644
--- a/reports/coverage/d_5a366ca900b21d9c_maps_py.html
+++ b/reports/coverage/d_5a366ca900b21d9c_maps_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_c7b4b9502c408abc___init___py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -1185,7 +1185,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_c7b4b9502c408abc___init___py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_5a366ca900b21d9c_states_py.html b/reports/coverage/d_5a366ca900b21d9c_states_py.html
index 09d9aa62b..6f73fc34c 100644
--- a/reports/coverage/d_5a366ca900b21d9c_states_py.html
+++ b/reports/coverage/d_5a366ca900b21d9c_states_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_values_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -533,7 +533,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_values_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_5a366ca900b21d9c_values_py.html b/reports/coverage/d_5a366ca900b21d9c_values_py.html
index e3102e151..48707f977 100644
--- a/reports/coverage/d_5a366ca900b21d9c_values_py.html
+++ b/reports/coverage/d_5a366ca900b21d9c_values_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="index.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -155,7 +155,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="index.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_aea9b701da09b1b0___init___py.html b/reports/coverage/d_aea9b701da09b1b0___init___py.html
index a69ce90f5..2a07c5dad 100644
--- a/reports/coverage/d_aea9b701da09b1b0___init___py.html
+++ b/reports/coverage/d_aea9b701da09b1b0___init___py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_aea9b701da09b1b0_base_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -89,7 +89,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_aea9b701da09b1b0_base_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_aea9b701da09b1b0_base_py.html b/reports/coverage/d_aea9b701da09b1b0_base_py.html
index 8e180fa1a..04d2c7c5c 100644
--- a/reports/coverage/d_aea9b701da09b1b0_base_py.html
+++ b/reports/coverage/d_aea9b701da09b1b0_base_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_aea9b701da09b1b0_censusapi_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -270,7 +270,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_aea9b701da09b1b0_censusapi_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_aea9b701da09b1b0_censusapi_py.html b/reports/coverage/d_aea9b701da09b1b0_censusapi_py.html
index 4c8431896..cf918e355 100644
--- a/reports/coverage/d_aea9b701da09b1b0_censusapi_py.html
+++ b/reports/coverage/d_aea9b701da09b1b0_censusapi_py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_maps_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -270,7 +270,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_maps_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/d_c7b4b9502c408abc___init___py.html b/reports/coverage/d_c7b4b9502c408abc___init___py.html
index 259dac678..0e2ad4e3e 100644
--- a/reports/coverage/d_c7b4b9502c408abc___init___py.html
+++ b/reports/coverage/d_c7b4b9502c408abc___init___py.html
@@ -65,7 +65,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_states_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
         <aside class="hidden">
             <button type="button" class="button_next_chunk" data-shortcut="j"/>
@@ -89,7 +89,7 @@ <h2>
             <a id="nextFileLink" class="nav" href="d_5a366ca900b21d9c_states_py.html">&#xbb; next</a>
             &nbsp; &nbsp; &nbsp;
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </footer>
diff --git a/reports/coverage/index.html b/reports/coverage/index.html
index 0fe8a99df..04e739936 100644
--- a/reports/coverage/index.html
+++ b/reports/coverage/index.html
@@ -45,7 +45,7 @@ <h1>Coverage report:
         </form>
         <p class="text">
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
 </header>
@@ -70,10 +70,10 @@ <h1>Coverage report:
             </tr>
             <tr class="file">
                 <td class="name left"><a href="d_5a366ca900b21d9c_data_py.html">censusdis/data.py</a></td>
-                <td>214</td>
+                <td>218</td>
                 <td>7</td>
                 <td>0</td>
-                <td class="right" data-ratio="207 214">97%</td>
+                <td class="right" data-ratio="211 218">97%</td>
             </tr>
             <tr class="file">
                 <td class="name left"><a href="d_5a366ca900b21d9c_geography_py.html">censusdis/geography.py</a></td>
@@ -163,10 +163,10 @@ <h1>Coverage report:
         <tfoot>
             <tr class="total">
                 <td class="name left">Total</td>
-                <td>1061</td>
+                <td>1065</td>
                 <td>52</td>
                 <td>0</td>
-                <td class="right" data-ratio="1009 1061">95%</td>
+                <td class="right" data-ratio="1013 1065">95%</td>
             </tr>
         </tfoot>
     </table>
@@ -178,7 +178,7 @@ <h1>Coverage report:
     <div class="content">
         <p>
             <a class="nav" href="https://coverage.readthedocs.io">coverage.py v6.5.0</a>,
-            created at 2023-06-04 13:39 +0000
+            created at 2023-06-04 16:35 +0000
         </p>
     </div>
     <aside class="hidden">


Test patch:
diff --git a/reports/junit/tests-badge.svg b/reports/junit/tests-badge.svg
index a14e9a953..70715bfda 100644
--- a/reports/junit/tests-badge.svg
+++ b/reports/junit/tests-badge.svg
@@ -1,1 +1,1 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="60" height="20" role="img" aria-label="tests: 95"><title>tests: 95</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="60" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="23" height="20" fill="#4c1"/><rect width="60" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">tests</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">tests</text><text aria-hidden="true" x="475" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="130">95</text><text x="475" y="140" transform="scale(.1)" fill="#fff" textLength="130">95</text></g></svg>
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="60" height="20" role="img" aria-label="tests: 96"><title>tests: 96</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="60" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="23" height="20" fill="#4c1"/><rect width="60" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">tests</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">tests</text><text aria-hidden="true" x="475" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="130">96</text><text x="475" y="140" transform="scale(.1)" fill="#fff" textLength="130">96</text></g></svg>
\ No newline at end of file
diff --git a/tests/test_integration.py b/tests/test_integration.py
index d4adbc90e..a78b562d6 100644
--- a/tests/test_integration.py
+++ b/tests/test_integration.py
@@ -172,7 +172,7 @@ def test_download_with_geometry_county(self):
         )
 
     def test_download_with_geometry_state(self):
-        """Download at the county level with geometry."""
+        """Download at the state level with geometry."""
 
         gdf = ced.download(
             self._dataset,
@@ -190,6 +190,33 @@ def test_download_with_geometry_state(self):
             ["STATE", "NAME", "B19001_001E", "geometry"], list(gdf.columns)
         )
 
+    def test_download_with_geometry_multi_state(self):
+        """
+        Download at the tract level for multiplle states with geometry.
+
+        The point of this test is that tract-level shapefiles exist
+        only on a per-state basis, so inside the call we have to
+        recognize this and download and concatenate several shapefiles
+        before merging with our data.
+        """
+        gdf = ced.download(
+            self._dataset,
+            self._year,
+            ["NAME", self._name],
+            with_geometry=True,
+            state=["01", "02"],  # Two specific states.
+            tract="*",
+        )
+
+        self.assertIsInstance(gdf, geopandas.GeoDataFrame)
+
+        self.assertEqual((1614, 6), gdf.shape)
+
+        self.assertEqual(
+            ["STATE", "COUNTY", "TRACT", "NAME", "B19001_001E", "geometry"],
+            list(gdf.columns),
+        )
+
     def test_download_with_geometry_consolidated_city(self):
         """Download at the consolidated city level with geometry."""