pgeocode

邮政编码地理编码和距离计算

pgeocode是一个Python库，用于从邮政编码中高效离线查询GPS坐标、区域名称和市镇名称。支持邮政编码之间的距离以及一般距离查询。使用的GeoNames数据库包括83个国家的邮政编码。

目前，只支持同一国家内的查询。

有关更多文档，请参阅pgeocode.readthedocs.io。

安装

pgeocode需要Python 3.10+以及numpy和pandas包。它可以这样安装：

pip install pgeocode

快速入门

邮政编码查询

>>> 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

地点名称查询

>>> 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

距离计算

>>> 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])

地理编码格式

地理定位查询的结果是一个包含以下列的pandas.DataFrame：

• country_code：iso国家代码，2个字符
• postal_code：邮政编码
• place_name：地点名称（例如镇、市等）
• state_name：1级次级分区（州）
• state_code：1级次级分区（州）
• county_name：2级次级分区（县/省）
• county_code：2级次级分区（县/省）
• community_name：3级次级分区（社区）
• community_code：3级次级分区（社区）
• latitude：估计纬度（wgs84）
• longitude：估计经度（wgs84）
• accuracy：纬度/经度精度，从1=估计到6=中心点

配置和默认值

存储目录

默认为 ~/.cache/pgeocode，这是用于以后使用的下载数据所在的目录。可以通过环境变量 PGEOCODE_DATA_DIR 进行更改，例如：export PGEOCODE_DATA_DIR=/tmp/pgeocode_data。

数据源

数据源以列表形式提供在 pgeocode.DOWNLOAD_URL 变量中。默认值为：

DOWNLOAD_URL = [
    "https://download.geonames.org/export/zip/{country}.zip",
    "https://symerio.github.io/postal-codes-data/data/geonames/{country}.txt",
]

将按照从第一个到最后一个的顺序尝试数据源，直到找到一个可用的为止。在这里，第二个链接是第一个链接的镜像。

也可以通过第三方数据源扩展此变量，只要它们遵循相同的格式。例如，可以参考postal-codes-data 仓库中的数据文件示例。

许可证

pgeocode 包遵循 3-clause BSD 许可。

pgeocode 包由 Symerio 维护。

支持的国家

以下列出了 GeoNames 数据库中可用的国家列表，以及相应的国家代码：

安道尔（AD）、阿根廷（AR）、美属萨摩亚（AS）、奥地利（AT）、澳大利亚（AU）、奥兰群岛（AX）、阿塞拜疆（AZ）、孟加拉国（BD）、比利时（BE）、保加利亚（BG）、百慕大（BM）、巴西（BR）、白俄罗斯（BY）、加拿大（CA）、瑞士（CH）、智利（CL）、哥伦比亚（CO）、哥斯达黎加（CR）、塞浦路斯（CY）、捷克（CZ）、德国（DE）、丹麦（DK）、多米尼加共和国（DO）、阿尔及利亚（DZ）、爱沙尼亚（EE）、西班牙（ES）、芬兰（FI）、密克罗尼西亚联邦（FM）、法罗群岛（FO）、法国（FR）、大不列颠及北爱尔兰联合王国（GB）、法属圭亚那（GF）、根西岛（GG）、格陵兰（GL）、瓜德罗普（GP）、危地马拉（GT）、关岛（GU）、克罗地亚（HR）、海地（HT）、匈牙利（HU）、爱尔兰（IE）、马恩岛（IM）、印度（IN）、冰岛（IS）、意大利（IT）、泽西岛（JE）、日本（JP）、大韩民国（KR）、列支敦士登（LI）、斯里兰卡（LK）、立陶宛（LT）、卢森堡（LU）、拉脱维亚（LV）、摩纳哥（MC）、摩尔多瓦共和国（MD）、马绍尔群岛（MH）、前南斯拉夫共和国马其顿（MK）、北马里亚纳群岛（MP）、马提尼克（MQ）、马耳他（MT）、马拉维（MW）、墨西哥（MX）、马来西亚（MY）、新喀里多尼亚（NC）、荷兰（NL）、挪威（NO）、新西兰（NZ）、秘鲁（PE）、菲律宾（PH）、巴基斯坦（PK）、波兰（PL）、圣皮埃尔和密克隆（PM）、波多黎各（PR）、葡萄牙（PT）、帕劳（PW）、留尼汪（RE）、罗马尼亚（RO）、塞尔维亚（RS）、俄罗斯联邦（RU）、瑞典（SE）、新加坡（SG）、斯洛文尼亚（SI）、斯瓦尔巴群岛和扬马延岛（SJ）、斯洛伐克（SK）、圣马力诺（SM）、泰国（TH）、土耳其（TR）、乌克兰（UA）、美利坚合众国（US）、乌拉圭（UY）、梵蒂冈（VA）、美属维尔京群岛（VI）、瓦利斯和富图纳群岛（WF）、马约特（YT）、南非（ZA）

有关更多信息，请参阅 GeoNames 数据库。