XYZ Hub is a RESTful web service for the access and management of geospatial data.

Overview

Some of the features of XYZ Hub are:

• Organize geo datasets in spaces
• Store and manipulate individual geo features (points, linestrings, polygons)
• Retrieve geo features as vector tiles, with or without clipped geometries
• Search for geo features spatially using a bounding box, radius, or any custom geometry
• Explore geo features by filtering property values
• Retrieve statistics for your spaces
• Analytical representation of geo data as hexbins with statistical information
• Connect with different data sources
• Build a real-time geodata pipeline with processors
• Attach listeners to react on events

You can find more information in the XYZ Documentation and in the OpenAPI specification.

XYZ Hub uses GeoJSON as the main geospatial data exchange format. Tiled data can also be provided as MVT.

Prerequisites

• Java 17
• Maven 3.9+
• Postgres 15+ with PostGIS 3+
• Redis 7+ (optional)
• Docker 18+ (optional)
• Docker Compose 1.24+ (optional)

Getting started

Clone and install the project using:

git clone https://github.com/heremaps/xyz-hub.git
cd xyz-hub
mvn clean install

With docker

The service and all dependencies could be started locally using Docker compose.

docker-compose up -d

Alternatively, you can start freshly from the sources by using this command after cloning the project:

mvn clean install -Pdocker

Hint: Postgres with PostGIS will be automatically started if you use 'docker-compose up -d' to start the service.

Without docker

The service could also be started directly as a fat jar. In this case Postgres and the other optional dependencies need to be started separately.

java [OPTIONS] -jar xyz-hub-service/target/xyz-hub-service.jar

Example:

java -DHTTP_PORT=8080 -jar xyz-hub-service/target/xyz-hub-service.jar

Configuration options

The service start parameters could be specified by editing the default config file, using environment variables or system properties. See the default list of configuration parameters and their default values.

Usage

Start using the service by creating a space:

curl -H "content-type:application/json" -d '{"title": "my first space", "description": "my first geodata repo"}' http://localhost:8080/hub/spaces

The service will respond with the space definition including the space ID:

{
    "id": "pvhQepar",
    "title": "my first space",
    "description": "my first geodata repo",
    "storage": {
        "id": "psql",
        "params": null
    },
    "owner": "ANONYMOUS",
    "createdAt": 1576601166681,
    "updatedAt": 1576601166681,
    "contentUpdatedAt": 1576601166681,
    "autoCacheProfile": {
        "browserTTL": 0,
        "cdnTTL": 0,
        "serviceTTL": 0
    }
}

You can now add features to your brand new space:

curl -H "content-type:application/geo+json" -d '{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[-2.960847,53.430828]},"properties":{"name":"Anfield","@ns:com:here:xyz":{"tags":["football","stadium"]},"amenity":"Football Stadium","capacity":54074,"description":"Home of Liverpool Football Club"}}]}' http://localhost:8080/hub/spaces/pvhQepar/features

The service will respond with the inserted geo features:

{
    "type": "FeatureCollection",
    "etag": "b67016e5dcabbd5f76b0719d75c84424",
    "features": [
        {
            "type": "Feature",
            "id": "nf36KMsQAUYoM5kM",
            "geometry": {
                "type": "Point",
                "coordinates": [ -2.960847, 53.430828 ]
            },
            "properties": {
                "@ns:com:here:xyz": {
                    "space": "pvhQepar",
                    "createdAt": 1576602412218,
                    "updatedAt": 1576602412218,
                    "tags": [ "football", "stadium" ]
                },
                "amenity": "Football Stadium",
                "name": "Anfield",
                "description": "Home of Liverpool Football Club",
                "capacity": 54074
            }
        }
    ],
    "inserted": [
        "nf36KMsQAUYoM5kM"
    ]
}

OpenAPI specification

The OpenAPI specification files are accessible under the following URIs:

• Stable: http://<host>:<port>/hub/static/openapi/stable.yaml
• Experimental: http://<host>:<port>/hub/static/openapi/experimental.yaml

Acknowledgements

XYZ Hub uses:

• Vertx
• Geotools
• JTS
• Jackson

and others.

Contributing

Your contributions are always welcome! Please have a look at the contribution guidelines first.

License

Copyright (C) 2017-2024 HERE Europe B.V.

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.