{"id":14529728,"url":"https://github.com/Placekey/placekey-py","last_synced_at":"2025-09-02T00:32:17.705Z","repository":{"id":51377965,"uuid":"299217830","full_name":"Placekey/placekey-py","owner":"Placekey","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-24T22:09:44.000Z","size":3113,"stargazers_count":62,"open_issues_count":7,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-04T10:55:29.165Z","etag":null,"topics":["api","api-client","conversion","distance","geospatial","h3","placekey","placekey-api","pypi"],"latest_commit_sha":null,"homepage":"https://placekey.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Placekey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-28T07:00:33.000Z","updated_at":"2025-05-31T14:19:25.000Z","dependencies_parsed_at":"2023-02-07T23:01:28.207Z","dependency_job_id":"aa5a504a-3201-4646-ac76-d67e56552178","html_url":"https://github.com/Placekey/placekey-py","commit_stats":{"total_commits":32,"total_committers":5,"mean_commits":6.4,"dds":0.5,"last_synced_commit":"faca8db46068dda9393b05984dbe7c63ec31209e"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/Placekey/placekey-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Placekey%2Fplacekey-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Placekey%2Fplacekey-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Placekey%2Fplacekey-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Placekey%2Fplacekey-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Placekey","download_url":"https://codeload.github.com/Placekey/placekey-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Placekey%2Fplacekey-py/sbom","scorecard":{"id":110569,"data":{"date":"2025-08-11","repo":{"name":"github.com/Placekey/placekey-py","commit":"4615ebb6ab046267ff0c198b2b1c06da3587cd2a"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4,"checks":[{"name":"Code-Review","score":0,"reason":"Found 1/30 approved changesets -- score normalized to 0","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":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"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":"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":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: topLevel 'contents' permission set to 'read': .github/workflows/build-and-deploy-release-pypi.yml:9","Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/ossar-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/python-package.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":"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-and-deploy-release-pypi.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/build-and-deploy-release-pypi.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-and-deploy-release-pypi.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/build-and-deploy-release-pypi.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:52: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/codeql-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ossar-analysis.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/ossar-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ossar-analysis.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/ossar-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ossar-analysis.yml:47: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/ossar-analysis.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/python-package.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-package.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/Placekey/placekey-py/python-package.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/build-and-deploy-release-pypi.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/python-package.yml:21","Warn: pipCommand not pinned by hash: .github/workflows/python-package.yml:22","Warn: pipCommand not pinned by hash: .github/workflows/python-package.yml:23","Info:   0 out of  11 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 pipCommand 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":"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":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"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":"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":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"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 'main'"],"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":9,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 17 commits out of 20 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-15T12:07:17.366Z","repository_id":51377965,"created_at":"2025-08-15T12:07:17.366Z","updated_at":"2025-08-15T12:07:17.366Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273213684,"owners_count":25065058,"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-09-01T02:00:09.058Z","response_time":120,"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":["api","api-client","conversion","distance","geospatial","h3","placekey","placekey-api","pypi"],"created_at":"2024-09-05T00:01:01.957Z","updated_at":"2025-09-02T00:32:17.688Z","avatar_url":"https://github.com/Placekey.png","language":"Python","funding_links":[],"categories":["Code"],"sub_categories":["Python Code, Tools, Tutorials"],"readme":"\n# Placekey-py\n\n  \n\n[![PyPI version](https://badge.fury.io/py/placekey.svg)](https://badge.fury.io/py/placekey)\n\n[![PyPI downloads](https://img.shields.io/pypi/dm/placekey)](https://pypistats.org/packages/placekey)\n\n[![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n  \n\nA Python library for working with [Placekeys](https://placekey.io). Documentation for this package can be found [here](https://placekey.github.io/placekey-py/), and documentation for the Placekey service API can be found [here](https://docs.placekey.io/). The Plackey design specification is available [here](https://docs.placekey.io/Placekey_Technical_White_Paper.pdf). The details in Placekey encoding is [here](https://docs.placekey.io/Placekey_Encoding_Specification%20White_Paper.pdf). We welcome your feedback.\n\n  \n\n## Installation\n\n  \n\nThis package can be installed from [PyPI](https://pypi.org/project/placekey/) by\n\n  \n\n```shell script\n\npip  install  placekey\n\n```\n\n  \n\nMacOS Big Sur may need to run `brew install geos` if the installation of the `shapely` dependency fails.\n\n  \n\n## Usage\n\n  \n\nThe basic functionality of the Placekey library is conversion between Placekeys and latitude-longitude coordinates.\n\n  \n\n```python\n\n\u003e\u003e\u003e import placekey as pk\n\n\u003e\u003e\u003e lat, long = 0.0, 0.0\n\n\u003e\u003e\u003e pk.geo_to_placekey(lat, long)\n\n'@dvt-smp-tvz'\n\n```\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.placekey_to_geo('@dvt-smp-tvz')\n\n(0.00018033323813810344, -0.00018985758738881587)\n\n```\n\n  \n\nThe library also allows for conversion between Placekeys and [H3 indices](https://github.com/uber/h3-py).\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.placekey_to_h3('@dvt-smp-tvz')\n\n'8a754e64992ffff'\n\n```\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.h3_to_placekey('8a754e64992ffff')\n\n'@dvt-smp-tvz'\n\n```\n\n  \n\nThe distance in meters between two Placekeys can be found with the following function.\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.placekey_distance('@dvt-smp-tvz', '@5vg-7gq-tjv')\n\n12795124.895573696\n\n```\n\n  \n\nAn upper bound on the maximal distance in meters between two Placekeys based on the length of their shared prefix is provided by `placekey.get_prefix_distance_dict()`.\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.get_prefix_distance_dict()\n\n{0: 20040000.0,\n\n1: 20040000.0,\n\n2: 2777000.0,\n\n3: 1065000.0,\n\n4: 152400.0,\n\n5: 21770.0,\n\n6: 8227.0,\n\n7: 1176.0,\n\n8: 444.3,\n\n9: 63.47}\n\n```\n\n  \n\nPlacekeys found in a data set can be partially validated by\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.placekey_format_is_valid('222-227@dvt-smp-tvz')\n\nTrue\n\n```\n\n  \n\n```python\n\n\u003e\u003e\u003e pk.placekey_format_is_valid('@123-456-789')\n\nFalse\n\n```\n\nYou can now access the locations of placekey’s free datasets in S3 using placekey-py! Use these two functions:\n\n  \n\n```python\n\nprint(pk.list_free_datasets())\nprint(pk.return_free_datasets_location_by_name('chipotle-locations'))\n\n```\n\n  \n\n1. List Free Datasets: Returns a list of all names of Placekey’s available free datasets\n\n2. Return Free Datasets Location By Name: Using one of the names from List Free Datasets above, returns the publicly accessible S3 URI of said dataset.\n\n  \n\nYou can use these locations to download files programmatically (with boto3) or directly in Spark.\n\n## API Client\n\n  \n\nThis package also includes a client for the Placekey API. The methods in the client are automatically rate limited.\n\n  \n\n```python\n\n\u003e\u003e\u003e from placekey.api import PlacekeyAPI\n\n\u003e\u003e\u003e placekey_api_key = \"...\"\n\n\u003e\u003e\u003e pk_api = PlacekeyAPI(placekey_api_key)\n\n```\n\n  \n\nThe `PlacekeyAPI.lookup_placekey` method can be used to lookup the Placekey for a single place.\n\n  \n\n```python\n\n\u003e\u003e\u003e pk_api.lookup_placekey(latitude=37.7371, longitude=-122.44283)\n\n{'query_id': '0', 'placekey': '@5vg-82n-kzz'}\n\n```\n\n  \n\n```python\n\n\u003e\u003e\u003e place = {\n\n\u003e\u003e\u003e \"location_name\": \"Twin Peaks Petroleum\",\n\n\u003e\u003e\u003e \"street_address\": \"598 Portola Dr\",\n\n\u003e\u003e\u003e \"city\": \"San Francisco\",\n\n\u003e\u003e\u003e \"region\": \"CA\",\n\n\u003e\u003e\u003e \"postal_code\": \"94131\",\n\n\u003e\u003e\u003e \"iso_country_code\": \"US\"\n\n\u003e\u003e\u003e }\n\n\u003e\u003e\u003e pk_api.lookup_placekey(**place, fields=\"building_placekey\",\"address_placekey\",\"confidence_score\",\"gers\", \"address_confidence_score\"])\n\n{\n'query_id': '0', \n'placekey': '227-223@5vg-82n-pgk', \n'address_placekey': '227@5vg-82n-pgk', \n'building_placekey': '227@5vg-82n-pgk', \n'confidence_score': 'HIGH', \n'address_confidence_score': 'HIGH', \n'gers': None\n}\n\n```\n\n  \n\nThe `PlacekeyAPI.lookup_placekeys` method can be used to lookup Placekeys for multiple places.\n\n  \n\n```python\n\n\u003e\u003e\u003e places = [\n\n\u003e\u003e\u003e {\n\n\u003e\u003e\u003e \"street_address\": \"1543 Mission Street, Floor 3\",\n\n\u003e\u003e\u003e \"city\": \"San Francisco\",\n\n\u003e\u003e\u003e \"region\": \"CA\",\n\n\u003e\u003e\u003e \"postal_code\": \"94105\",\n\n\u003e\u003e\u003e \"iso_country_code\": \"US\"\n\n\u003e\u003e\u003e },\n\n\u003e\u003e\u003e {\n\n\u003e\u003e\u003e \"query_id\": \"thisqueryidaloneiscustom\",\n\n\u003e\u003e\u003e \"location_name\": \"Twin Peaks Petroleum\",\n\n\u003e\u003e\u003e \"street_address\": \"598 Portola Dr\",\n\n\u003e\u003e\u003e \"city\": \"San Francisco\",\n\n\u003e\u003e\u003e \"region\": \"CA\",\n\n\u003e\u003e\u003e \"postal_code\": \"94131\",\n\n\u003e\u003e\u003e \"iso_country_code\": \"US\"\n\n\u003e\u003e\u003e },\n\n\u003e\u003e\u003e {\n\n\u003e\u003e\u003e \"latitude\": 37.7371,\n\n\u003e\u003e\u003e \"longitude\": -122.44283\n\n\u003e\u003e\u003e }\n\n\u003e\u003e\u003e ]\n\n\u003e\u003e\u003e pk_api.lookup_placekeys(places, fields=[\"building_placekey\",\"address_placekey\",\"confidence_score\",\"gers\"])\n\n[{'query_id': 'place_0',\n\n'placekey': '0rsdbudq45@5vg-7gq-5mk',\n\n'address_placekey': '0rsdbudq45@5vg-7gq-5mk',\n\n'building_placekey': '22g@5vg-7gq-5mk',\n\n'confidence_score': 'HIGH',\n\n'gers': None},\n\n{'query_id': 'thisqueryidaloneiscustom',\n\n'placekey': '227-223@5vg-82n-pgk',\n\n'address_placekey': '227@5vg-82n-pgk',\n\n'building_placekey': '227@5vg-82n-pgk',\n\n'confidence_score': 'HIGH',\n\n'gers': None},\n\n{'query_id': 'place_2',\n\n'placekey': '@5vg-82n-kzz',\n\n'confidence_score': 'HIGH',\n\n'gers': None}]\n\n```\n\nYou can submit a Pandas dataset and have it come back wth Placekeys:\n```python\ndf  =  pd.DataFrame({\n\"address\": [\"1543 Mission Street, Floor 3\", \"598 Portola Dr\", None],\n\"city\": [\"San Francisco\", \"San Francisco\", None],\n\"region\": [\"CA\", \"CA\", None],\n\"postal\": [\"94105\", \"94131\", None],\n\"country\": [\"US\", \"US\", None],\n\"latitude\": [None, None, 37.7371],\n\"longitude\": [None, None, -122.44283]\n})\n\ncolumn_mappings  = {\n\"street_address\": \"address\",\n\"city\": \"city\",\n\"region\": \"region\",\n\"postal_code\": \"postal\",\n\"iso_country_code\": \"country\",\n\"latitude\": \"latitude\",\n\"longitude\": \"longitude\"\n}\n\ndf_with_placekeys  =  pk_api._placekey_pandas_df(df, column_mappings, fields=['address_placekey', 'address_confidence_score'])\nprint(df_with_placekeys)\n```\n ```\n                        address           city region postal country  latitude  longitude         placekey address_placekey\n0  1543 Mission Street, Floor 3  San Francisco     CA  94105      US       NaN        NaN  22g@5vg-7gq-5mk  22g@5vg-7gq-5mk\n1                598 Portola Dr  San Francisco     CA  94131      US       NaN        NaN  227@5vg-82n-pgk  227@5vg-82n-pgk\n2                          None           None   None   None    None   37.7371 -122.44283     @5vg-82n-kzz              NaN\n```\n\nYou can also join two pandas datasets together (placekey'd or not).\n```python\njoin  =  pk_api._join_pandas_df(df_1, column_mappings_1, df_2, column_mappings_2, on='address_placekey', how='outer')\n```\n\nFull details on how to query the API and how to get an API key can be found [here](https://docs.placekey.io/).\n\n  \n\n## Notebooks\n\n  \n\nJupyter notebooks demonstrating various Placekey functionality are contained in the [placekey-notebooks](https://github.com/Placekey/placekey-notebooks) repository.\n\n  \n\n## Support\n\n  \n\nThis package runs on Python 3.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPlacekey%2Fplacekey-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPlacekey%2Fplacekey-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPlacekey%2Fplacekey-py/lists"}