{"id":27019320,"url":"https://github.com/opencagedata/python-opencage-geocoder","last_synced_at":"2025-12-16T14:03:57.061Z","repository":{"id":17213578,"uuid":"19982210","full_name":"OpenCageData/python-opencage-geocoder","owner":"OpenCageData","description":"Python module to access the OpenCage geocoding API","archived":false,"fork":false,"pushed_at":"2025-05-26T20:30:44.000Z","size":397,"stargazers_count":84,"open_issues_count":2,"forks_count":26,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-10-20T04:57:04.795Z","etag":null,"topics":["geocoding","opencage","opencage-geocoder","python"],"latest_commit_sha":null,"homepage":"https://opencagedata.com/tutorials/geocode-in-python","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCageData.png","metadata":{"files":{"readme":"README.md","changelog":"Changes.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-05-20T13:38:53.000Z","updated_at":"2025-10-19T01:20:00.000Z","dependencies_parsed_at":"2023-02-12T12:50:17.533Z","dependency_job_id":"ae93ea88-ae54-4a66-8832-812e858adbfc","html_url":"https://github.com/OpenCageData/python-opencage-geocoder","commit_stats":{"total_commits":141,"total_committers":12,"mean_commits":11.75,"dds":0.624113475177305,"last_synced_commit":"4792173832e3b88b25aad95488c83c725fbb13be"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/OpenCageData/python-opencage-geocoder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fpython-opencage-geocoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fpython-opencage-geocoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fpython-opencage-geocoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fpython-opencage-geocoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCageData","download_url":"https://codeload.github.com/OpenCageData/python-opencage-geocoder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCageData%2Fpython-opencage-geocoder/sbom","scorecard":{"id":105171,"data":{"date":"2025-08-11","repo":{"name":"github.com/OpenCageData/python-opencage-geocoder","commit":"d143d5745a9c13208ec7782f1a8e52597ddd7537"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.4,"checks":[{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":2,"reason":"Found 6/30 approved changesets -- score normalized to 2","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":3,"reason":"4 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/OpenCageData/python-opencage-geocoder/build.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/OpenCageData/python-opencage-geocoder/build.yml/master?enable=pin","Warn: pipCommand not pinned by hash: vagrant-provision.sh:10","Warn: pipCommand not pinned by hash: vagrant-provision.sh:11","Warn: downloadThenRun not pinned by hash: vagrant-provision.sh:15","Warn: pipCommand not pinned by hash: .github/workflows/build.yml:32","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 pipCommand dependencies pinned","Info:   0 out of   1 downloadThenRun dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":9,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 11 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-15T10:58:06.246Z","repository_id":17213578,"created_at":"2025-08-15T10:58:06.246Z","updated_at":"2025-08-15T10:58:06.246Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27765951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geocoding","opencage","opencage-geocoder","python"],"created_at":"2025-04-04T17:27:11.947Z","updated_at":"2025-12-16T14:03:57.000Z","avatar_url":"https://github.com/OpenCageData.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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[![PyPI version](https://badge.fury.io/py/opencage.svg)](https://badge.fury.io/py/opencage)\n[![Downloads](https://pepy.tech/badge/opencage/month)](https://pepy.tech/project/opencage)\n[![Versions](https://img.shields.io/pypi/pyversions/opencage)](https://pypi.org/project/opencage/)\n![GitHub contributors](https://img.shields.io/github/contributors/opencagedata/python-opencage-geocoder)\n[![Build Status](https://github.com/OpenCageData/python-opencage-geocoder/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/OpenCageData/python-opencage-geocoder/actions/workflows/build.yml)\n![Mastodon Follow](https://img.shields.io/mastodon/follow/109287663468501769?domain=https%3A%2F%2Fen.osm.town%2F\u0026style=social)\n\n## Tutorials\n\nYou can find a [comprehensive tutorial for using this module on the OpenCage site](https://opencagedata.com/tutorials/geocode-in-python).\n\nThere are two brief video tutorials on YouTube, one [covering forward geocoding](https://www.youtube.com/watch?v=9bXu8-LPr5c), one [covering reverse geocoding](https://www.youtube.com/watch?v=u-kkE4yA-z0).\n\nThe module installs an `opencage` CLI tool for geocoding files. Check `opencage --help` or the [CLI tutorial](https://opencagedata.com/tutorials/geocode-commandline).\n\n\n## Usage\n\nSupports Python 3.8 or newer. Starting opencage version 3.0 depends on asyncio package.\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.8 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### 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## Command-line batch geocoding\n\nUse `opencage forward` or `opencage reverse`\n\n```\nopencage forward --help\n\noptions:\n  -h, --help            show this help message and exit\n  --api-key API_KEY     Your OpenCage API key\n  --input FILENAME      Input file name\n  --output FILENAME     Output file name\n  --headers             If the first row should be treated as a header row\n  --input-columns       Comma-separated list of integers (default '1')\n  --add-columns         Comma-separated list of output columns (default 'lat,lng,_type,_category,country_code,country,state,county,_normalized_city,postcode,road,house_number,confidence,formatted,json,status')\n  --workers             Number of parallel geocoding requests (default 1)\n  --timeout             Timeout in seconds (default 10)\n  --retries             Number of retries (default 5)\n  --api-domain          API domain (default api.opencagedata.com)\n  --optional-api-params\n                        Extra parameters for each request (e.g. language=fr,no_dedupe=1)\n  --unordered           Allow the output lines to be in different order (can be faster)\n  --limit               Stop after this number of lines in the input\n  --dry-run             Read the input file but no geocoding\n  --no-progress         Display no progress bar\n  --quiet               No progress bar and no messages\n  --overwrite           Delete the output file first if it exists\n  --verbose             Display debug information for each request\n```\n\n\u003cimg src=\"batch-progress.gif\"/\u003e\n\n\n## Copyright \u0026 License\n\nThis software is copyright OpenCage GmbH.\nPlease see `LICENSE.txt`\n\n### Who is OpenCage GmbH?\n\n\u003ca href=\"https://opencagedata.com\"\u003e\u003cimg src=\"opencage_logo_300_150.png\"/\u003e\u003c/a\u003e\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencagedata%2Fpython-opencage-geocoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencagedata%2Fpython-opencage-geocoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencagedata%2Fpython-opencage-geocoder/lists"}