Manage your XYZ Hub or HERE Data Hub spaces and Interactive Map Layer from Python.
FEATURED IN: Online Python Machine Learning Conference & GeoPython 2020, Sept 21, 2020, see conference schedule.
XYZ is an Open Source, real-time, cloud database system providing access to large geospatial data at scale. An XYZ "Hub" manages "spaces" that contain "features" (geodata "records") with tags and properties, with spaces and features having unique IDs. A RESTful API exists to provide low-level access to interact with a XYZ Hub.
This Python package allows to interact with your XYZ spaces and features on a given Hub using a higher level programmatic interface that wraps the RESTful API. Using this package you can:
Based on the XYZ Hub the HERE Data Hub is a commercial service (with a free plan), that offers some additional features (in a pro plan), like clustering, virtual spaces, activity logs, and likely more to come.
The GIF below shows an interaction with an example notebook, demonstrating how to use a spatial search on a big public dataset, loaded from the HERE Data Hub.
Before you can install this package, run its test-suite or use the example notebooks to make sure your system meets the following prerequisities:
pip
command available to install dependenciesAn XYZ API access token from your XYZ Hub server or the XYZ portal (see also its Getting
Started section) in an environment variable named XYZ_TOKEN
which you can
set like this (with a valid value, of course):
export XYZ_TOKEN="MY-FANCY-XYZ-TOKEN"
If you prefer, you can alternatively provide this token as a parameter in your code.
This package can be installed with pip
or conda
from various sources:
Install with conda from the Anaconda conda-forge channel:
conda install -c conda-forge xyzspaces
Install from the Python Package Index:
pip install xyzspaces
Install from the Python Package Index with optional dependencies:
pip install "xyzspaces[geo]"
Install from its source repository on GitHub:
pip install -e git+https://github.com/heremaps/xyz-spaces-python#egg=xyzspaces
If you want to run the test suite or experiment with the example notebooks bundled, you need to clone the whole repository:
Make a local clone of the repository hosting this package. The following command should do:
git clone https://github.com/heremaps/xyz-spaces-python.git
Change into the repo root directory:
cd xyzspaces
The xyzspaces
package supports Interactive Map Layers which is Data Hub on HERE Platform.
Using xyzspaces
you can interact with your Interactive Map Layers using higher level pythonic interface that wraps the RESTful API.
With Interactive Map Layers, data is stored in GeoJSON and can be retrieved dynamically at any zoom level.
Interactive map layer is optimized for the visualization, analysis, and modification of data on a map (i.e., GIS functions).
Key features of Interactive Map Layers include:
To interact with Interactive Map Layer you will need an account on the HERE Platform. To get more details on the HERE Platform account please check our documentation Get a HERE account. Once you have the account follow the below steps to get credentials:
credentials.properties
file.The HERE platform generated app credentials should look similar to the example below:
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>
You can provide your credentials using any of the following methods:
Place the credentials file into
For Linux/MacOS: $HOME/.here/credentials.properties
For Windows: %USERPROFILE%\.here\credentials.properties
You can override default credentials by assigning values to the following environment variables:
HERE_USER_ID
HERE_CLIENT_ID
HERE_ACCESS_KEY_ID
HERE_ACCESS_KEY_SECRET
HERE_TOKEN_ENDPOINT_URL
You can specify any credentials file as an alternative to that found in ~/.here/credentials.properties
. An error is generated if there is no file present at the path, or if the file is not properly formatted.
Documentation is hosted here.
To build the docs locally run:
bash scripts/build_docs.sh
The following are tiny "Hello World"-like examples that you can run to have a successful first XYZ experience right after installation!
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))
Copyright (C) 2019-2021 HERE Europe B.V.
Unless otherwise noted in LICENSE
files for specific directories, the LICENSE in the root applies to all content in this repository.