Data

Tools

Indexes

Applications

Experiments

Open Source Science

opencage

Python module to access the OpenCage geocoding API

https://github.com/opencagedata/python-opencage-geocoder

Science Score: 26.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ○
    Committers with academic emails
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (13.7%) to scientific vocabulary

Keywords

geocoding opencage opencage-geocoder python

Keywords from Contributors

geocode
Last synced: 6 months ago · JSON representation

Repository

Python module to access the OpenCage geocoding API

Basic Info
Statistics
  • Stars: 83
  • Watchers: 9
  • Forks: 24
  • Open Issues: 2
  • Releases: 0
Topics
geocoding opencage opencage-geocoder python
Created almost 12 years ago · Last pushed 9 months ago
Metadata Files
Readme Changelog License Security

README.md

OpenCage Geocoding Module for Python

A Python module to access the OpenCage Geocoding API.

Build Status / Code Quality / etc

PyPI version Downloads Versions GitHub contributors Build Status Mastodon Follow

Tutorials

You can find a comprehensive tutorial for using this module on the OpenCage site.

There are two brief video tutorials on YouTube, one covering forward geocoding, one covering reverse geocoding.

The module installs an opencage CLI tool for geocoding files. Check opencage --help or the CLI tutorial.

Usage

Supports Python 3.8 or newer. Starting opencage version 3.0 depends on asyncio package.

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:

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.8 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')

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)

Command-line batch geocoding

Use opencage forward or opencage reverse

``` opencage forward --help

options: -h, --help show this help message and exit --api-key APIKEY Your OpenCage API key --input FILENAME Input file name --output FILENAME Output file name --headers If the first row should be treated as a header row --input-columns Comma-separated list of integers (default '1') --add-columns Comma-separated list of output columns (default 'lat,lng,type,category,countrycode,country,state,county,normalizedcity,postcode,road,housenumber,confidence,formatted,json,status') --workers Number of parallel geocoding requests (default 1) --timeout Timeout in seconds (default 10) --retries Number of retries (default 5) --api-domain API domain (default api.opencagedata.com) --optional-api-params Extra parameters for each request (e.g. language=fr,nodedupe=1) --unordered Allow the output lines to be in different order (can be faster) --limit Stop after this number of lines in the input --dry-run Read the input file but no geocoding --no-progress Display no progress bar --quiet No progress bar and no messages --overwrite Delete the output file first if it exists --verbose Display debug information for each request ```

Copyright & License

This software is copyright OpenCage GmbH. Please see LICENSE.txt

Who is OpenCage GmbH?

We run a worldwide geocoding API and geosearch service based on open data. Learn more about us.

We also run Geomob, 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.

Owner

  • Name: OpenCage GmbH
  • Login: OpenCageData
  • Kind: organization
  • Email: support@opencagedata.com
  • Location: Worldwide

easy, affordable, worldwide geocoding API and geosearch made with open data

GitHub Events

Total
  • Watch event: 6
  • Push event: 13
  • Pull request event: 7
  • Fork event: 4
  • Create event: 9
Last Year
  • Watch event: 6
  • Push event: 13
  • Pull request event: 7
  • Fork event: 4
  • Create event: 9

Committers

Last synced: 9 months ago

All Time
  • Total Commits: 170
  • Total Committers: 11
  • Avg Commits per committer: 15.455
  • Development Distribution Score (DDS): 0.547
Past Year
  • Commits: 24
  • Committers: 2
  • Avg Commits per committer: 12.0
  • Development Distribution Score (DDS): 0.125
Top Committers
Name Email Commits
mtmail m****l@g****t 77
Rory McCann r****y@t****g 41
Ed Freyfogle f****e 24
Alex Balhatchet a****x@b****t 12
Sam Scully s****y@g****m 10
vicchi g****y@v****g 1
Savio Dimatteo d****o@g****m 1
Jeremy Fleischman j****n@g****m 1
CrazyPython C****n 1
Jim Hagan j****m@l****m 1
David Lowe d****l@l****m 1
Committer Domains (Top 20 + Academic)
lokku.com: 1 locately.com: 1 vicchi.org: 1 balhatchet.net: 1 technomancy.org: 1 gmx.net: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 16
  • Total pull requests: 48
  • Average time to close issues: 4 months
  • Average time to close pull requests: 18 days
  • Total issue authors: 14
  • Total pull request authors: 9
  • Average comments per issue: 1.88
  • Average comments per pull request: 0.38
  • Merged pull requests: 47
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 0
  • Pull requests: 11
  • Average time to close issues: N/A
  • Average time to close pull requests: 4 days
  • Issue authors: 0
  • Pull request authors: 3
  • Average comments per issue: 0
  • Average comments per pull request: 0.09
  • Merged pull requests: 10
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • CrazyPython (3)
  • JimHagan (1)
  • theconor (1)
  • DenisCarriere (1)
  • Dinges28 (1)
  • nate-bush (1)
  • mtmail (1)
  • ZribeDev (1)
  • borbash (1)
  • lemious (1)
  • ghost (1)
  • VGalata (1)
  • shubham-kumarpandey (1)
  • shihas1991 (1)
Pull Request Authors
  • mtmail (33)
  • sbscully (15)
  • amandasaurus (2)
  • jfly (1)
  • CrazyPython (1)
  • riquedev (1)
  • darksmo (1)
  • kaoru (1)
  • JimHagan (1)
Top Labels
Issue Labels
Pull Request Labels

Packages

  • Total packages: 3
  • Total downloads:
    • pypi 64,579 last-month
  • Total dependent packages: 6
    (may contain duplicates)
  • Total dependent repositories: 115
    (may contain duplicates)
  • Total versions: 26
  • Total maintainers: 2
pypi.org: opencage

Wrapper module for the OpenCage Geocoder API

  • Versions: 24
  • Dependent Packages: 6
  • Dependent Repositories: 115
  • Downloads: 64,579 Last month
Rankings
Dependent repos count: 1.4%
Dependent packages count: 1.4%
Downloads: 1.8%
Average: 4.4%
Stargazers count: 8.5%
Forks count: 8.7%
Maintainers (2)
opencage mtmail
Last synced: 6 months ago
proxy.golang.org: github.com/opencagedata/python-opencage-geocoder
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.4%
Average: 5.6%
Dependent repos count: 5.8%
Last synced: 6 months ago
proxy.golang.org: github.com/OpenCageData/python-opencage-geocoder
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.4%
Average: 5.6%
Dependent repos count: 5.8%
Last synced: 6 months ago

Dependencies

setup.py pypi
  • Requests >=2.2.0
  • backoff >=1.10.0
  • pyopenssl >=0.15.1