Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/heremaps/xyz-hub
XYZ Hub is a RESTful web service for the access and management of geospatial data.
https://github.com/heremaps/xyz-hub
geojson geospatial restful-api
Last synced: about 2 months ago
JSON representation
XYZ Hub is a RESTful web service for the access and management of geospatial data.
- Host: GitHub
- URL: https://github.com/heremaps/xyz-hub
- Owner: heremaps
- License: apache-2.0
- Created: 2019-12-06T16:05:33.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-04-12T07:48:35.000Z (5 months ago)
- Last Synced: 2024-04-14T05:58:25.676Z (5 months ago)
- Topics: geojson, geospatial, restful-api
- Language: Java
- Homepage:
- Size: 8.79 MB
- Stars: 63
- Watchers: 21
- Forks: 40
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
---
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/heremaps/xyz-hub/actions?query=workflow%3A%22Run+XYZ+Hub+tests%22)
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](https://www.here.xyz/api) and in the [OpenAPI specification](https://xyz.api.here.com/hub/static/redoc/index.html).
XYZ Hub uses [GeoJSON](https://tools.ietf.org/html/rfc79460) as the main geospatial data exchange format. Tiled data can also be provided as [MVT](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md).
# 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:
```bash
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.
```bash
docker-compose up -d
```
Alternatively, you can start freshly from the sources by using this command after cloning the project:
```bash
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.
```bash
java [OPTIONS] -jar xyz-hub-service/target/xyz-hub-service.jar
```
Example:
```bash
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](./xyz-hub-service/src/main/resources/config.json), using environment variables or system properties. See the default list of [configuration parameters](https://github.com/heremaps/xyz-hub/wiki/Configuration-parameters) and their default values.
# Usage
Start using the service by creating a _space_:
```bash
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:
```json
{
"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:
```bash
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:
```json
{
"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://:/hub/static/openapi/stable.yaml`
* Experimental: `http://:/hub/static/openapi/experimental.yaml`
# Acknowledgements
XYZ Hub uses:
* [Vertx](http://vertx.io/)
* [Geotools](https://github.com/geotools/geotools)
* [JTS](https://github.com/locationtech/jts)
* [Jackson](https://github.com/FasterXML/jackson)
and [others](./pom.xml#L177-L479).
# Contributing
Your contributions are always welcome! Please have a look at the [contribution guidelines](CONTRIBUTING.md) first.
# License
Copyright (C) 2017-2024 HERE Europe B.V.
This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](./LICENSE) file for details.