Census Geocode
--------------
Census Geocode is a light weight Python wrapper for the US Census [Geocoder API](http://geocoding.geo.census.gov/geocoder/), compatible with Python 3. It comes packaged with a simple command line tool for geocoding an address to a longitude and latitude, or a batch file into a parsed address and coordinates.
It's strongly recommended to review the [Census Geocoder docs](https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/census-geocoder.html) before using this module.
Basic example:
```python
import censusgeocode as cg
cg.coordinates(x=-76, y=41)
cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')
cg.address('1600 Pennsylvania Avenue', city='Washington', state='DC', zip='20006')
cg.addressbatch('data/addresses.csv')
```
Use the returntype keyword to specify 'locations' or 'geographies'. 'Locations' yields structured information about the address, and 'geographies' yields information about the Census geographies. Geographies is the default.
```python
cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC', returntype='locations')
```
Queries return a CensusResult object, which is basically a Python list with an extra 'input' property, which the Census returns to tell you how they interpreted your request.
```python
>>> result = cg.coordinates(x=-76, y=41)
>>> result.input
{
u'vintage': {
u'vintageName': u'Current_Current',
u'id': u'4',
u'vintageDescription': u'Current Vintage - Current Benchmark',
u'isDefault': True
},
u'benchmark': {
u'benchmarkName': u'Public_AR_Current',
u'id': u'4',
u'isDefault': False,
u'benchmarkDescription': u'Public Address Ranges - Current Benchmark'
},
u'location': {
u'y': 41.0,
u'x': -76.0
}
}
>>> result
[{
'2010 Census Blocks': [{
'AREALAND': 1409023,
'AREAWATER': 0,
'BASENAME': '1045',
'BLKGRP': '1',
'BLOCK': '1045',
'CENTLAT': '+40.9957436',
'CENTLON': '-076.0089338',
'COUNTY': '079',
'FUNCSTAT': 'S',
'GEOID': '420792166001045',
'INTPTLAT': '+40.9957436',
'INTPTLON': '-076.0089338',
'LSADC': 'BK',
'LWBLKTYP': 'L',
'MTFCC': 'G5040',
'NAME': 'Block 1045',
'OBJECTID': 9940449,
'OID': 210404020212114,
'STATE': '42',
'SUFFIX': '',
'TRACT': '216600'
}],
'Census Tracts': [{
# snip
'NAME': 'Census Tract 2166',
'OBJECTID': 61245,
'OID': 20790277158250,
'STATE': '42',
'TRACT': '216600'
}],
'Counties': [{
# snip
'NAME': 'Luzerne County',
'OBJECTID': 866,
'OID': 27590277115518,
'STATE': '42'
}],
'States': [{
# snip
'NAME': 'Pennsylvania',
'REGION': '1',
'STATE': '42',
'STATENS': '01779798',
'STUSAB': 'PA'
}]
}]
```
### Advanced
By default, the geocoder uses the "Current" vintage and benchmarks. To use another vintage or benchmark, use the `CensusGeocode` class:
````python
from censusgeocode import CensusGeocode
cg = CensusGeocode(benchmark='Public_AR_Current', vintage='Census2020_Current')
cg.onelineaddress(foobar)
````
The Census may update the available benchmarks and vintages. Review the Census Geocoder docs for the currently available [benchmarks](https://geocoding.geo.census.gov/geocoder/benchmarks) and [vintages](https://geocoding.geo.census.gov/geocoder/vintages?form).
## Command line tool
The `censusgeocode` tool has two settings.
At the simplest, it takes one argument, an address, and returns a comma-delimited longitude, latitude pair.
````bash
censusgeocode '100 Fifth Avenue, New York, NY'
-73.992195,40.73797
censusgeocode '1600 Pennsylvania Avenue, Washington DC'
-77.03535,38.898754
````
The Census geocoder is reasonably good at recognizing non-standard addresses.
````bash
censusgeocode 'Hollywood & Vine, LA, CA'
-118.32668,34.101624
````
It can also use the Census Geocoder's batch function to process an entire file. The file must be comma-delimited, have no header, and include the following columns:
````
unique id, street address, state, city, zip code
````
The geocoder can read from a file:
````
censusgeocode --csv tests/fixtures/batch.csv
````
([example file](https://github.com/fitnr/censusgeocode/blob/master/tests/fixtures/batch.csv))
Or from stdin, using `-` as the filename:
````
head tests/fixtures/batch.csv | censusgeocode --csv -
````
According to the Census docs, the batch geocoder is limited to 10,000 rows.
The output will be a CSV file (with a header) and the columns:
* id
* address
* match
* matchtype
* parsed
* tigerlineid
* side
* lat
* lon
If your data doesn't have a unique id, try adding line numbers with the Unix command line utility `nl`:
```
nl -s , input.csv | censusgeocode --csv - > output.csv
```
## License
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Raw data
{
"_id": null,
"home_page": "https://github.com/fitnr/censusgeocode",
"name": "censusgeocode",
"maintainer": "",
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": "",
"keywords": "census,geocode,api",
"author": "Neil Freeman",
"author_email": "contact@fakeisthenewreal.org",
"download_url": "https://files.pythonhosted.org/packages/f2/f5/83c9a6aead949cfda4d21f7fed673f8a40d859a4e4c05e3ff30a8f021b08/censusgeocode-0.5.2.tar.gz",
"platform": "",
"description": "Census Geocode\n--------------\n\nCensus Geocode is a light weight Python wrapper for the US Census [Geocoder API](http://geocoding.geo.census.gov/geocoder/), compatible with Python 3. It comes packaged with a simple command line tool for geocoding an address to a longitude and latitude, or a batch file into a parsed address and coordinates.\n\nIt's strongly recommended to review the [Census Geocoder docs](https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/census-geocoder.html) before using this module.\n\nBasic example:\n\n```python\nimport censusgeocode as cg\n\ncg.coordinates(x=-76, y=41)\ncg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')\ncg.address('1600 Pennsylvania Avenue', city='Washington', state='DC', zip='20006')\ncg.addressbatch('data/addresses.csv')\n```\n\nUse the returntype keyword to specify 'locations' or 'geographies'. 'Locations' yields structured information about the address, and 'geographies' yields information about the Census geographies. Geographies is the default.\n```python\ncg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC', returntype='locations')\n```\n\nQueries return a CensusResult object, which is basically a Python list with an extra 'input' property, which the Census returns to tell you how they interpreted your request.\n\n```python\n>>> result = cg.coordinates(x=-76, y=41)\n>>> result.input\n{\n u'vintage': {\n u'vintageName': u'Current_Current',\n u'id': u'4',\n u'vintageDescription': u'Current Vintage - Current Benchmark',\n u'isDefault': True\n },\n u'benchmark': {\n u'benchmarkName': u'Public_AR_Current',\n u'id': u'4',\n u'isDefault': False,\n u'benchmarkDescription': u'Public Address Ranges - Current Benchmark'\n },\n u'location': {\n u'y': 41.0,\n u'x': -76.0\n }\n}\n>>> result\n[{\n '2010 Census Blocks': [{\n 'AREALAND': 1409023,\n 'AREAWATER': 0,\n 'BASENAME': '1045',\n 'BLKGRP': '1',\n 'BLOCK': '1045',\n 'CENTLAT': '+40.9957436',\n 'CENTLON': '-076.0089338',\n 'COUNTY': '079',\n 'FUNCSTAT': 'S',\n 'GEOID': '420792166001045',\n 'INTPTLAT': '+40.9957436',\n 'INTPTLON': '-076.0089338',\n 'LSADC': 'BK',\n 'LWBLKTYP': 'L',\n 'MTFCC': 'G5040',\n 'NAME': 'Block 1045',\n 'OBJECTID': 9940449,\n 'OID': 210404020212114,\n 'STATE': '42',\n 'SUFFIX': '',\n 'TRACT': '216600'\n }],\n 'Census Tracts': [{\n # snip \n 'NAME': 'Census Tract 2166',\n 'OBJECTID': 61245,\n 'OID': 20790277158250,\n 'STATE': '42',\n 'TRACT': '216600'\n }],\n 'Counties': [{\n # snip\n 'NAME': 'Luzerne County',\n 'OBJECTID': 866,\n 'OID': 27590277115518,\n 'STATE': '42'\n }],\n 'States': [{\n # snip\n 'NAME': 'Pennsylvania',\n 'REGION': '1',\n 'STATE': '42',\n 'STATENS': '01779798',\n 'STUSAB': 'PA'\n }]\n}]\n```\n\n### Advanced\n\nBy default, the geocoder uses the \"Current\" vintage and benchmarks. To use another vintage or benchmark, use the `CensusGeocode` class:\n````python\nfrom censusgeocode import CensusGeocode\ncg = CensusGeocode(benchmark='Public_AR_Current', vintage='Census2020_Current')\ncg.onelineaddress(foobar)\n````\n\nThe Census may update the available benchmarks and vintages. Review the Census Geocoder docs for the currently available [benchmarks](https://geocoding.geo.census.gov/geocoder/benchmarks) and [vintages](https://geocoding.geo.census.gov/geocoder/vintages?form).\n\n## Command line tool\n\nThe `censusgeocode` tool has two settings.\n\nAt the simplest, it takes one argument, an address, and returns a comma-delimited longitude, latitude pair.\n````bash\ncensusgeocode '100 Fifth Avenue, New York, NY'\n-73.992195,40.73797\n\ncensusgeocode '1600 Pennsylvania Avenue, Washington DC'\n-77.03535,38.898754\n````\n\nThe Census geocoder is reasonably good at recognizing non-standard addresses.\n````bash\ncensusgeocode 'Hollywood & Vine, LA, CA'\n-118.32668,34.101624\n````\n\nIt can also use the Census Geocoder's batch function to process an entire file. The file must be comma-delimited, have no header, and include the following columns:\n````\nunique id, street address, state, city, zip code\n````\n\nThe geocoder can read from a file:\n````\ncensusgeocode --csv tests/fixtures/batch.csv\n````\n([example file](https://github.com/fitnr/censusgeocode/blob/master/tests/fixtures/batch.csv))\n\nOr from stdin, using `-` as the filename:\n````\nhead tests/fixtures/batch.csv | censusgeocode --csv -\n````\n\nAccording to the Census docs, the batch geocoder is limited to 10,000 rows.\n\nThe output will be a CSV file (with a header) and the columns:\n* id\n* address\n* match\n* matchtype\n* parsed\n* tigerlineid\n* side\n* lat\n* lon\n\nIf your data doesn't have a unique id, try adding line numbers with the Unix command line utility `nl`:\n```\nnl -s , input.csv | censusgeocode --csv - > output.csv\n```\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.\n\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Thin Python wrapper for the US Census Geocoder",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://github.com/fitnr/censusgeocode"
},
"split_keywords": [
"census",
"geocode",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a8f7eba876fa146e434ab29b295213ca3357d8708f8e4e730453096d5d63b151",
"md5": "188048c796211a7ab55a2d6bec52bca5",
"sha256": "fa2a9e0d44a7216fb5c3d031fc09d6c2008de28cec45495aaad5d309ef06b98b"
},
"downloads": -1,
"filename": "censusgeocode-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "188048c796211a7ab55a2d6bec52bca5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 9178,
"upload_time": "2022-01-22T16:22:22",
"upload_time_iso_8601": "2022-01-22T16:22:22.395813Z",
"url": "https://files.pythonhosted.org/packages/a8/f7/eba876fa146e434ab29b295213ca3357d8708f8e4e730453096d5d63b151/censusgeocode-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2f583c9a6aead949cfda4d21f7fed673f8a40d859a4e4c05e3ff30a8f021b08",
"md5": "de5975c36e0bec93d3aeb9fa60adec58",
"sha256": "ee590d1b7806c630b4a6e60adfa572abf502c95fb2d9489ac045bdda46edde38"
},
"downloads": -1,
"filename": "censusgeocode-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "de5975c36e0bec93d3aeb9fa60adec58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 20898,
"upload_time": "2022-01-22T16:22:23",
"upload_time_iso_8601": "2022-01-22T16:22:23.784906Z",
"url": "https://files.pythonhosted.org/packages/f2/f5/83c9a6aead949cfda4d21f7fed673f8a40d859a4e4c05e3ff30a8f021b08/censusgeocode-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-01-22 16:22:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fitnr",
"github_project": "censusgeocode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "censusgeocode"
}
JSON
