Package: pygeocodio
Python wrapper forGeocodio geocoding API.Full documentation onRead the Docs.If you are upgrading from a version prior to 0.2.0 please see the changelog
in HISTORY.rst. The default coordinate ordering has changed to something a bit
more sensible for most users.Geocodio API FeaturesGeocode an individual addressBatch geocode up to 10,000 addresses at a timeParse an address into its identifiable componentsReverse geocode an individual geographic pointBatch reverse geocode up to 10,000 points at a timePerform operations using the HIPAA API URLThe service is limited to U.S. and Canada addresses for the time being.Read the completeGeocodio documentationfor
service documentation.Installationpygeocodio requiresrequests1.0.0 or greater and will ensure requests is
installed:pip install pygeocodioBasic usageImport the API client and ensure you have a valid API key:>>> from geocodio import GeocodioClient
>>> client = GeocodioClient(YOUR_API_KEY)Note that you can pass in a timeout value in seconds (the default is no timeout):>>> client = GeocodioClient(YOUR_API_KEY, timeout=15)GeocodingGeocoding an individual address:>>> geocoded_location = client.geocode("42370 Bob Hope Drive, Rancho Mirage CA")
>>> geocoded_location.coords
(33.738987255507, -116.40833849559)Geocode a set of address components:>>> geocoded_location = client.geocode(components_data={
  "postal_code": "02210",
  "country": "US"
})
>>> geocoded_location.coords
(42.347547, -71.040645)Batch geocodingYou can also geocode a list of addresses:>>> geocoded_addresses = client.geocode([
        '2 15th St NW, Washington, DC 20024',
        '3101 Patterson Ave, Richmond, VA, 23221'
    ])Return a list of just the coordinates for the resultant geocoded addresses:>>> geocoded_addresses.coords
[(38.890083, -76.983822), (37.560446, -77.476008)]
>>> geocoded_addresses[0].coords
(38.890083, -76.983822)Lookup an address by the queried address:>>> geocoded_addresses.get('2 15th St NW, Washington, DC 20024').coords
(38.879138, -76.981879))You can also geocode a list of address component dictionaries:>>> geocoded_addresses = client.geocode(components_data=[{
        'street': '1109 N Highland St',
        'city': 'Arlington',
        'state': 'VA'
    }, {
        'city': 'Toronto',
        'country': 'CA'
    }])And geocode a keyed mapping of address components:>>> gecoded_addresses = client.geocode(components_data={
        "1": {
            "street": "1109 N Highland St",
            "city": "Arlington",
            "state": "VA"
        },
        "2": {
            "city": "Toronto",
            "country": "CA"
        }})And geocode even a keyed mapping of addresses:>>> geocoded_addresses = client.geocode({
        "1": "3101 patterson ave, richmond, va",
        "2": "1657 W Broad St, Richmond, VA"
    })Return a list of just the coordinates for the resultant geocoded addresses:>>> geocoded_addresses.coords
{'1': (37.560454, -77.47601), '2': (37.555176, -77.458273)}Lookup an address by its key:>>> geocoded_addresses.get("1").coords
(37.560454, -77.47601)Address parsingAnd if you just want to parse an individual address into its components:>>> client.parse('1600 Pennsylvania Ave, Washington DC')
  {
      "address_components": {
          "number": "1600",
          "street": "Pennsylvania",
          "suffix": "Ave",
          "city": "Washington",
          "state": "DC"
      },
      "formatted_address": "1600 Pennsylvania Ave, Washington DC"
  }Reverse geocodingReverse geocode a point to find a matching address:>>> location = client.reverse((33.738987, -116.4083))
>>> location.formatted_address
"42370 Bob Hope Dr, Rancho Mirage CA, 92270"Batch reverse geocodingAnd multiple points at a time:>>> locations = client.reverse([
        (33.738987, -116.4083),
        (33.738987, -116.4083),
        (38.890083, -76.983822)
    ])Return the list of formatted addresses:>>> locations.formatted_addresses
["42370 Bob Hope Dr, Rancho Mirage CA, 92270",  "42370 Bob Hope Dr, Rancho Mirage CA, 92270", "2 15th St NW, Washington, DC 20024"]Access a specific address by the queried point tuple:>>> locations.get("38.890083,-76.983822").formatted_address
"2 15th St NW, Washington, DC 20024"Or by the more natural key of the queried point tuple:>>> locations.get((38.890083, -76.983822)).formatted_address
"2 15th St NW, Washington, DC 20024"CLI usageIn the works!DocumentationFor complete documentation seethe docs.LicenseBSD LicenseHistory1.4.0 (2023-07-08)Drop support for Python 3.71.3.0 (2023-05-31)Adds support for the ‘limit’ parameter to limit results (thanks bruno-uy!)1.2.0 (2023-03-21)Adds custom_base_domain support (thanks MiniCodeMonkey!)Drops Python 3.6 supportAdds official Python 3.11 support1.1.0 (2022-03-28)Adds a timeout parameter for API requests (thanks aviv!)1.0.1 (2021-07-18)Fixes batched keyed address geocoding1.0.0 (2020-06-18)Adds support for keying batch geocode results (thanks liufran1 and Unix-Code!)Adds support for keying batch reverse geocode results (thanks liufran1 and Unix-Code!)0.12.0 (2020-06-04)Adds auto-loading of API version (thanks Unix-Code!)Default API calls to Version 1.6 (thanks MiniCodeMonkey!)0.11.1 (2019-11-07)Default API calls to Version 1.4 (thanks cyranix!)0.11.0 (2019-10-19)Search by address components (thanks Unix-Code!)0.10.0 (2019-02-05)Replaced http with https in clinet (thanks shea-parkes!)0.9.0 (2019-01-15)Updates to use Geocodio API v 1.3 by default (thanks joshgeller!)The API version is now configurable for backwards and forward compatibility0.8.0 (2018-12-30)Adds new US Census fields (thanks pedromachados!)0.7.0 (2018-03-29)Added support for new Congressional districts for 2018 election (thanks nickcatal!)0.6.0 (2018-02-16)Upgrade to Geocodio API version 1.2 (thanks MiniCodeMonkey!)Update allowed fieldsUpdate docs that Canada now included (thanks Goorzhel!)Miscellaneous fixes (thanks snake-plissken!)0.5.0 (2016-05-16)Add additional allowed fields (census, cd114)0.4.2 (2015-02-17)Bug fix the last bug fix0.4.1 (2015-02-17)Bug fix to flatten ‘fields’ argument as a single query key0.4.0 (2014-09-28)Bug fix for batch reverse geocodingRemoves request handling from client methods0.3.0 (2014-03-24)Adds support for additional data fields (e.g. Congressional districts, timezone)0.2.1 (2014-02-15)Fixed Python 3.3 test errors. Shouldn’t have any functional effect on Python
3.3 usage except for matching module paths of pygeocodio objects.0.2.0 (2014-02-07)Added initial reverse geocoding functionalitySwaps default coordinates order. This is a mostly backwards incompatible
change to amend a silly design decision.0.1.4 (2014-01-25)Handle error in which Geoco.io has returned empty result set0.1.3 (2014-01-25)Packaging fix, thanks to @kyen990.1.2 (2014-01-23)Moves and enhances fixture data to JSON data based on linted server responsesAdds Geocodio named errorsBetter handling of errors in individual locations from batch requests0.1.1 (2014-01-22)Adds requests to install_requires in setup.py and drops minimum version to 1.0.00.1.0 (2014-01-21)First release on PyPI.