# OpenCage Geocoding Module for Python
A Python module to access the [OpenCage Geocoding API](https://opencagedata.com/).
## Build Status / Code Quality / etc
[](https://badge.fury.io/py/opencage)
[](https://pepy.tech/project/opencage)
[](https://pypi.org/project/opencage/)
[](https://github.com/OpenCageData/python-opencage-geocoder/actions/workflows/build.yml)
## Tutorial
You can find a [comprehensive tutorial for using this module on the OpenCage site](https://opencagedata.com/tutorials/geocode-in-python).
## Usage
Supports Python 3.7 or newer. Use the older opencage 1.x releases if you need Python 2.7 support.
Install the module:
```bash
pip install opencage
```
Load the module:
```python
from opencage.geocoder import OpenCageGeocode
```
Create an instance of the geocoder module, passing a valid OpenCage Data Geocoder API key
as a parameter to the geocoder modules's constructor:
```python
key = 'your-api-key-here'
geocoder = OpenCageGeocode(key)
```
Pass a string containing the query or address to be geocoded to the modules' `geocode` method:
```python
query = '82 Clerkenwell Road, London'
results = geocoder.geocode(query)
```
You can add [additional parameters](https://opencagedata.com/api#forward-opt):
```python
results = geocoder.geocode('London', no_annotations=1, language='es')
```
For example you can use the proximity parameter to provide the geocoder with a hint:
```python
results = geocoder.geocode('London', proximity='42.828576, -81.406643')
print(results[0]['formatted'])
# u'London, ON N6A 3M8, Canada'
```
### Reverse geocoding
Turn a lat/long into an address with the `reverse_geocode` method:
```python
result = geocoder.reverse_geocode(51.51024, -0.10303)
```
### Sessions
You can reuse your HTTP connection for multiple requests by
using a `with` block. This can help performance when making
a lot of requests:
```python
queries = ['82 Clerkenwell Road, London', ...]
with OpenCageGeocode(key) as geocoder:
# Queries reuse the same HTTP connection
results = [geocoder.geocode(query) for query in queries]
```
### Asyncronous requests
You can run requests in parallel with the `geocode_async` and `reverse_geocode_async`
method which have the same parameters and response as their synronous counterparts.
You will need at least Python 3.7 and the `asyncio` and `aiohttp` packages installed.
```python
async with OpenCageGeocode(key) as geocoder:
results = await geocoder.geocode_async(address)
```
For a more complete example and links to futher tutorials on asyncronous IO see
`batch.py` in the `examples` directory.
### Non-SSL API use
If you have trouble accesing the OpenCage API with https, e.g. issues with OpenSSL
libraries in your enviroment, then you can set the 'http' protocol instead. Please
understand that the connection to the OpenCage API will no longer be encrypted.
```python
geocoder = OpenCageGeocode('your-api-key', 'http')
```
### Command-line batch geocoding
See `examples/batch.py` for an example to geocode a CSV file.
<img src="batch-progress.gif"/>
### Exceptions
If anything goes wrong, then an exception will be raised:
- `InvalidInputError` for non-unicode query strings
- `NotAuthorizedError` if API key is missing, invalid syntax or disabled
- `ForbiddenError` API key is blocked or suspended
- `RateLimitExceededError` if you go past your rate limit
- `UnknownError` if there's some problem with the API (bad results, 500 status code, etc)
## Copyright & License
This software is copyright OpenCage GmbH.
Please see `LICENSE.txt`
### Who is OpenCage GmbH?
<a href="https://opencagedata.com"><img src="opencage_logo_300_150.png"/></a>
We run a worldwide [geocoding API](https://opencagedata.com/api) and [geosearch](https://opencagedata.com/geosearch) service based on open data.
Learn more [about us](https://opencagedata.com/about).
We also run [Geomob](https://thegeomob.com), a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy [the Geomob podcast](https://thegeomob.com/podcast/).
Raw data
{
"_id": null,
"home_page": "https://github.com/OpenCageData/python-opencage-geocoder/",
"name": "opencage",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "geocoding,geocoder",
"author": "OpenCage GmbH",
"author_email": "info@opencagedata.com",
"download_url": "https://files.pythonhosted.org/packages/3c/52/d52316f077e1b90ae40c7aeb0787b2a56ed278c17d1c9003940a93af6170/opencage-2.4.0.tar.gz",
"platform": null,
"description": "# OpenCage Geocoding Module for Python\n\nA Python module to access the [OpenCage Geocoding API](https://opencagedata.com/).\n\n## Build Status / Code Quality / etc\n\n[](https://badge.fury.io/py/opencage)\n[](https://pepy.tech/project/opencage)\n[](https://pypi.org/project/opencage/)\n\n[](https://github.com/OpenCageData/python-opencage-geocoder/actions/workflows/build.yml)\n\n\n## Tutorial\n\nYou can find a [comprehensive tutorial for using this module on the OpenCage site](https://opencagedata.com/tutorials/geocode-in-python).\n\n## Usage\n\nSupports Python 3.7 or newer. Use the older opencage 1.x releases if you need Python 2.7 support.\n\nInstall the module:\n\n```bash\npip install opencage\n```\n\nLoad the module:\n\n```python\nfrom opencage.geocoder import OpenCageGeocode\n```\n\nCreate an instance of the geocoder module, passing a valid OpenCage Data Geocoder API key\nas a parameter to the geocoder modules's constructor:\n\n```python\nkey = 'your-api-key-here'\ngeocoder = OpenCageGeocode(key)\n```\n\nPass a string containing the query or address to be geocoded to the modules' `geocode` method:\n\n```python\nquery = '82 Clerkenwell Road, London'\nresults = geocoder.geocode(query)\n```\n\nYou can add [additional parameters](https://opencagedata.com/api#forward-opt):\n\n```python\nresults = geocoder.geocode('London', no_annotations=1, language='es')\n```\n\nFor example you can use the proximity parameter to provide the geocoder with a hint:\n\n```python\nresults = geocoder.geocode('London', proximity='42.828576, -81.406643')\nprint(results[0]['formatted'])\n# u'London, ON N6A 3M8, Canada'\n```\n\n### Reverse geocoding\n\nTurn a lat/long into an address with the `reverse_geocode` method:\n\n```python\nresult = geocoder.reverse_geocode(51.51024, -0.10303)\n```\n\n### Sessions\n\nYou can reuse your HTTP connection for multiple requests by\nusing a `with` block. This can help performance when making\na lot of requests:\n\n```python\nqueries = ['82 Clerkenwell Road, London', ...]\nwith OpenCageGeocode(key) as geocoder:\n # Queries reuse the same HTTP connection\n results = [geocoder.geocode(query) for query in queries]\n```\n\n### Asyncronous requests\n\nYou can run requests in parallel with the `geocode_async` and `reverse_geocode_async`\nmethod which have the same parameters and response as their synronous counterparts.\nYou will need at least Python 3.7 and the `asyncio` and `aiohttp` packages installed.\n\n```python\nasync with OpenCageGeocode(key) as geocoder:\n results = await geocoder.geocode_async(address)\n```\n\nFor a more complete example and links to futher tutorials on asyncronous IO see\n`batch.py` in the `examples` directory.\n\n### Non-SSL API use\n\nIf you have trouble accesing the OpenCage API with https, e.g. issues with OpenSSL\nlibraries in your enviroment, then you can set the 'http' protocol instead. Please\nunderstand that the connection to the OpenCage API will no longer be encrypted.\n\n```python\ngeocoder = OpenCageGeocode('your-api-key', 'http')\n```\n\n### Command-line batch geocoding\n\nSee `examples/batch.py` for an example to geocode a CSV file.\n\n<img src=\"batch-progress.gif\"/>\n\n### Exceptions\n\nIf anything goes wrong, then an exception will be raised:\n\n- `InvalidInputError` for non-unicode query strings\n- `NotAuthorizedError` if API key is missing, invalid syntax or disabled\n- `ForbiddenError` API key is blocked or suspended\n- `RateLimitExceededError` if you go past your rate limit\n- `UnknownError` if there's some problem with the API (bad results, 500 status code, etc)\n\n## Copyright & License\n\nThis software is copyright OpenCage GmbH.\nPlease see `LICENSE.txt`\n\n### Who is OpenCage GmbH?\n\n<a href=\"https://opencagedata.com\"><img src=\"opencage_logo_300_150.png\"/></a>\n\nWe run a worldwide [geocoding API](https://opencagedata.com/api) and [geosearch](https://opencagedata.com/geosearch) service based on open data.\nLearn more [about us](https://opencagedata.com/about).\n\nWe also run [Geomob](https://thegeomob.com), a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy [the Geomob podcast](https://thegeomob.com/podcast/).\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Wrapper module for the OpenCage Geocoder API",
"version": "2.4.0",
"project_urls": {
"Download": "https://github.com/OpenCageData/python-opencage-geocoder/tarball/2.4.0",
"Homepage": "https://github.com/OpenCageData/python-opencage-geocoder/"
},
"split_keywords": [
"geocoding",
"geocoder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1ec051441cbfe21146f5c153af3fa19f24f9621734af398f3da6f4e781adce68",
"md5": "caf3a058a100515bc6396b37b1d1b9bf",
"sha256": "0453bfeb94227f32efd31c2aed40699c96a62f90e15d5c62d13c2fde8223a5dd"
},
"downloads": -1,
"filename": "opencage-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "caf3a058a100515bc6396b37b1d1b9bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16137,
"upload_time": "2023-12-09T17:57:41",
"upload_time_iso_8601": "2023-12-09T17:57:41.050410Z",
"url": "https://files.pythonhosted.org/packages/1e/c0/51441cbfe21146f5c153af3fa19f24f9621734af398f3da6f4e781adce68/opencage-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3c52d52316f077e1b90ae40c7aeb0787b2a56ed278c17d1c9003940a93af6170",
"md5": "5903441aa0a970304a98e6c5e74f7a0d",
"sha256": "fe8a73efc91220bcd4b91a598178e5a1107330f00d5472242189c2006a74afbc"
},
"downloads": -1,
"filename": "opencage-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "5903441aa0a970304a98e6c5e74f7a0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11980,
"upload_time": "2023-12-09T17:57:42",
"upload_time_iso_8601": "2023-12-09T17:57:42.829656Z",
"url": "https://files.pythonhosted.org/packages/3c/52/d52316f077e1b90ae40c7aeb0787b2a56ed278c17d1c9003940a93af6170/opencage-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-09 17:57:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OpenCageData",
"github_project": "python-opencage-geocoder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "opencage"
}
JSON
