Metadata-Version: 2.0
Name: censusgeocode
Version: 0.4.2
Summary: Thin Python wrapper for the US Census Geocoder
Home-page: https://github.com/fitnr/censusgeocode
Author: Neil Freeman
Author-email: contact@fakeisthenewreal.org
License: GNU General Public License v3 (GPLv3)
Keywords: census geocode api
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.4
Classifier: Operating System :: OS Independent
Requires-Dist: requests-toolbelt (>=0.8.0,<1)
Requires-Dist: requests[security] (<3,>=2.18)
Requires-Dist: six

Census Geocode
--------------

Census Geocode is a light weight Python wrapper for the US Census
`Geocoder API <http://geocoding.geo.census.gov/geocoder/>`__, compatible
with both Python 2 and 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://geocoding.geo.census.gov/geocoder/Geocoding_Services_API.pdf>`__
before using this module.

Basic example:

.. code:: 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', zipcode='22052')
    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.

.. code:: 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.

.. code:: 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': [{
            'AREALAND': 86404594,
            'AREAWATER': 650526,
            'BASENAME': '2166',
            'CENTLAT': '+41.0361462',
            'CENTLON': '-075.9801252',
            'COUNTY': '079',
            'FUNCSTAT': 'S',
            'GEOID': '42079216600',
            'INTPTLAT': '+41.0379841',
            'INTPTLON': '-075.9743749',
            'LSADC': 'CT',
            'MTFCC': 'G5020',
            'NAME': 'Census Tract 2166',
            'OBJECTID': 61245,
            'OID': 20790277158250,
            'STATE': '42',
            'TRACT': '216600'
        }],
        'Counties': [{
            'AREALAND': 2305974186,
            'AREAWATER': 41240020,
            'BASENAME': 'Luzerne',
            'CENTLAT': '+41.1768961',
            'CENTLON': '-075.9890400',
            'COUNTY': '079',
            'COUNTYCC': 'H1',
            'COUNTYNS': '01209183',
            'FUNCSTAT': 'A',
            'GEOID': '42079',
            'INTPTLAT': '+41.1727868',
            'INTPTLON': '-075.9760345',
            'LSADC': '06',
            'MTFCC': 'G4020',
            'NAME': 'Luzerne County',
            'OBJECTID': 866,
            'OID': 27590277115518,
            'STATE': '42'
        }],
        'States': [{
            'AREALAND': 115884236236,
            'AREAWATER': 3395797284,
            'BASENAME': 'Pennsylvania',
            'CENTLAT': '+40.9011252',
            'CENTLON': '-077.8369164',
            'DIVISION': '2',
            'FUNCSTAT': 'A',
            'GEOID': '42',
            'INTPTLAT': '+40.9024957',
            'INTPTLON': '-077.8334514',
            'LSADC': '00',
            'MTFCC': 'G4000',
            'NAME': 'Pennsylvania',
            'OBJECTID': 37,
            'OID': 27490163788605,
            '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:

.. code:: python

    import censusgeocode
    cg = censusgeocode.CensusGeocode(benchmark='Public_AR_Census2010', vintage='Census2010_Census2010')
    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.

.. code:: 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.

.. code:: 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:

::

    cat tests/fixtures/batch.csv | censusgeocode --csv -

According to the Census docs, the batch geocoder is limited to 1000
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/.


