{"id":14036835,"url":"https://github.com/symerio/pgeocode","last_synced_at":"2025-07-27T04:32:29.055Z","repository":{"id":41282889,"uuid":"116300991","full_name":"symerio/pgeocode","owner":"symerio","description":"Postal code geocoding and distance calculation","archived":false,"fork":false,"pushed_at":"2024-04-13T06:45:22.000Z","size":73,"stargazers_count":219,"open_issues_count":17,"forks_count":55,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-14T05:36:45.954Z","etag":null,"topics":["geocoding","geolocation","geonames","postal-code","zipcode"],"latest_commit_sha":null,"homepage":"https://pgeocode.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/symerio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2018-01-04T19:47:58.000Z","updated_at":"2024-04-16T08:34:06.340Z","dependencies_parsed_at":"2024-04-16T08:33:57.074Z","dependency_job_id":null,"html_url":"https://github.com/symerio/pgeocode","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/symerio%2Fpgeocode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/symerio%2Fpgeocode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/symerio%2Fpgeocode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/symerio%2Fpgeocode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/symerio","download_url":"https://codeload.github.com/symerio/pgeocode/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":214982087,"owners_count":15811653,"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","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","geolocation","geonames","postal-code","zipcode"],"created_at":"2024-08-12T03:02:16.014Z","updated_at":"2025-07-27T04:32:29.035Z","avatar_url":"https://github.com/symerio.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# pgeocode\n\n[![pypi](https://img.shields.io/pypi/v/pgeocode.svg)](https://pypi.org/project/pgeocode/)\n[![rdfd](https://readthedocs.org/projects/pgeocode/badge/?version=latest)](http://pgeocode.readthedocs.io/)\n[![GHactions](https://github.com/symerio/pgeocode/workflows/Test/badge.svg)](https://github.com/symerio/pgeocode/actions?query=branch%3Amaster+)\n\nPostal code geocoding and distance calculations\n\npgeocode is a Python library for high performance off-line querying of\nGPS coordinates, region name and municipality name from postal codes.\nDistances between postal codes as well as general distance queries are\nalso supported. The used\n[GeoNames](http://download.geonames.org/export/zip/) database includes\npostal codes for 83 countries.\n\nCurrently, only queries within the same country are supported.\n\nFor additional documentation see\n[pgeocode.readthedocs.io](https://pgeocode.readthedocs.io).\n\n# Installation\n\npgeocode requires Python 3.10+ and the pandas 1.5.0+ package.\nIt can be installed with,\n\n```\npip install pgeocode\n```\n\n\n# Quickstart\n\n**Postal code queries**\n\n```python\n\u003e\u003e\u003e import pgeocode\n\n\u003e\u003e\u003e nomi = pgeocode.Nominatim('fr')\n\u003e\u003e\u003e nomi.query_postal_code(\"75013\")\npostal_code               75013\ncountry_code                 FR\nplace_name             Paris 13\nstate_name        Île-de-France\nstate_code                   11\ncounty_name               Paris\ncounty_code                  75\ncommunity_name            Paris\ncommunity_code              751\nlatitude                48.8322\nlongitude                2.3561\naccuracy                      5\n\n\u003e\u003e\u003e nomi.query_postal_code([\"75013\", \"69006\"])\n      postal_code place_name            state_name  latitude  longitude\n0       75013   Paris 13         Île-de-France   48.8322     2.3561\n1       69006    Lyon 06  Auvergne-Rhône-Alpes   45.7679     4.8506\n```\n\n**Place name queries**\n\n```python\n\u003e\u003e\u003e import pgeocode\n\n\u003e\u003e\u003e nomi = pgeocode.Nominatim('fr')\n\u003e\u003e\u003e nomi.query_location(\"Antibes\", top_k=3)\n    country_code  postal_code place_name                  state_name  state_code  ... community_name community_code latitude longitude  accuracy\n49553           FR        06160    Antibes  Provence-Alpes-Côte d'Azur        93.0  ...         Grasse            061  43.5858    7.1083         5\n49787           FR        06600    Antibes  Provence-Alpes-Côte d'Azur        93.0  ...         Grasse            061  43.5858    7.1083         5\n49788           FR  06601 CEDEX    Antibes  Provence-Alpes-Côte d'Azur        93.0  ...         Grasse            061  43.5858    7.1083         5\n\n\u003e\u003e\u003e nomi.query_location(\"Straassborg\", top_k=3, fuzzy_threshold=80)\n    country_code  postal_code  place_name state_name  state_code  ... community_name community_code latitude longitude  accuracy\n25461           FR        67000  Strasbourg  Grand Est        44.0  ...     Strasbourg            678  48.5839    7.7455         5\n25462           FR  67001 CEDEX  Strasbourg  Grand Est        44.0  ...     Strasbourg            678  48.5839    7.7455         5\n25463           FR  67002 CEDEX  Strasbourg  Grand Est        44.0  ...     Strasbourg            678  48.5839    7.7455         5\n```\n\n**Distance calculations**\n\n```python\n\u003e\u003e\u003e dist = pgeocode.GeoDistance('fr')\n\u003e\u003e\u003e dist.query_postal_code(\"75013\", \"69006\")\n389.156\n\u003e\u003e\u003e dist.query_postal_code([\"75013\", \"75014\", \"75015\"], [\"69006\", \"69005\", \"69004\"])\narray([ 389.15648697,  390.12577967,  390.49857655])\n```\n\n# Geocoding format\n\nThe result of a geo-localistion query is a `pandas.DataFrame` with the\nfollowing columns,\n\n-   `country_code`: iso country code, 2 characters\n-   `postal_code` : postal code\n-   `place_name` : place name (e.g. town, city etc)\n-   `state_name` : 1. order subdivision (state)\n-   `state_code` : 1. order subdivision (state)\n-   `county_name` : 2. order subdivision (county/province)\n-   `county_code` : 2. order subdivision (county/province)\n-   `community_name` : 3. order subdivision (community)\n-   `community_code` : 3. order subdivision (community)\n-   `latitude` : estimated latitude (wgs84)\n-   `longitude` : estimated longitude (wgs84)\n-   `accuracy` : accuracy of lat/lng from 1=estimated to 6=centroid\n\n# Configuration and defaults\n\n**Storage directory**\n\nDefaults to `~/.cache/pgeocode`, it is the directory where data is\ndownloaded for later consumption. It can be changed using the\nenvironment variable `PGEOCODE_DATA_DIR`, i.e.\n`export PGEOCODE_DATA_DIR=/tmp/pgeocode_data`.\n\n**Data sources**\n\nData sources are provided as a list in the `pgeocode.DOWNLOAD_URL`\nvariable. The default value is,\n\n``` python\nDOWNLOAD_URL = [\n    \"https://download.geonames.org/export/zip/{country}.zip\",\n    \"https://symerio.github.io/postal-codes-data/data/geonames/{country}.txt\",\n]\n```\n\nData sources are tried from first to last until one works. Here the\nsecond link is a mirror of the first.\n\nIt is also possible to extend this variable with third party data\nsources, as long as they follow the same format. See for instance\n[postal-codes-data](https://github.com/symerio/postal-codes-data/tree/master/data/geonames)\nrepository for examples of data files.\n\n# License\n\nThe pgeocode package is distributed under the 3-clause BSD license.\n\nThe pgeocode package is maintained by [Symerio](https://www.symerio.com).\n\n# Supported countries\n\nThe list of countries available in the GeoNames database, with the\ncorresponding country codes, are given below,\n\nAndorra (AD), Argentina (AR), American Samoa (AS), Austria (AT),\nAustralia (AU), Åland Islands (AX), Azerbaijan (AZ), Bangladesh (BD),\nBelgium (BE), Bulgaria (BG), Bermuda (BM), Brazil (BR), Belarus (BY),\nCanada (CA), Switzerland (CH), Chile (CL), Colombia (CO), Costa Rica\n(CR), Cyprus (CY), Czechia (CZ), Germany (DE), Denmark (DK), Dominican\nRepublic (DO), Algeria (DZ), Estonia (EE), Spain (ES), Finland (FI),\nFederated States of Micronesia (FM), Faroe Islands (FO), France (FR),\nUnited Kingdom of Great Britain and Northern Ireland (GB), French Guiana\n(GF), Guernsey (GG), Greenland (GL), Guadeloupe (GP), Guatemala (GT),\nGuam (GU), Croatia (HR), Haiti (HT), Hungary (HU), Ireland (IE), Isle of\nMan (IM), India (IN), Iceland (IS), Italy (IT), Jersey (JE), Japan (JP),\nRepublic of Korea (KR), Liechtenstein (LI), Sri Lanka (LK), Lithuania\n(LT), Luxembourg (LU), Latvia (LV), Monaco (MC), Republic of Moldova\n(MD), Marshall Islands (MH), The former Yugoslav Republic of Macedonia\n(MK), Northern Mariana Islands (MP), Martinique (MQ), Malta (MT), Malawi\n(MW), Mexico (MX), Malaysia (MY), New Caledonia (NC), Netherlands (NL),\nNorway (NO), New Zealand (NZ), Peru (PE), Philippines (PH), Pakistan\n(PK), Poland (PL), Saint Pierre and Miquelon (PM), Puerto Rico (PR),\nPortugal (PT), Palau (PW), Réunion (RE), Romania (RO), Serbia (RS),\nRussian Federation (RU), Sweden (SE), Singapore (SG), Slovenia (SI),\nSvalbard and Jan Mayen Islands (SJ), Slovakia (SK), San Marino (SM),\nThailand (TH), Turkey (TR), Ukraine (UA), United States of America (US),\nUruguay (UY), Holy See (VA), United States Virgin Islands (VI), Wallis\nand Futuna Islands (WF), Mayotte (YT), South Africa (ZA)\n\nSee [GeoNames database](http://download.geonames.org/export/zip/) for\nmore information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsymerio%2Fpgeocode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsymerio%2Fpgeocode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsymerio%2Fpgeocode/lists"}