Naksha (नक्शा) is the name of this fork of the XYZ-Hub (pronounced nakshaa or nakśā). It stays a web service for the access and management of geospatial data. This spin-off was done to independently realize needed new features, not planned to be supported in the original XYZ-Hub project.
The meaning of Naksha is “Map”.
Naksha features 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
Naksha uses GeoJSON as the main geospatial data exchange format. Tiled data can also be provided as MVT.
- Java 8+
- Maven 3.6+
- Postgres 10+ with PostGIS 2.5+
- Redis 5+ (optional)
- Docker 18+ (optional)
- Docker Compose 1.24+ (optional)
Clone and install the project using:
git clone https://github.com/heremaps/xyz-hub.git
cd xyz-hub
mvn clean install
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.
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 -server -cp xyz-hub-service/target/xyz-hub-service.jar com.here.xyz.hub.Service
There are two ways to provide runtime configuration:
- Using custom
config.json
file - Using environment variables
The service persists out of modules with a bootstrap code to start the service. All configuration is done in the config.json.
The bootstrap code could be used to run only the hub-verticle
or only the connector-verticle
or it can be used to run both as a single monolith. In a microservice deployment you run one cluster with only hub-verticle
deployment and another cluster with only connector-verticle
deployment. It is as well possible to mix this, so running a monolith deployment that optionally can use connector configurations to use foreign connectors for individual spaces.
Warning: The connector-verticle
does not perform security checks, so open it to external access will bypass all security restrictions!
The location of the configuration file could be modified using environment variables or by creating the config.json
file in the corresponding configuration folder. The exact configuration folder is platform dependent, but generally follows the XGD user configuration directory, standard, so on Linux being by default ~/.config/xyz-hub/
. For Windows the files will reside in the CSIDL_PROFILE folder, by default C:\Users\{username}\.config\xyz-hub
. This path could be changed via environment variable XDG_CONFIG_HOME
, which will result in the location $XDG_CONFIG_HOME/xyz-hub/
. Next to this, an explicit location can be specified via the environment variable XYZ_CONFIG_PATH
, this path will not be extended by the xyz-hub
folder, so you can directly specify where to keep the config files. This is important when you want to start multiple versions of the service: XYZ_CONFIG_PATH=~/.config/xyz-hub/a/ java -jar xyz-hub-service.jar
.
# Create copy of default config file
mkdir ~/.config/xyz-hub
cp xyz-hub-service/src/main/resources/config.json ~/.config/xyz-hub/
# Modify custom file as per need
vi ~/.config/xyz-hub/config.json
# Then, start the service (usual command)
java -server -cp xyz-hub-service/target/xyz-hub-service.jar com.here.xyz.hub.Service
Environment variables can be explicitly set to override default parameters defined in config.json file.
For example:
# Set environment variables with custom values
export HTTP_PORT=7080
export STORAGE_DB_URL=jdbc:postgresql://localhost:5432/postgres
export STORAGE_DB_USER=postgres_user
export STORAGE_DB_PASSWORD=postgres_pswd
# (optional) below parameters required only for SNS publishing
export ENABLE_TXN_PUBLISHER=true
export AWS_ACCESS_KEY_ID=aws-user-key
export AWS_SECRET_ACCESS_KEY=aws-user-secret
export AWS_DEFAULT_REGION=us-east-1
# Then, start the service (usual command)
java -server -cp xyz-hub-service/target/xyz-hub-service.jar com.here.xyz.hub.Service
Start using the service by creating a space:
curl -H "content-type:application/json" \
-d '{"id": "test-space", "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 (should you not specify an own id
):
{
"id": "test-space",
"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"
]
}
The OpenAPI specification files are accessible under the following URIs:
- Full: http://{host}:{port}/hub/static/openapi/full.yaml
- Stable: http://{host}:{port}/hub/static/openapi/stable.yaml
- Experimental: http://{host}:{port}/hub/static/openapi/experimental.yaml
- Contract: http://{host}:{port}/hub/static/openapi/contract.yaml
- Connector: http://{host}:{port}/psql/static/openapi/openapi-http-connector.yaml
Naksha (XYZ Hub) uses:
and others.
Your contributions are always welcome! Please have a look at the contribution guidelines first.
Copyright (C) 2017-2022 HERE Europe B.V.
This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.