===========
Py-Geocodio
===========
.. image:: https://badge.fury.io/py/pygeocodio.svg
:target: http://badge.fury.io/py/pygeocodio
.. image:: https://github.com/bennylope/pygeocodio/actions/workflows/tests.yml/badge.svg?branch=master
:target: https://github.com/bennylope/pygeocodio/actions
.. image:: https://img.shields.io/pypi/dm/pygeocodio.svg
:target: https://img.shields.io/pypi/dm/pygeocodio.svg
Python wrapper for `Geocodio geocoding API <http://geocod.io/docs/>`_.
Full documentation on `Read the Docs <http://pygeocodio.readthedocs.org/en/latest/>`_.
**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 <http://geocod.io/docs/>`_ 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
<http://pygeocodio.readthedocs.org/en/latest/>`_.
License
=======
BSD License
History
-------
1.4.0 (2023-07-08)
+++++++++++++++++++
* Drop support for Python 3.7
1.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 support
* Adds official Python 3.11 support
1.1.0 (2022-03-28)
+++++++++++++++++++
* Adds a timeout parameter for API requests (thanks aviv!)
1.0.1 (2021-07-18)
+++++++++++++++++++
* Fixes batched keyed address geocoding
1.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 compatibility
0.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 fields
* Update 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 fix
0.4.1 (2015-02-17)
++++++++++++++++++
* Bug fix to flatten 'fields' argument as a single query key
0.4.0 (2014-09-28)
++++++++++++++++++
* Bug fix for batch reverse geocoding
* Removes request handling from client methods
0.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 functionality
* Swaps 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 set
0.1.3 (2014-01-25)
++++++++++++++++++
* Packaging fix, thanks to @kyen99
0.1.2 (2014-01-23)
++++++++++++++++++
* Moves and enhances fixture data to JSON data based on linted server responses
* Adds Geocodio named errors
* Better handling of errors in individual locations from batch requests
0.1.1 (2014-01-22)
++++++++++++++++++
* Adds requests to install_requires in setup.py and drops minimum version to 1.0.0
0.1.0 (2014-01-21)
++++++++++++++++++
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/bennylope/pygeocodio",
"name": "pygeocodio",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "geocodio",
"author": "Ben Lopatin",
"author_email": "ben@benlopatin.com",
"download_url": "https://files.pythonhosted.org/packages/da/b1/bc3c628ed5b9c97e7e9a83561704a4075855cf3ee17a59080fdb4a31eaf8/pygeocodio-1.4.0.tar.gz",
"platform": null,
"description": "===========\nPy-Geocodio\n===========\n\n.. image:: https://badge.fury.io/py/pygeocodio.svg\n :target: http://badge.fury.io/py/pygeocodio\n\n.. image:: https://github.com/bennylope/pygeocodio/actions/workflows/tests.yml/badge.svg?branch=master\n :target: https://github.com/bennylope/pygeocodio/actions\n\n.. image:: https://img.shields.io/pypi/dm/pygeocodio.svg\n :target: https://img.shields.io/pypi/dm/pygeocodio.svg\n\n\nPython wrapper for `Geocodio geocoding API <http://geocod.io/docs/>`_.\n\nFull documentation on `Read the Docs <http://pygeocodio.readthedocs.org/en/latest/>`_.\n\n**If you are upgrading from a version prior to 0.2.0 please see the changelog\nin HISTORY.rst. The default coordinate ordering has changed to something a bit\nmore sensible for most users.**\n\nGeocodio API Features\n=====================\n\n* Geocode an individual address\n* Batch geocode up to 10,000 addresses at a time\n* Parse an address into its identifiable components\n* Reverse geocode an individual geographic point\n* Batch reverse geocode up to 10,000 points at a time\n* Perform operations using the HIPAA API URL\n\nThe service is limited to U.S. and Canada addresses for the time being.\n\nRead the complete `Geocodio documentation <http://geocod.io/docs/>`_ for\nservice documentation.\n\nInstallation\n============\n\npygeocodio requires `requests` 1.0.0 or greater and will ensure requests is\ninstalled::\n\n pip install pygeocodio\n\nBasic usage\n===========\n\nImport the API client and ensure you have a valid API key::\n\n >>> from geocodio import GeocodioClient\n >>> client = GeocodioClient(YOUR_API_KEY)\n\nNote that you can pass in a timeout value in seconds (the default is no timeout)::\n\n >>> client = GeocodioClient(YOUR_API_KEY, timeout=15)\n\nGeocoding\n---------\n\nGeocoding an individual address::\n\n >>> geocoded_location = client.geocode(\"42370 Bob Hope Drive, Rancho Mirage CA\")\n >>> geocoded_location.coords\n (33.738987255507, -116.40833849559)\n\n\nGeocode a set of address components::\n\n >>> geocoded_location = client.geocode(components_data={\n \"postal_code\": \"02210\",\n \"country\": \"US\"\n })\n >>> geocoded_location.coords\n (42.347547, -71.040645)\n\nBatch geocoding\n---------------\n\nYou can also geocode a list of addresses::\n\n >>> geocoded_addresses = client.geocode([\n '2 15th St NW, Washington, DC 20024',\n '3101 Patterson Ave, Richmond, VA, 23221'\n ])\n\nReturn a list of just the coordinates for the resultant geocoded addresses::\n\n >>> geocoded_addresses.coords\n [(38.890083, -76.983822), (37.560446, -77.476008)]\n >>> geocoded_addresses[0].coords\n (38.890083, -76.983822)\n\nLookup an address by the queried address::\n\n >>> geocoded_addresses.get('2 15th St NW, Washington, DC 20024').coords\n (38.879138, -76.981879))\n\n\nYou can also geocode a list of address component dictionaries::\n\n >>> geocoded_addresses = client.geocode(components_data=[{\n 'street': '1109 N Highland St',\n 'city': 'Arlington',\n 'state': 'VA'\n }, {\n 'city': 'Toronto',\n 'country': 'CA'\n }])\n\n\nAnd geocode a keyed mapping of address components::\n\n >>> gecoded_addresses = client.geocode(components_data={\n \"1\": {\n \"street\": \"1109 N Highland St\",\n \"city\": \"Arlington\",\n \"state\": \"VA\"\n },\n \"2\": {\n \"city\": \"Toronto\",\n \"country\": \"CA\"\n }})\n\n\nAnd geocode even a keyed mapping of addresses::\n\n >>> geocoded_addresses = client.geocode({\n \"1\": \"3101 patterson ave, richmond, va\",\n \"2\": \"1657 W Broad St, Richmond, VA\"\n })\n\nReturn a list of just the coordinates for the resultant geocoded addresses::\n\n >>> geocoded_addresses.coords\n {'1': (37.560454, -77.47601), '2': (37.555176, -77.458273)}\n\n\nLookup an address by its key::\n\n >>> geocoded_addresses.get(\"1\").coords\n (37.560454, -77.47601)\n\n\nAddress parsing\n---------------\n\nAnd if you just want to parse an individual address into its components::\n\n >>> client.parse('1600 Pennsylvania Ave, Washington DC')\n {\n \"address_components\": {\n \"number\": \"1600\",\n \"street\": \"Pennsylvania\",\n \"suffix\": \"Ave\",\n \"city\": \"Washington\",\n \"state\": \"DC\"\n },\n \"formatted_address\": \"1600 Pennsylvania Ave, Washington DC\"\n }\n \nReverse geocoding\n-----------------\n\nReverse geocode a point to find a matching address::\n\n >>> location = client.reverse((33.738987, -116.4083))\n >>> location.formatted_address\n \"42370 Bob Hope Dr, Rancho Mirage CA, 92270\"\n\nBatch reverse geocoding\n-----------------------\n\nAnd multiple points at a time::\n\n >>> locations = client.reverse([\n (33.738987, -116.4083),\n (33.738987, -116.4083),\n (38.890083, -76.983822)\n ])\n\nReturn the list of formatted addresses::\n\n >>> locations.formatted_addresses\n [\"42370 Bob Hope Dr, Rancho Mirage CA, 92270\", \"42370 Bob Hope Dr, Rancho Mirage CA, 92270\", \"2 15th St NW, Washington, DC 20024\"]\n\nAccess a specific address by the queried point tuple::\n\n >>> locations.get(\"38.890083,-76.983822\").formatted_address\n \"2 15th St NW, Washington, DC 20024\"\n\nOr by the more natural key of the queried point tuple::\n\n >>> locations.get((38.890083, -76.983822)).formatted_address\n \"2 15th St NW, Washington, DC 20024\"\n\nCLI usage\n=========\n\nIn the works!\n\nDocumentation\n=============\n\nFor complete documentation see `the docs\n<http://pygeocodio.readthedocs.org/en/latest/>`_.\n\nLicense\n=======\n\nBSD License\n\n\n\n\nHistory\n-------\n\n1.4.0 (2023-07-08)\n+++++++++++++++++++\n\n* Drop support for Python 3.7\n\n1.3.0 (2023-05-31)\n+++++++++++++++++++\n\n* Adds support for the 'limit' parameter to limit results (thanks bruno-uy!)\n\n1.2.0 (2023-03-21)\n+++++++++++++++++++\n\n* Adds custom_base_domain support (thanks MiniCodeMonkey!)\n* Drops Python 3.6 support\n* Adds official Python 3.11 support\n\n1.1.0 (2022-03-28)\n+++++++++++++++++++\n\n* Adds a timeout parameter for API requests (thanks aviv!)\n\n1.0.1 (2021-07-18)\n+++++++++++++++++++\n* Fixes batched keyed address geocoding\n\n1.0.0 (2020-06-18)\n+++++++++++++++++++\n\n* Adds support for keying batch geocode results (thanks liufran1 and Unix-Code!)\n* Adds support for keying batch reverse geocode results (thanks liufran1 and Unix-Code!)\n\n0.12.0 (2020-06-04)\n+++++++++++++++++++\n\n* Adds auto-loading of API version (thanks Unix-Code!)\n* Default API calls to Version 1.6 (thanks MiniCodeMonkey!) \n\n0.11.1 (2019-11-07)\n+++++++++++++++++++\n\n* Default API calls to Version 1.4 (thanks cyranix!) \n\n0.11.0 (2019-10-19)\n+++++++++++++++++++\n\n* Search by address components (thanks Unix-Code!)\n\n0.10.0 (2019-02-05)\n+++++++++++++++++++\n\n* Replaced http with https in clinet (thanks shea-parkes!)\n\n0.9.0 (2019-01-15)\n++++++++++++++++++\n\n* Updates to use Geocodio API v 1.3 by default (thanks joshgeller!)\n* The API version is now configurable for backwards and forward compatibility\n\n\n0.8.0 (2018-12-30)\n++++++++++++++++++\n\n* Adds new US Census fields (thanks pedromachados!)\n\n0.7.0 (2018-03-29)\n++++++++++++++++++\n\n* Added support for new Congressional districts for 2018 election (thanks nickcatal!)\n\n0.6.0 (2018-02-16)\n++++++++++++++++++\n\n* Upgrade to Geocodio API version 1.2 (thanks MiniCodeMonkey!)\n* Update allowed fields\n* Update docs that Canada now included (thanks Goorzhel!)\n* Miscellaneous fixes (thanks snake-plissken!)\n\n0.5.0 (2016-05-16)\n++++++++++++++++++\n\n* Add additional allowed fields (census, cd114)\n\n0.4.2 (2015-02-17)\n++++++++++++++++++\n\n* Bug fix the last bug fix\n\n0.4.1 (2015-02-17)\n++++++++++++++++++\n\n* Bug fix to flatten 'fields' argument as a single query key\n\n0.4.0 (2014-09-28)\n++++++++++++++++++\n\n* Bug fix for batch reverse geocoding\n* Removes request handling from client methods\n\n0.3.0 (2014-03-24)\n++++++++++++++++++\n\n* Adds support for additional data fields (e.g. Congressional districts, timezone)\n\n0.2.1 (2014-02-15)\n++++++++++++++++++\n\n* Fixed Python 3.3 test errors. Shouldn't have any functional effect on Python\n 3.3 usage except for matching module paths of pygeocodio objects.\n\n0.2.0 (2014-02-07)\n++++++++++++++++++\n\n* Added initial reverse geocoding functionality\n* Swaps default coordinates order. This is a mostly backwards incompatible\n change to amend a silly design decision.\n\n0.1.4 (2014-01-25)\n++++++++++++++++++\n\n* Handle error in which Geoco.io has returned empty result set\n\n0.1.3 (2014-01-25)\n++++++++++++++++++\n\n* Packaging fix, thanks to @kyen99\n\n0.1.2 (2014-01-23)\n++++++++++++++++++\n\n* Moves and enhances fixture data to JSON data based on linted server responses\n* Adds Geocodio named errors\n* Better handling of errors in individual locations from batch requests\n\n0.1.1 (2014-01-22)\n++++++++++++++++++\n\n* Adds requests to install_requires in setup.py and drops minimum version to 1.0.0\n\n0.1.0 (2014-01-21)\n++++++++++++++++++\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Python wrapper for Geocod.io API",
"version": "1.4.0",
"project_urls": {
"Homepage": "https://github.com/bennylope/pygeocodio"
},
"split_keywords": [
"geocodio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6f2654d0ea257cbaed72e73da13a92de9998705ccd988c9c739f5366c152ba1",
"md5": "a73353f66c62885229ecdb483d82c12b",
"sha256": "f986453139936c801ddc28ed9e519f830a2f4e410a21f861925c9c72fda091dc"
},
"downloads": -1,
"filename": "pygeocodio-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a73353f66c62885229ecdb483d82c12b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11013,
"upload_time": "2023-07-08T19:31:10",
"upload_time_iso_8601": "2023-07-08T19:31:10.648298Z",
"url": "https://files.pythonhosted.org/packages/d6/f2/654d0ea257cbaed72e73da13a92de9998705ccd988c9c739f5366c152ba1/pygeocodio-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dab1bc3c628ed5b9c97e7e9a83561704a4075855cf3ee17a59080fdb4a31eaf8",
"md5": "d6c9a803f38ea49e77bec211dc695c50",
"sha256": "400954db20a86e949eedd3383e2a57d3c2da3fe7457b7f348b30eb4c5e03808e"
},
"downloads": -1,
"filename": "pygeocodio-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "d6c9a803f38ea49e77bec211dc695c50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14357,
"upload_time": "2023-07-08T19:31:12",
"upload_time_iso_8601": "2023-07-08T19:31:12.103467Z",
"url": "https://files.pythonhosted.org/packages/da/b1/bc3c628ed5b9c97e7e9a83561704a4075855cf3ee17a59080fdb4a31eaf8/pygeocodio-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-08 19:31:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bennylope",
"github_project": "pygeocodio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "httpretty",
"specs": [
[
">=",
"0.9.7"
]
]
}
],
"tox": true,
"lcname": "pygeocodio"
}
JSON
