Metadata-Version: 2.1
Name: census_backup
Version: 0.1.7
Summary: Backup utilities.
Author: Your Name
Author-email: you@example.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: censusdis (>=1.3.3,<2.0.0)
Requires-Dist: logargparser (>=0.1.1,<0.2.0)
Requires-Dist: usingversion (>=0.1.2,<0.2.0)
Description-Content-Type: text/markdown

# censusdis/backup

This project is a command-line utility for bulk downloads of 
U.S. Census data. Documentation and examples are a little sparse,
but we wanted to get this out so people who know what data sets
and vintages they are interested in can start using it. 

## Installation

```shell
pip install census_backup
```

## Usage Examples

### General help and overview

```shell
census-backup --help
```

### Download from a group across all available bulk geographies

This is the simplest way to use this tool. It will look for all
available geographies for the given dataset and vintage, then
download all variables in the specified group for every geography
it can.

```shell
census-backup -d acs/acs5 -v 2020 -g B02001 -o ~/tmp/backup  --log INFO
```

The required arguments are:

- `-d`: the data set
- `-v`: the vintage
- `-g`: the variable group

The option arguments are:

- `-o`: output directory. The default is the current working directory.
- `--log`: logging level. `INFO` is useful to see what is happening.

Logging will also help you see what geographies the script was not able
to download in bulk. The census API syntax does not allow all the bulk
downloads one might like to do.


### Download geometries that have `state` as a component

Sometimes we really only care about a specific set of geography
levels. This example will download at the [state], [state, county],
[state, county, tract] etc... levels.

```shell
census-backup -d acs/acs5 -v 2020 -g B02001 -G state -o ~/tmp/backup-states-and-below  --log INFO
```

### Download state aggregated data only

This will not get geographies within the state. It will only get data
aggregate at the state level. The `+` prefix says that `state` must be
the last component of the geography, so it will not match [state, county]
like it would without the `+`.

```shell
census-backup -d acs/acs5 -v 2020 -g B02001 -G +state -o ~/tmp/backup-states  --log INFO
```

### Download county aggregated data within states only

This will not get geographies within the state. It will only get data
aggregate at the state level.

```shell
census-backup -d acs/acs5 -v 2020 -g B02001 -G state +county -o ~/tmp/backup-state-counties --log INFO
```

## More Help

```shell
census-backup --help
```
