Py-Geocodio

Python wrapper for Geocodio geocoding API.

Full documentation on Read 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 Features

• Geocode an individual address
• Batch geocode up to 10,000 addresses at a time
• Parse an address into its identifiable components
• Reverse geocode an individual geographic point
• Batch reverse geocode up to 10,000 points at a time
• Perform operations using the HIPAA API URL

The service is limited to U.S. and Canada addresses for the time being.

Read the complete Geocodio documentation for service documentation.

Installation

pygeocodio requires requests 1.0.0 or greater and will ensure requests is installed:

pip install pygeocodio

Basic usage

Import 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)

Geocoding

Geocoding 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 geocoding

You 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 parsing

And 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 geocoding

Reverse 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 geocoding

And 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 usage

In the works!

Documentation

For complete documentation see the docs.

License

BSD License