XYZ Spaces for Python

Manage your XYZ Hub or HERE Data Hub spaces from Python.


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:

  • Create, read, list, update, share, delete spaces (also: get space info and stats).
  • Add, read, update, iterate, search, cluster (hex/quad bins), delete features.
  • Search features by ID, tag, property, bbox, tile, radius, geometry.

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:

  • A Python installation, 3.6+ recommended, with the pip command available to install dependencies

  • A HERE developer account, free and available under HERE Developer Portal

  • An XYZ API access token from your XYZ Hub server or the XYZ portal (see also its Getting
    section) in an environment variable named XYZ_TOKEN which you can
    set like this (with a valid value, of course):


    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 its source repository on GitHub:

    pip install -e git+

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
  • Change into the repo root directory:

    cd xyzspaces


Documentation is hosted here.

To build the docs locally run:

bash scripts/

Hello World Example

The following is a tiny "Hello World"-like example that you can run to have a successful first XYZ experience right after installation! Just make sure to use your own real XYZ token!

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 =, 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))