| Name | autocensus JSON |
| Version |
2.2.1
JSON |
| download |
| home_page | None |
| Summary | A tool for collecting ACS and geospatial data from the Census API |
| upload_time | 2025-02-12 22:12:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.10 |
| license | None |
| keywords |
census
acs
api
data
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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": null,
"name": "autocensus",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "census, acs, api, data",
"author": null,
"author_email": "Christopher Setzer <cmsetzer.github@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/76/17/18d801109e65bee6fa4778ccf71c5689681a50e056cfbaeaff93eeb69193/autocensus-2.2.1.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": null,
"summary": "A tool for collecting ACS and geospatial data from the Census API",
"version": "2.2.1",
"project_urls": {
"Repository": "https://github.com/cmsetzer/autocensus"
},
"split_keywords": [
"census",
" acs",
" api",
" data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4cff9dc906ce091e9fb8422a1742d07f60b9a46b76d1fdc582b3ac381b4807d6",
"md5": "d32f9ca7229caf6820ece35a0a9bf9a1",
"sha256": "34fe640e9b47ee48813374b3c2e22f6a21a37aec198332ff2bc20ac785d931ec"
},
"downloads": -1,
"filename": "autocensus-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d32f9ca7229caf6820ece35a0a9bf9a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 17213,
"upload_time": "2025-02-12T22:12:10",
"upload_time_iso_8601": "2025-02-12T22:12:10.214727Z",
"url": "https://files.pythonhosted.org/packages/4c/ff/9dc906ce091e9fb8422a1742d07f60b9a46b76d1fdc582b3ac381b4807d6/autocensus-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "761718d801109e65bee6fa4778ccf71c5689681a50e056cfbaeaff93eeb69193",
"md5": "348e7c10527f97bda6055c95c8c39af9",
"sha256": "7b291cc71c33aba8d60ffe4cda99627a8cdecb900d68ed6e564069227118993b"
},
"downloads": -1,
"filename": "autocensus-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "348e7c10527f97bda6055c95c8c39af9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 17778,
"upload_time": "2025-02-12T22:12:12",
"upload_time_iso_8601": "2025-02-12T22:12:12.100670Z",
"url": "https://files.pythonhosted.org/packages/76/17/18d801109e65bee6fa4778ccf71c5689681a50e056cfbaeaff93eeb69193/autocensus-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 22:12:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cmsetzer",
"github_project": "autocensus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "autocensus"
}
