XYZ Spaces for Python

使用Python管理您的XYZ Hub或HERE Data Hub空间和交互式地图层。

收录于：在线Python机器学习会议 & GeoPython 2020，2020年9月21日，查看会议日程。

动机

XYZ是一个开源的、实时的、云数据库系统，提供大规模访问大量地理空间数据的能力。一个XYZ“Hub”管理包含“特征”（地理数据“记录”）的“空间”，这些空间和特征具有唯一的ID，并带有标签和属性。存在一个RESTful API，以提供与XYZ Hub交互的低级别访问。

这个Python包允许您通过包装RESTful API的高级程序接口，与给定Hub上的XYZ空间和特征进行交互。使用此包，您可以

• 创建、读取、列出、更新、共享、删除空间（也可以：获取空间信息和统计信息）。
• 添加、读取、更新、迭代、搜索、聚类（十六进制/四分位框）、删除特征。
• 通过ID、标签、属性、bbox、瓦片、半径、几何形状搜索特征。

基于XYZ Hub，HERE Data Hub是一个商业服务（提供免费计划），提供一些额外功能（专业计划），如聚类、虚拟空间、活动日志等。

下面的GIF展示了与示例笔记本的交互，演示如何在大规模公共数据集上使用空间搜索，该数据集是从HERE Data Hub加载的。

先决条件

在您可以安装此包、运行其测试套件或使用示例笔记本之前，请确保您的系统满足以下先决条件

• 一个Python安装，建议3.7+，并且有pip命令可以安装依赖项

• 一个HERE开发者门户下的免费HERE开发者账户

• 从您的XYZ Hub服务器或XYZ门户（另见其入门部分）获取的XYZ API访问令牌，该令牌在名为XYZ_TOKEN的环境变量中，您可以通过以下方式设置（当然，使用有效值）

  export XYZ_TOKEN="MY-FANCY-XYZ-TOKEN"
  

  如果您愿意，您也可以将此令牌作为代码中的参数提供。

安装

此包可以通过pip或conda从各种来源安装

• 从Anaconda conda-forge频道使用conda安装

  conda install -c conda-forge xyzspaces
  

• 从Python包索引安装

  pip install xyzspaces
  

• 使用可选依赖项从Python包索引安装

  pip install "xyzspaces[geo]"
  

• 从GitHub上的源代码仓库安装

  pip install -e git+https://github.com/heremaps/xyz-spaces-python#egg=xyzspaces
  

如果您想运行测试套件或尝试示例笔记本，您需要克隆整个仓库

• 克隆托管此包的仓库的本地副本。以下命令应该会这样做

  git clone https://github.com/heremaps/xyz-spaces-python.git
  

• 进入仓库的根目录

  cd xyzspaces
  

交互式地图层

《xyzspaces》包支持交互式地图层，这是在HERE平台上的数据枢纽。使用《xyzspaces》，您可以使用高级Python接口与交互式地图层进行交互，该接口封装了RESTful API。通过交互式地图层，数据以GeoJSON格式存储，可以在任何缩放级别动态检索。交互式地图层针对地图（即GIS功能）上的数据可视化、分析和修改进行了优化。

交互式地图层的关键特性包括：

• 手动或通过程序创建和修改地图；编辑实时发布，无需额外交互。
• 在粒度和特征属性级别修改数据。
• 在地图上直接添加和删除点、线和多边形。
• 能够以不同的瓦片方案检索数据。
• 通过特征ID、边界框、空间搜索、属性搜索以及瓦片内包含的特征来探索和检索数据。
• 通过特征属性的值（例如，速度限制、地点类型、地址、名称等）来搜索数据。
• 数据采样，使其能够高效地渲染非常大的数据集的摘要，以供视觉参考和分析。
• 使用六边形或四边形进行聚类，以产生丰富的视觉数据表示。

凭证

