| Name | pgeocode JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | Postal code geocoding |
| upload_time | 2024-04-13 06:46:07 |
| maintainer | None |
| docs_url | None |
| author | Roman Yurchak |
| requires_python | >=3.10 |
| license | BSD |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pgeocode
[](https://pypi.org/project/pgeocode/)
[](http://pgeocode.readthedocs.io/)
[](https://github.com/symerio/pgeocode/actions?query=branch%3Amaster+)
Postal code geocoding and distance calculations
pgeocode is a Python library for high performance off-line querying of
GPS coordinates, region name and municipality name from postal codes.
Distances between postal codes as well as general distance queries are
also supported. The used
[GeoNames](http://download.geonames.org/export/zip/) database includes
postal codes for 83 countries.
Currently, only queries within the same country are supported.
For additional documentation see
[pgeocode.readthedocs.io](https://pgeocode.readthedocs.io).
# Installation
pgeocode requires Python 3.10+ as well as `numpy` and `pandas` packages.
It can be installed with,
```
pip install pgeocode
```
# Quickstart
**Postal code queries**
```python
>>> import pgeocode
>>> nomi = pgeocode.Nominatim('fr')
>>> nomi.query_postal_code("75013")
postal_code 75013
country_code FR
place_name Paris 13
state_name Île-de-France
state_code 11
county_name Paris
county_code 75
community_name Paris
community_code 751
latitude 48.8322
longitude 2.3561
accuracy 5
>>> nomi.query_postal_code(["75013", "69006"])
postal_code place_name state_name latitude longitude
0 75013 Paris 13 Île-de-France 48.8322 2.3561
1 69006 Lyon 06 Auvergne-Rhône-Alpes 45.7679 4.8506
```
**Place name queries**
```python
>>> import pgeocode
>>> nomi = pgeocode.Nominatim('fr')
>>> nomi.query_location("Antibes", top_k=3)
country_code postal_code place_name state_name state_code ... community_name community_code latitude longitude accuracy
49553 FR 06160 Antibes Provence-Alpes-Côte d'Azur 93.0 ... Grasse 061 43.5858 7.1083 5
49787 FR 06600 Antibes Provence-Alpes-Côte d'Azur 93.0 ... Grasse 061 43.5858 7.1083 5
49788 FR 06601 CEDEX Antibes Provence-Alpes-Côte d'Azur 93.0 ... Grasse 061 43.5858 7.1083 5
>>> nomi.query_location("Straassborg", top_k=3, fuzzy_threshold=80)
country_code postal_code place_name state_name state_code ... community_name community_code latitude longitude accuracy
25461 FR 67000 Strasbourg Grand Est 44.0 ... Strasbourg 678 48.5839 7.7455 5
25462 FR 67001 CEDEX Strasbourg Grand Est 44.0 ... Strasbourg 678 48.5839 7.7455 5
25463 FR 67002 CEDEX Strasbourg Grand Est 44.0 ... Strasbourg 678 48.5839 7.7455 5
```
**Distance calculations**
```python
>>> dist = pgeocode.GeoDistance('fr')
>>> dist.query_postal_code("75013", "69006")
389.156
>>> dist.query_postal_code(["75013", "75014", "75015"], ["69006", "69005", "69004"])
array([ 389.15648697, 390.12577967, 390.49857655])
```
# Geocoding format
The result of a geo-localistion query is a `pandas.DataFrame` with the
following columns,
- `country_code`: iso country code, 2 characters
- `postal_code` : postal code
- `place_name` : place name (e.g. town, city etc)
- `state_name` : 1. order subdivision (state)
- `state_code` : 1. order subdivision (state)
- `county_name` : 2. order subdivision (county/province)
- `county_code` : 2. order subdivision (county/province)
- `community_name` : 3. order subdivision (community)
- `community_code` : 3. order subdivision (community)
- `latitude` : estimated latitude (wgs84)
- `longitude` : estimated longitude (wgs84)
- `accuracy` : accuracy of lat/lng from 1=estimated to 6=centroid
# Configuration and defaults
**Storage directory**
Defaults to `~/.cache/pgeocode`, it is the directory where data is
downloaded for later consumption. It can be changed using the
environment variable `PGEOCODE_DATA_DIR`, i.e.
`export PGEOCODE_DATA_DIR=/tmp/pgeocode_data`.
**Data sources**
Data sources are provided as a list in the `pgeocode.DOWNLOAD_URL`
variable. The default value is,
``` python
DOWNLOAD_URL = [
"https://download.geonames.org/export/zip/{country}.zip",
"https://symerio.github.io/postal-codes-data/data/geonames/{country}.txt",
]
```
Data sources are tried from first to last until one works. Here the
second link is a mirror of the first.
It is also possible to extend this variable with third party data
sources, as long as they follow the same format. See for instance
[postal-codes-data](https://github.com/symerio/postal-codes-data/tree/master/data/geonames)
repository for examples of data files.
# License
The pgeocode package is distributed under the 3-clause BSD license.
The pgeocode package is maintained by [Symerio](https://www.symerio.com).
# Supported countries
The list of countries available in the GeoNames database, with the
corresponding country codes, are given below,
Andorra (AD), Argentina (AR), American Samoa (AS), Austria (AT),
Australia (AU), Åland Islands (AX), Azerbaijan (AZ), Bangladesh (BD),
Belgium (BE), Bulgaria (BG), Bermuda (BM), Brazil (BR), Belarus (BY),
Canada (CA), Switzerland (CH), Chile (CL), Colombia (CO), Costa Rica
(CR), Cyprus (CY), Czechia (CZ), Germany (DE), Denmark (DK), Dominican
Republic (DO), Algeria (DZ), Estonia (EE), Spain (ES), Finland (FI),
Federated States of Micronesia (FM), Faroe Islands (FO), France (FR),
United Kingdom of Great Britain and Northern Ireland (GB), French Guiana
(GF), Guernsey (GG), Greenland (GL), Guadeloupe (GP), Guatemala (GT),
Guam (GU), Croatia (HR), Haiti (HT), Hungary (HU), Ireland (IE), Isle of
Man (IM), India (IN), Iceland (IS), Italy (IT), Jersey (JE), Japan (JP),
Republic of Korea (KR), Liechtenstein (LI), Sri Lanka (LK), Lithuania
(LT), Luxembourg (LU), Latvia (LV), Monaco (MC), Republic of Moldova
(MD), Marshall Islands (MH), The former Yugoslav Republic of Macedonia
(MK), Northern Mariana Islands (MP), Martinique (MQ), Malta (MT), Malawi
(MW), Mexico (MX), Malaysia (MY), New Caledonia (NC), Netherlands (NL),
Norway (NO), New Zealand (NZ), Peru (PE), Philippines (PH), Pakistan
(PK), Poland (PL), Saint Pierre and Miquelon (PM), Puerto Rico (PR),
Portugal (PT), Palau (PW), Réunion (RE), Romania (RO), Serbia (RS),
Russian Federation (RU), Sweden (SE), Singapore (SG), Slovenia (SI),
Svalbard and Jan Mayen Islands (SJ), Slovakia (SK), San Marino (SM),
Thailand (TH), Turkey (TR), Ukraine (UA), United States of America (US),
Uruguay (UY), Holy See (VA), United States Virgin Islands (VI), Wallis
and Futuna Islands (WF), Mayotte (YT), South Africa (ZA)
See [GeoNames database](http://download.geonames.org/export/zip/) for
more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "pgeocode",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Roman Yurchak",
"author_email": "roman.yurchak@symerio.com",
"download_url": "https://files.pythonhosted.org/packages/91/27/0de1f3890a4b8c1a7ca0bd913251c1f414bf49d8d5d85482a8b95ba6c738/pgeocode-0.5.0.tar.gz",
"platform": null,
"description": "# pgeocode\n\n[](https://pypi.org/project/pgeocode/)\n[](http://pgeocode.readthedocs.io/)\n[](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+ as well as `numpy` and `pandas` packages.\nIt can be installed with,\n\n```\npip install pgeocode\n```\n\n\n# Quickstart\n\n**Postal code queries**\n\n```python\n>>> import pgeocode\n\n>>> nomi = pgeocode.Nominatim('fr')\n>>> nomi.query_postal_code(\"75013\")\npostal_code 75013\ncountry_code FR\nplace_name Paris 13\nstate_name \u00cele-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>>> nomi.query_postal_code([\"75013\", \"69006\"])\n postal_code place_name state_name latitude longitude\n0 75013 Paris 13 \u00cele-de-France 48.8322 2.3561\n1 69006 Lyon 06 Auvergne-Rh\u00f4ne-Alpes 45.7679 4.8506\n```\n\n**Place name queries**\n\n```python\n>>> import pgeocode\n\n>>> nomi = pgeocode.Nominatim('fr')\n>>> 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\u00f4te d'Azur 93.0 ... Grasse 061 43.5858 7.1083 5\n49787 FR 06600 Antibes Provence-Alpes-C\u00f4te d'Azur 93.0 ... Grasse 061 43.5858 7.1083 5\n49788 FR 06601 CEDEX Antibes Provence-Alpes-C\u00f4te d'Azur 93.0 ... Grasse 061 43.5858 7.1083 5\n\n>>> 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>>> dist = pgeocode.GeoDistance('fr')\n>>> dist.query_postal_code(\"75013\", \"69006\")\n389.156\n>>> 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), \u00c5land 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\u00e9union (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",
"bugtrack_url": null,
"license": "BSD",
"summary": "Postal code geocoding",
"version": "0.5.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2662ff5ac22710794b01a6021fb681189f43e8bff224e100cb590ced4c545f7b",
"md5": "36eea472a082c51348319c6bae7ef950",
"sha256": "de24a5997524ef557a29a1b22443cc1bf5d02c098e0c7a8dd9ea9caf01a6a72a"
},
"downloads": -1,
"filename": "pgeocode-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36eea472a082c51348319c6bae7ef950",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9772,
"upload_time": "2024-04-13T06:46:05",
"upload_time_iso_8601": "2024-04-13T06:46:05.157572Z",
"url": "https://files.pythonhosted.org/packages/26/62/ff5ac22710794b01a6021fb681189f43e8bff224e100cb590ced4c545f7b/pgeocode-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "91270de1f3890a4b8c1a7ca0bd913251c1f414bf49d8d5d85482a8b95ba6c738",
"md5": "95768a947cb2f9a161bcaddd769fb732",
"sha256": "37d6caf74e9f2b1e69762811953df5b43fe7f1806833c83bf85a60dd784dff9e"
},
"downloads": -1,
"filename": "pgeocode-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "95768a947cb2f9a161bcaddd769fb732",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10473,
"upload_time": "2024-04-13T06:46:07",
"upload_time_iso_8601": "2024-04-13T06:46:07.060643Z",
"url": "https://files.pythonhosted.org/packages/91/27/0de1f3890a4b8c1a7ca0bd913251c1f414bf49d8d5d85482a8b95ba6c738/pgeocode-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-13 06:46:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pgeocode"
}
