# autocensus
A Python package for collecting American Community Survey (ACS) data and associated geometry from the [Census API] in a [pandas] dataframe.
[Census API]: https://www.census.gov/developers
[pandas]: https://pandas.pydata.org
## Contents
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Geometry](#geometry)
- [Points](#points)
- [Polygons](#polygons)
- [Shapefile resolution](#shapefile-resolution)
- [Shapefile caching](#shapefile-caching)
## Installation
autocensus requires Python 3.9 or higher. Install as follows:
```sh
pip install autocensus
```
To run autocensus, you must specify a [Census API key] via either the `census_api_key` keyword argument (as shown in the example below) or by setting the environment variable `CENSUS_API_KEY`.
[Census API key]: https://api.census.gov/data/key_signup.html
## Quickstart
```python
from autocensus import Query
# Configure query
query = Query(
estimate=1,
years=[2017, 2018],
variables=['DP03_0025E', 'S0103_C01_104E'],
for_geo='county:033',
in_geo=['state:53'],
# Optional arg to add geometry: 'points', 'polygons', or None (default)
geometry='points',
# Fill in the following with your actual Census API key
census_api_key='Your Census API key'
)
# Run query and collect output in dataframe
dataframe = query.run()
```
Output:
| name | geo_id | geo_type | year | date | variable_code | variable_label | variable_concept | annotation | value | geometry |
| :---------------------- | :------------- | :------- | ---: | :--------- | :------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------ | ---------: | -----: | :-------- |
| King County, Washington | 0500000US53033 | county | 2017 | 2017-12-31 | DP03_0025E | Estimate!!COMMUTING TO WORK!!Mean travel time to work (minutes) | SELECTED ECONOMIC CHARACTERISTICS | | 30.0 | POINT (…) |
| King County, Washington | 0500000US53033 | county | 2018 | 2018-12-31 | DP03_0025E | Estimate!!COMMUTING TO WORK!!Workers 16 years and over!!Mean travel time to work (minutes) | SELECTED ECONOMIC CHARACTERISTICS | | 30.2 | POINT (…) |
| King County, Washington | 0500000US53033 | county | 2017 | 2017-12-31 | S0103_C01_104E | Total!!Estimate!!GROSS RENT!!Median gross rent (dollars) | POPULATION 65 YEARS AND OVER IN THE UNITED STATES | | 1555.0 | POINT (…) |
| King County, Washington | 0500000US53033 | county | 2018 | 2018-12-31 | S0103_C01_104E | Estimate!!Total!!Renter-occupied housing units!!GROSS RENT!!Median gross rent (dollars) | POPULATION 65 YEARS AND OVER IN THE UNITED STATES | | 1674.0 | POINT (…) |
## Geometry
autocensus supports point- and polygon-based geometry data for many years and geographies by way of the Census Bureau's [Gazetteer Files] and [Cartographic Boundary Files].
Here's how to add geometry to your data:
[Gazetteer Files]: https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html
[Cartographic Boundary Files]: https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-file.html
### Points
Point data from the Census Bureau's Gazetteer Files is generally available for years from 2012 on in the following geographies:
- Nation-level
- `urban area`
- `zip code tabulation area`
- `county`
- `congressional district`
- `metropolitan statistical area/micropolitan statistical area`
- `american indian area/alaska native area/hawaiian home land`
- State-level
- `county subdivision`
- `tract`
- `place`
- `state legislative district (upper chamber)`
- `state legislative district (lower chamber)`
Example:
```python
from autocensus import Query
query = Query(
estimate=5,
years=[2018],
variables=['DP03_0025E'],
for_geo=['county:033'],
in_geo=['state:53'],
geometry='points'
)
dataframe = query.run()
```
### Polygons
Polygon data from the Census Bureau's Cartographic Boundary Shapefiles is generally available for years from 2013 on in the following geographies:
- Nation-level
- `nation`
- `region`
- `division`
- `state`
- `urban area`
- `zip code tabulation area`
- `county`
- `congressional district`
- `metropolitan statistical area/micropolitan statistical area`
- `combined statistical area`
- `american indian area/alaska native area/hawaiian home land`
- `new england city and town area`
- State-level
- `alaska native regional corporation`
- `block group`
- `county subdivision`
- `tract`
- `place`
- `public use microdata area`
- `state legislative district (upper chamber)`
- `state legislative district (lower chamber)`
Example:
```python
from autocensus import Query
query = Query(
estimate=5,
years=[2018],
variables=['DP03_0025E'],
for_geo=['county:033'],
in_geo=['state:53'],
geometry='polygons'
)
dataframe = query.run()
```
#### Shapefile resolution
By default, autocensus will attempt to fetch almost all shapefiles at a resolution of 1 : 500,000 (`500k`). Some sources among the Cartographic Boundary Shapefiles are also available at the lower resolutions of 1 : 5,000,000 (`5m`) or 1 : 20,000,000 (`20m`). To attempt to download a shapefile at a specific resolution, pass a value to `Query`'s optional `resolution` parameter:
```python
from autocensus import Query
query = Query(
estimate=5,
years=[2018],
variables=['DP03_0025E'],
for_geo=['county:*'],
in_geo=['state:53'],
geometry='polygons',
# Optional arg to set a specific resolution: '500k', '5m', or '20m'
resolution='20m'
)
```
Setting a specific resolution is only supported for polygon-based geometry.
#### Shapefile caching
To improve performance across queries that include polygon-based geometry data, autocensus will cache Census shapefiles on disk by default. The cache directory location depends on your OS; you can look it up from `autocensus.constants.CACHE_DIRECTORY_PATH` like so:
```shell
python -c "import autocensus; print(autocensus.constants.CACHE_DIRECTORY_PATH)"
```
Sometimes it is useful to clear this cache directory, especially if you're running into persistent shapefile-related problems. You can clear the cache by manually deleting the cache directory or by executing the `autocensus.clear_cache` function:
```shell
python -c "import autocensus; autocensus.clear_cache()"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cmsetzer/autocensus",
"name": "autocensus",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "census, acs, api, data",
"author": "Christopher Setzer",
"author_email": "cmsetzer.github@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/61/b58ba8967e604454e318b013501ffb674f5498ebd6f24899e08205ab1511/autocensus-2.2.0.tar.gz",
"platform": null,
"description": "# autocensus\n\nA Python package for collecting American Community Survey (ACS) data and associated geometry from the [Census API] in a [pandas] dataframe.\n\n[Census API]: https://www.census.gov/developers\n[pandas]: https://pandas.pydata.org\n\n## Contents\n\n- [Installation](#installation)\n- [Quickstart](#quickstart)\n- [Geometry](#geometry)\n - [Points](#points)\n - [Polygons](#polygons)\n - [Shapefile resolution](#shapefile-resolution)\n - [Shapefile caching](#shapefile-caching)\n\n## Installation\n\nautocensus requires Python 3.9 or higher. Install as follows:\n\n```sh\npip install autocensus\n```\n\nTo run autocensus, you must specify a [Census API key] via either the `census_api_key` keyword argument (as shown in the example below) or by setting the environment variable `CENSUS_API_KEY`.\n\n[Census API key]: https://api.census.gov/data/key_signup.html\n\n## Quickstart\n\n```python\nfrom autocensus import Query\n\n# Configure query\nquery = Query(\n estimate=1,\n years=[2017, 2018],\n variables=['DP03_0025E', 'S0103_C01_104E'],\n for_geo='county:033',\n in_geo=['state:53'],\n # Optional arg to add geometry: 'points', 'polygons', or None (default)\n geometry='points',\n # Fill in the following with your actual Census API key\n census_api_key='Your Census API key'\n)\n\n# Run query and collect output in dataframe\ndataframe = query.run()\n```\n\nOutput:\n\n| name | geo_id | geo_type | year | date | variable_code | variable_label | variable_concept | annotation | value | geometry |\n| :---------------------- | :------------- | :------- | ---: | :--------- | :------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------ | ---------: | -----: | :-------- |\n| King County, Washington | 0500000US53033 | county | 2017 | 2017-12-31 | DP03_0025E | Estimate!!COMMUTING TO WORK!!Mean travel time to work (minutes) | SELECTED ECONOMIC CHARACTERISTICS | | 30.0 | POINT (\u2026) |\n| King County, Washington | 0500000US53033 | county | 2018 | 2018-12-31 | DP03_0025E | Estimate!!COMMUTING TO WORK!!Workers 16 years and over!!Mean travel time to work (minutes) | SELECTED ECONOMIC CHARACTERISTICS | | 30.2 | POINT (\u2026) |\n| King County, Washington | 0500000US53033 | county | 2017 | 2017-12-31 | S0103_C01_104E | Total!!Estimate!!GROSS RENT!!Median gross rent (dollars) | POPULATION 65 YEARS AND OVER IN THE UNITED STATES | | 1555.0 | POINT (\u2026) |\n| King County, Washington | 0500000US53033 | county | 2018 | 2018-12-31 | S0103_C01_104E | Estimate!!Total!!Renter-occupied housing units!!GROSS RENT!!Median gross rent (dollars) | POPULATION 65 YEARS AND OVER IN THE UNITED STATES | | 1674.0 | POINT (\u2026) |\n\n## Geometry\n\nautocensus supports point- and polygon-based geometry data for many years and geographies by way of the Census Bureau's [Gazetteer Files] and [Cartographic Boundary Files].\n\nHere's how to add geometry to your data:\n\n[Gazetteer Files]: https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html\n[Cartographic Boundary Files]: https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-file.html\n\n### Points\n\nPoint data from the Census Bureau's Gazetteer Files is generally available for years from 2012 on in the following geographies:\n\n- Nation-level\n - `urban area`\n - `zip code tabulation area`\n - `county`\n - `congressional district`\n - `metropolitan statistical area/micropolitan statistical area`\n - `american indian area/alaska native area/hawaiian home land`\n- State-level\n - `county subdivision`\n - `tract`\n - `place`\n - `state legislative district (upper chamber)`\n - `state legislative district (lower chamber)`\n\nExample:\n\n```python\nfrom autocensus import Query\n\nquery = Query(\n estimate=5,\n years=[2018],\n variables=['DP03_0025E'],\n for_geo=['county:033'],\n in_geo=['state:53'],\n geometry='points'\n)\ndataframe = query.run()\n```\n\n### Polygons\n\nPolygon data from the Census Bureau's Cartographic Boundary Shapefiles is generally available for years from 2013 on in the following geographies:\n\n- Nation-level\n - `nation`\n - `region`\n - `division`\n - `state`\n - `urban area`\n - `zip code tabulation area`\n - `county`\n - `congressional district`\n - `metropolitan statistical area/micropolitan statistical area`\n - `combined statistical area`\n - `american indian area/alaska native area/hawaiian home land`\n - `new england city and town area`\n- State-level\n - `alaska native regional corporation`\n - `block group`\n - `county subdivision`\n - `tract`\n - `place`\n - `public use microdata area`\n - `state legislative district (upper chamber)`\n - `state legislative district (lower chamber)`\n\nExample:\n\n```python\nfrom autocensus import Query\n\nquery = Query(\n estimate=5,\n years=[2018],\n variables=['DP03_0025E'],\n for_geo=['county:033'],\n in_geo=['state:53'],\n geometry='polygons'\n)\ndataframe = query.run()\n```\n\n#### Shapefile resolution\n\nBy default, autocensus will attempt to fetch almost all shapefiles at a resolution of 1 : 500,000 (`500k`). Some sources among the Cartographic Boundary Shapefiles are also available at the lower resolutions of 1 : 5,000,000 (`5m`) or 1 : 20,000,000 (`20m`). To attempt to download a shapefile at a specific resolution, pass a value to `Query`'s optional `resolution` parameter:\n\n```python\nfrom autocensus import Query\n\nquery = Query(\n estimate=5,\n years=[2018],\n variables=['DP03_0025E'],\n for_geo=['county:*'],\n in_geo=['state:53'],\n geometry='polygons',\n # Optional arg to set a specific resolution: '500k', '5m', or '20m'\n resolution='20m'\n)\n```\n\nSetting a specific resolution is only supported for polygon-based geometry.\n\n#### Shapefile caching\n\nTo improve performance across queries that include polygon-based geometry data, autocensus will cache Census shapefiles on disk by default. The cache directory location depends on your OS; you can look it up from `autocensus.constants.CACHE_DIRECTORY_PATH` like so:\n\n```shell\npython -c \"import autocensus; print(autocensus.constants.CACHE_DIRECTORY_PATH)\"\n```\n\nSometimes it is useful to clear this cache directory, especially if you're running into persistent shapefile-related problems. You can clear the cache by manually deleting the cache directory or by executing the `autocensus.clear_cache` function:\n\n```shell\npython -c \"import autocensus; autocensus.clear_cache()\"\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool for collecting ACS and geospatial data from the Census API",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/cmsetzer/autocensus"
},
"split_keywords": [
"census",
" acs",
" api",
" data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "989858a98c5a77409232f6391679ae2257ba9641f8a1320c213a71928cef7677",
"md5": "382df47dac4b2586594b8cf7782c9049",
"sha256": "f485184f524ba2b528964b6d04eeb8c87c1210160fde59dcac4173ee1b85ca98"
},
"downloads": -1,
"filename": "autocensus-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "382df47dac4b2586594b8cf7782c9049",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 21221,
"upload_time": "2024-08-02T20:45:58",
"upload_time_iso_8601": "2024-08-02T20:45:58.561489Z",
"url": "https://files.pythonhosted.org/packages/98/98/58a98c5a77409232f6391679ae2257ba9641f8a1320c213a71928cef7677/autocensus-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc61b58ba8967e604454e318b013501ffb674f5498ebd6f24899e08205ab1511",
"md5": "8faaaa0e830b6d2fddb159b0374b5298",
"sha256": "72013e495778bc10bfb787ccd97541341aa4b041ac1265670753a60a8ab8ae6d"
},
"downloads": -1,
"filename": "autocensus-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8faaaa0e830b6d2fddb159b0374b5298",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 17266,
"upload_time": "2024-08-02T20:45:59",
"upload_time_iso_8601": "2024-08-02T20:45:59.887205Z",
"url": "https://files.pythonhosted.org/packages/fc/61/b58ba8967e604454e318b013501ffb674f5498ebd6f24899e08205ab1511/autocensus-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-02 20:45:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cmsetzer",
"github_project": "autocensus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "autocensus"
}
JSON