要与交互式地图层交互，您需要在HERE平台上拥有一个账户。有关HERE平台账户的更多详细信息，请参阅我们的文档获取HERE账户。一旦您拥有账户，请按照以下步骤获取凭证

• 转到HERE平台应用程序和密钥并注册一个新应用程序。
• 为应用程序创建密钥并下载生成的credentials.properties文件。

HERE平台生成的应用程序凭证应类似于以下示例

  here.user.id = <example_here>
  here.client.id = <example_here>
  here.access.key.id = <example_here>
  here.access.key.secret = <example_here>
  here.token.endpoint.url = <example_here>

您可以使用以下任何方法提供凭证

• 默认凭证
• 环境变量
• 凭证文件

默认凭证

将凭证文件放置在

对于Linux/MacOS：$HOME/.here/credentials.properties

对于Windows：%USERPROFILE%\.here\credentials.properties

环境变量

您可以通过分配以下环境变量的值来覆盖默认凭证

HERE_USER_ID
HERE_CLIENT_ID
HERE_ACCESS_KEY_ID
HERE_ACCESS_KEY_SECRET
HERE_TOKEN_ENDPOINT_URL

凭证文件

您可以将任何凭证文件指定为~/.here/credentials.properties中找到的凭证文件的替代品。如果路径上不存在文件，或者文件格式不正确，则生成错误。

文档

文档托管在此处。

要本地构建文档，请运行

bash scripts/build_docs.sh

“Hello World”示例

以下是一些微小的“Hello World”示例，您可以在安装后立即运行以成功体验XYZ！

数据枢纽

import geojson
import os
import xyzspaces

os.environ["XYZ_TOKEN"] = "MY_XYZ_TOKEN"
xyz = xyzspaces.XYZ()

# Create a New Space
title = "My Demo Space"
description = "My Description"
space = xyz.spaces.new(title=title, description=description)

# Define a New Feature
feature =  {
    "type": "Feature",
    "properties": {"party": "Republican"},
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [-104.05, 48.99],
            [-97.22,  48.98],
            [-96.58,  45.94],
            [-104.03, 45.94],
            [-104.05, 48.99]
        ]]
    }
}

# Save it to a Space and get its ID
feature_id = space.add_features(features=geojson.FeatureCollection([feature]))["features"][0]["id"]

# Read a Feature from a Space
feature = space.get_feature(feature_id=feature_id)
print(geojson.dumps(feature, indent=4, sort_keys=True))

交互式地图层

import geojson
from xyzspaces import IML
from xyzspaces.iml.credentials import Credentials

credentials = Credentials.from_default() # credentials are in either credentials file at default location or in environment variables

layer_details = {
    "id": "demo-interactive-layer",
    "name": "Demo Interactive Layer",
    "summary": "Demo Interactive Layer",
    "description": "Demo Interactive Layer",
    "layerType": "interactivemap",
    "interactiveMapProperties": {},
}

iml = IML.new(
    catalog_id="demo-catalog1",
    catalog_name="demo-catalog",
    catalog_summary="Demo catalog",
    catalog_description="Demo catalog",
    layer_details=layer_details,
    credentials=credentials,
)

# Define a New Feature
feature = {
    "type": "Feature",
    "properties": {"party": "Republican"},
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-104.05, 48.99],
                [-97.22, 48.98],
                [-96.58, 45.94],
                [-104.03, 45.94],
                [-104.05, 48.99],
            ]
        ],
    },
}
# Save feature to interactive map layer
iml.layer.write_feature(feature_id="demo_feature", data=feature)

# Read feature from nteractive map layer
resp = iml.layer.get_feature(feature_id="demo_feature")
print(geojson.dumps(resp.to_geojson(), indent=4, sort_keys=True))

许可证

版权（C）2019-2021 HERE欧洲B.V。

除非在特定目录的LICENSE文件中另有说明，否则根目录中的LICENSE适用于本存储库中的所有内容。