{"id":4683,"library":"pgeocode","title":"pgeocode","description":"pgeocode is a Python library for high-performance off-line querying of GPS coordinates, region name, and municipality name from postal codes. It also supports distance calculations between postal codes. The library utilizes the GeoNames database, covering 83 countries. The current version is 0.5.0. It has an active maintenance schedule with new releases that increment with feature additions and bug fixes.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/symerio/pgeocode","tags":["geocoding","postal codes","location","distance","offline","geonames"],"install":[{"cmd":"pip install pgeocode","lang":"bash","label":"Install pgeocode"}],"dependencies":[{"reason":"Required for data handling and the DataFrame output format.","package":"pandas","optional":false},{"reason":"Optional dependency for fuzzy search functionality in `Nominatim.query_location`.","package":"thefuzz","optional":true}],"imports":[{"symbol":"pgeocode","correct":"import pgeocode"},{"symbol":"Nominatim","correct":"from pgeocode import Nominatim"},{"symbol":"GeoDistance","correct":"from pgeocode import GeoDistance"}],"quickstart":{"code":"import pgeocode\nimport os\n\n# Set a temporary data directory for demonstration if desired\n# os.environ['PGEOCODE_DATA_DIR'] = '/tmp/pgeocode_data'\n\n# Initialize Nominatim for a specific country (e.g., France)\nnomi = pgeocode.Nominatim('fr')\n\n# Query a single postal code\nparis_13 = nomi.query_postal_code('75013')\nprint(f\"Paris 13 details:\\n{paris_13}\\n\")\n\n# Query multiple postal codes\nmultiple_cities = nomi.query_postal_code(['75013', '69006'])\nprint(f\"Multiple cities details:\\n{multiple_cities}\\n\")\n\n# Initialize GeoDistance for a specific country\ndist = pgeocode.GeoDistance('fr')\n\n# Calculate distance between two postal codes\ndistance_km = dist.query_postal_code('75013', '69006')\nprint(f\"Distance between 75013 and 69006: {distance_km:.2f} km\")\n\n# Example of using query_location (requires 'thefuzz' optional dependency for fuzzy matching)\n# If 'thefuzz' is not installed, it will perform exact matches.\n# To install: pip install \"pgeocode[fuzzy]\"\n# anti_data = nomi.query_location(\"Antibes\", top_k=3)\n# print(f\"Antibes locations:\\n{anti_data}\\n\")","lang":"python","description":"This quickstart demonstrates how to use `pgeocode.Nominatim` for querying postal code and location data, and `pgeocode.GeoDistance` for calculating distances between postal codes for a specified country. The data is downloaded and cached locally on first use. You can optionally set the `PGEOCODE_DATA_DIR` environment variable to control where the data is stored."},"warnings":[{"fix":"Ensure your Python environment is at version 3.10 or higher. Upgrade Python if necessary.","message":"The minimum required Python version has been updated. Version 0.4.0 required Python 3.8+, while the current version 0.5.0 requires Python 3.10+.","severity":"breaking","affected_versions":"0.4.x -> 0.5.0"},{"fix":"When passing a pandas Series to `query_postal_code`, convert it to a list using `.to_list()`. Example: `dist.query_postal_code(df['postal_code_1'].to_list(), df['postal_code_2'].to_list())`.","message":"`GeoDistance.query_postal_code` expects postal codes as Python lists when querying multiple codes, not NumPy arrays (e.g., directly from pandas Series).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the `PGEOCODE_DATA_DIR` environment variable to a desired writable directory before initializing `pgeocode` objects. For example: `os.environ['PGEOCODE_DATA_DIR'] = '/path/to/writable/cache'`.","message":"Data files for each country are downloaded and cached locally. By default, this cache is stored in `~/.cache/pgeocode/`. If this directory is not writable or needs to be controlled (e.g., in a containerized environment), downloads might fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `thefuzz` as an extra dependency if fuzzy search is desired: `pip install \"pgeocode[fuzzy]\"`.","message":"When `Nominatim.query_location` is used for fuzzy searching by place name, the optional `thefuzz` package is required. Without it, only exact matches will be performed.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}