XYZ Hub

License Build Status

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

Overview

Some of the features of XYZ Hub are:

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

Getting started

Clone and install the project using:

git clone https://github.com/heremaps/xyz-hub.git
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:

Acknowledgements

XYZ Hub uses:

and others.

Contributing

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

License

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

See the LICENSE file in the root of this project for license details.