geocode-sqlite

从SQLite表中解码行

安装

使用pip或pipx安装此工具

# install inside a virtualenv
pip install geocode-sqlite

# install globally
pipx install geocode-sqlite

使用方法

假设你有一个包含地址的电子表格，并希望将这些位置映射出来。首先，创建一个SQLite数据库，并使用sqlite-utils将电子表格中的行插入到该数据库中。

sqlite-utils insert data.db data data.csv --csv

现在，使用OpenStreetMap的Nominatim地理编码器进行地理编码。

geocode-sqlite nominatim data.db data \
 --location="{address}, {city}, {state} {zip}" \
 --delay=1 \
 --user-agent="this-is-me"

在上面的命令中，你使用了Nominatim，它是免费的，并且只要求一个唯一的用户代理（--user-agent）。

这将连接到一个数据库（data.db）并从data表读取所有行（跳过任何已经填充了latitude和longitude列的行）。

你还告诉地理编码器如何从数据行中提取一个位置查询（--location），使用Python内置的字符串格式化，并设置请求速率限制（--delay）为每秒一个请求。

对于每个成功地理编码的行，将填充latitude和longitude。如果遇到错误或达到速率限制，请运行相同的查询并从上次离开的地方继续。

结果表布局可以使用datasette-cluster-map可视化。

在底层，这个包使用优秀的geopy库，该库稳定且经过充分的路试。如果你需要帮助理解特定地理编码器的选项，请参考geopy的文档。

支持的地理编码器

CLI目前支持以下地理编码器

• bing
• googlev3
• mapquest（和open-mapquest）
• mapbox
• nominatim
• opencage

添加新的地理编码器

1. 打开一个带有地理编码服务名称的问题作为票据标题的问题（示例）。在票据正文中放置任何值得注意的实现细节，如是否需要API密钥，以及如何获取。
2. 分叉存储库并添加一个地理编码器。
3. 向 Makefile 添加一个示例。如果有新的共享功能，请添加测试。

常见参数和选项

每个地理编码器都需要知道它正在处理的数据的位置。这些是前两个参数

• database：SQLite文件的路径，必须已经存在
• table：该数据库中存在且具有可地理编码数据的表名

从这里，我们有一组选项传递给每个地理编码器

• location：一个字符串格式，将扩展到每一行以构建完整的查询，进行地理编码
• delay：每次调用之间的延迟（某些服务需要此延迟）
• latitude：纬度列名
• longitude：经度列名
• geojson：将结果存储为GeoJSON，而不是纬度和经度列
• spatialite：将结果存储在SpatiaLite几何列中，而不是纬度和经度列
• raw：将原始地理编码结果存储在JSON列中

每个地理编码器都接受比这些更多的附加、特定参数，例如API密钥。再次提醒，geopy的文档 是一个极好的资源。

使用SpatiaLite

--spatialite标志将结果存储在几何列中，而不是latitude和longitude列。如果您正在进行其他GIS操作，例如使用空间索引，这很有用。有关更多信息，请参阅SpatiaLite烹饪书和函数列表。

捕获额外的地理编码数据

地理编码服务通常返回的数据不仅仅是坐标。这可能包括精度、标准化地址或其他上下文。可以使用--raw标志捕获这些数据。默认情况下，这将添加一个raw列，并将完整的地理编码响应作为JSON存储。如果您想重命名该列，请传递一个值，例如--raw custom_raw。

此响应对象的形状在不同服务之间会有所不同。您可以使用SQLite的内置JSON函数查询特定值。例如，这可以与Google的地理编码器一起工作

select
  json_extract(raw, '$.formatted_address') as address,
  json_extract(raw, '$.geometry.location_type') as location_type
from
  innout_test

请参阅每个地理编码服务文档，以了解响应中包含的内容。

Python API

命令行界面旨在支持每个地理编码器的最常见选项。要实现更精细的控制，请使用Python API。

与CLI一样，这假设您已经有一个SQLite数据库和位置数据表。

from geocode_sqlite import geocode_table
from geopy.geocoders import Nominatim

# create a geocoder instance, with some extra options
nominatim = Nominatim(user_agent="this-is-me", domain="nominatim.local.dev", scheme="http")

# assuming our database is in the same directory
count = geocode_table("data.db", "data", query_template="{address}, {city}, {state} {zip}")

# when it's done
print(f"Geocoded {count} rows")

任何geopy地理编码器都可以与Python API一起使用。

开发

要为此工具做出贡献，首先检出代码。然后创建一个新的虚拟环境

cd geocode-sqlite
python -m venv .venv
source .venv/bin/activate

或者如果您使用的是pipenv

pipenv shell

现在安装依赖项和测试

pip install -e '.[test]'

要运行测试

pytest

请记住，这个库主要是其他经过充分测试的项目之间的胶水代码，特别是：click、geopy 和 sqlite-utils。测试应确保这些部分正确结合在一起。我们可以假设这些部分本身已经正常工作。

为此，我们包含了一个测试地理编码器：geocode_sqlite.testing.DummyGeocoder。该地理编码器使用AllThePlaces提供的包含In-N-Out Burger位置的包含数据集与数据库一起工作。它像正常的GeoPy地理编码器一样工作，但只会使用包含的数据库返回In-N-Out位置的结果。