placekey-notebooks

This repository includes tutorials, such as Jupyter notebooks, Google Sheets guides and more, showcasing the features of the Placekey, the Placekey API, Placekey Python library and an expanse of no-code tools.

For more details about Placekey, visit the Placekey website.

Setup

1. Clone this repo and install dependencies. requirements.txt is hash-pinned (all transitive deps locked with sha256 hashes) and generated from requirements.in. Pip verifies hashes automatically:

   pip install -r requirements.txt

   To bump versions, edit requirements.in then regenerate with uv (universal mode, so the lockfile works across macOS + Linux without platform-specific drift):

   uv pip compile --universal --python-version 3.11 --generate-hashes \
       --output-file=requirements.txt requirements.in

   Dependabot raises weekly PRs to update pinned versions + hashes (see .github/dependabot.yml). Major-version bumps are capped in both requirements.in and dependabot.yml's ignore: block; to take one, raise the cap in both files and regenerate. A companion workflow (dependabot-lockfile.yml) auto-regenerates requirements.txt with uv after each Dependabot pip PR so hashes stay coherent across transitives.

2. Get a Placekey API key — sign up at placekey.io.

3. Provide the key to the notebooks without pasting it into a cell. Pick one:

   • Environment variable (recommended):

     export PLACEKEY_API_KEY="your-key-here"
     jupyter lab

   • .env file (auto-loaded by python-dotenv): copy .env.example to .env and fill it in. .env is gitignored.
   • Interactive prompt: if neither of the above is set, the API notebooks fall back to getpass.getpass() and will prompt you at run time.

   Never commit API keys. .gitignore excludes .env, *.key, and *_api_key*, and CI runs a secret scan on every push.

Tutorials

Python

• Joining POI datasets with Placekey: [tutorial], [colab notebook]
• Joining POI and non-POI datasets with Placekey: [tutorial], [colab notebook]
• How to Clean and Deduplicate Addresses ("De-Duping"): [tutorial], [colab notebook]

Google Sheets with Placekey for Google Sheets

• Using Placekey without Addresses (Latitude and Longitude Only): [tutorial]
• Using Placekey to Deal with Multiple Points of Interest at a Single Address: [tutorial]

ArcGIS with AGS_placekey

• Address Matching without a Geocoder: [tutorial]

Using the placekey-py Python library

Placekey API Utilities in placekey-py

• Calling Single Placekey Endpoint: [notebook], [colab notebook]
• Calling Bulk Placekey Endpoint: [notebook], [colab notebook]

Spatial Tooling for Placekey in placekey-py

• Basic Spatial Functionality of Placekey: [notebook]
• Advanced Spatial Functionality of Placekey: [notebook]

Security

• API keys are read from PLACEKEY_API_KEY or prompted interactively — never hardcode them in cells.
• Dependencies in requirements.txt are hash-pinned (sha256) and verified by pip on install. Range specs live in requirements.in; Dependabot opens weekly bump PRs.
• CI runs on every push and pull request:
  • gitleaks — secret scanning
  • Notebook hygiene check — blocks committed personal paths (/Users/, /home/) and API-key literals in cell sources
  • nbmake — executes the key-free notebooks (basic_functionality, advanced_functionality)

If you find a security issue, please open a private report via GitHub Security Advisories.