Metadata-Version: 2.0
Name: censusgeocode
Version: 0.3.0
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[security] (<3,>=2.18)

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

Census Geocode is a 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.

Census Geocode is very lightweight, and relies only on
`requests <http://docs.python-requests.org/en/latest/>`__.

Basic example:

.. code:: python

    from censusgeocode import CensusGeocode

    cg = CensusGeocode()

    cg.coordinates(x=-76, y=41)
    cg.onelineaddress('1600 Pennsylvania Avenue, Washington, DC')
    cg.address('1600 Pennsylvania Avenue', city='Washington', state='DC', zipcode='22052')

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'
        }]
    }]

Command line tool
-----------------

The ``censusgeocode`` tool is bare bones. 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

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/.


