ohsome-py：用于 ohsome API 的 Python 客户端

ohsome -py包可帮助您使用ohsome API和 Python提取和分析 OpenStreetMap 历史数据。它处理对ohsome API的查询，并将其响应转换为Pandas和GeoPandas数据帧，以方便数据处理和分析。

ohsome API 为数据聚合、数据提取和贡献以分析 OSM 数据的历史提供了各种端点。查看ohsome API 的文档或通过教程开始了解如何使用ohsome-py。

安装

ohsome-py需要

• 蟒蛇> = 3.6
• geopandas >= 0.9.0
• pyproj >= 3.0.0
• 请求 >= 2.25.1

使用点子

您可以使用 pip 安装ohsome-py，它还将安装所有依赖项。

$ pip install ohsome

使用 Anaconda

ohsome-py还不能通过 Anaconda 获得。因此，如果您使用的是 Anaconda，请在使用 pip安装ohsome-py之前创建一个新的 anaconda 环境并安装所需的依赖项。请注意，在 anaconda 中使用 pip时可能会出现问题。为避免出现问题，请确保在新的 conda 环境中安装所有内容。

$ conda create -n ohsome python=3.8 geopandas">=0.9.0" requests">=2.25.1"
$ conda activate ohsome
$ pip install ohsome --no-deps

Jupyter Notebook 的依赖项

如果你想运行 Jupyter Notebook教程，你还需要安装jupyter，matplotlib例如

$ pip install jupyter matplotlib

用法

所有查询都由一个OhsomeClient对象处理，该对象还提供有关当前 ohsome API 实例的信息，例如start_timestamp并end_timestamp指示查询的最早和最晚可能日期。

from ohsome import OhsomeClient
client = OhsomeClient()
client.start_timestamp # --> '2007-10-08T00:00:00Z'
client.end_timestamp # --> '2021-01-23T03:00Z'

1. 数据聚合

示例：使用/elements/count端点标记为landuse=farmland的 OSM 方式数：

response = client.elements.count.post(bboxes=[8.625,49.3711,8.7334,49.4397],
				      time="2014-01-01",
				      filter="landuse=farmland and type:way")

端点 URL 的单个组件作为方法调用附加到OhsomeClient对象。使用自动代码完成来查找有效端点。或者，您可以将端点定义为.post()方法中的参数。

response = client.post(endpoint="elements/count",
		       bboxes=[8.625,49.3711,8.7334,49.4397],
		       time="2020-01-01",
		       filter="landuse=farmland and type:way")

可以使用该方法将来自数据聚合端点的响应转换为pandas.DataFrame对象OhsomeResponse.as_dataframe()。

response_df = response.as_dataframe()

2. 数据提取

示例：标记为landuse=farmland的OSM 方式，包括使用/elements/geometry端点的几何图形和标签：

client = OhsomeClient()
response = client.elements.geometry.post(bboxes=[8.625,49.3711,8.7334,49.4397],
					 time="2020-01-01",
					 filter="landuse=farmland and type:way",
					 properties="tags")
response_gdf = response.as_dataframe()

由于数据包含几何图形，因此可以geopandas.GeoDataFrame 使用该方法将来自数据提取端点的响应转换为 a 。OhsomeResponse.as_dataframe()

查询参数

所有查询参数都在ohsome API 文档中进行了描述，并且可以作为string对象传递给post()方法。也接受其他 Python 数据类型。

边界

可以使用,和参数定义查询的边界。坐标必须在 WGS 84 (EPSG:4326) 中给出。bpolysbboxesbcircles

多聚体

该bpolys参数可以作为geopandas.GeoDataFrame包含多边形特征的 a 传递。

bpolys = gpd.read_file("./data/polygons.geojson")
client.elements.count.groupByBoundary.post(bpolys=bpolys, filter="amenity=restaurant")

盒子

该bboxes参数包含一个或多个边界框的坐标。

bboxes = [8.7137,49.4096,8.717,49.4119] # one bounding box
bboxes = [[8.7137,49.4096,8.717,49.4119], [8.7137,49.4096,8.717,49.4119]]
bboxes = {"A": [8.67066, 49.41423, 8.68177, 49.4204],
	  "B": [8.67066, 49.41423, 8.68177, 49.4204]}

bcircles

该bcircles参数包含一个或多个通过质心坐标和以米为单位的半径定义的圆。

bcircles = [8.7137,49.4096, 100]
bcircles = [[8.7137,49.4096, 100], [8.7137,49.4096, 300]]
bcircles = {"Circle1": [8.695, 49.41, 200],
	    "Circle2": [8.696, 49.41, 200]}

时间

时间参数必须符合 ISO-8601 可以通过多种方式传递

time = '2018-01-01/2018-03-01/P1M'
time = ['2018-01-01', '2018-02-01', '2018-03-01']
time = datetime.datetime(year=2018, month=3, day=1)
time = pandas.date_range("2018-01-01", periods=3, freq="M")

贡献指南

如果您想为此项目做出贡献，请分叉存储库或创建一个包含您的更改的新分支。

为开发安装依赖项

所有这些依赖项都可以使用 pip 安装。如果您使用 anaconda，则需要通过 conda-forge 安装软件包。

• pytest = ^6.2.2
• pytest-cov = >=2.0.0
• 预提交 = >=2.1.1
• 黑色 = ^20.8b1
• pytest-random-order = ^1.0.4（不能通过 anaconda 获得）
• 亚斯平 = <1.4.1
• 毒物 = ^3.23.0

在提交之前在我们的本地 git repo 中安装预提交钩子，以确保同质的代码风格。

$ pre-commit install

使用pytest（如果您愿意）在存储库中运行测试poetry以确保一切正常。

$ poetry run pytest

针对 ohsome API 的 dockerised 本地实例运行测试更快，但不是强制性的。默认情况下，测试会发出一条警告，指出它找不到本地实例，然后回退到公共实例。要设置和启动本地实例，请在运行测试之前运行以下命令（请参阅https://github.com/GIScience/ohsome-api-dockerized）。

$ docker run -dt --name ohsome-api -p 8080:8080 julianpsotta/ohsome-api:latest

准备好合并后，向开发分支创建拉取请求。

参考

这个包的设计灵感来自于 Elmer Thomas 的博客文章Using Python to Implement a Fluent Interface to Any REST API。