https://github.com/giscience/ohsome-now-stats-service
This is the REST service for the ohsomeNow stats.
https://github.com/giscience/ohsome-now-stats-service
Last synced: 5 months ago
JSON representation
This is the REST service for the ohsomeNow stats.
- Host: GitHub
- URL: https://github.com/giscience/ohsome-now-stats-service
- Owner: GIScience
- License: agpl-3.0
- Created: 2023-03-16T13:54:15.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-15T13:20:37.000Z (5 months ago)
- Last Synced: 2025-10-16T06:13:30.870Z (5 months ago)
- Language: Kotlin
- Homepage: https://stats.now.ohsome.org/api/
- Size: 1.62 MB
- Stars: 4
- Watchers: 9
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ohsome-now-stats-service
[](https://jenkins.heigit.org/job/ohsomeNow%20stats%20service/job/main/)
[](https://sonarcloud.io/dashboard?id=GIScience_ohsome-now-stats-service)
[](https://github.com/GIScience/badges#active)
[](LICENSE)
[](https://stats.now.ohsome.org/api/)
The **ohsomeNow stats API** offers a REST service to retrieve up-to-date and global scale overview statistics on mapping
activity in OpenStreetMap (OSM).
The ohsomeNow stats API builds upon a ClickHouse DB which contains all OSM edits for which a changeset hashtag has been
used. The REST service allows you to get insights into the number of contributors, total map edits, added buildings and
added road length for a given time range and OSM changesets hashtag filter. Additional topic statistics, e.g. the length
of added waterways, or the number of added healthcare facilities. You can use the REST service to report mapping
statistics for any time range starting from 2009-04-21 when the OSM-API version 0.6 introduced changesets.
Check out the [API documentation](https://stats.now.ohsome.org/api/swagger-ui/index.html#/) get in contact with us in
case you are planning to embed the API in your services or
websites.
The core features are:
* **Overview Statistics**: The `stats` endpoint provides mapping activity statistics summarized into a single line for a
single or multiple OSM changeset hashtags.
* **Trending Hashtags**: Get a list of the `mostUsedHashtags` in your chosen time-interval. The list is sorted by the
number of distinct OSM contributors per hashtag.
* **Country Stats**: Use the `/stats/{hashtag}/country` endpoint to get insights into contributors and edits per OSM
changeset hashtags for all countries.
* **Timeline**: Get insights about the dynamics in mapping activity over time with the `/stats/{hashtag}/interval`
endpoint.
* Country, Timeline and Overview Statistics are also available for a range of different topics, to explore which topics
are available, you can visit the [webpage](https://stats.now.ohsome.org).
Features for HOT Tasking Manager statistics:
* **User Statistics**: Access to statistics for individual users is restricted to OSM contributors who are logged in the
HOT Tasking Manager. These statistics only consider mapping activity for related changeset hashtags (
filter: `hotosm-project-*`).
For details about the ohsomeNow stats website
check [GIScience/ohsome-now-stats-frontend](https://github.com/GIScience/ohsome-now-stats-frontend).
# For Developers
## Technology
* JVM: Java 17
* Base framework: Spring Boot 3
* Build tool: Gradle 8.14
* Implementation language: Kotlin 2.0.21
* Test Framework: JUnit Jupiter 5.9
* additional HTTP integration and performance tests: Hurl 1.8
* API documentation: OpenAPI / Swagger
## Code Quality Tools
* Metrics: Detekt
* method length <= 17
* cyclomatic complexity <= 4
* Code Coverage: Kover
* test coverage > 90%
## Running the service
The service can be run directly with gradle
### Running Locally
#### Starting the service
The service can be run on every machine with a Java Runtime (JDK 17 or higher.)
To do so, run the following start script (on *nix systems):
```shell
./gradlew bootRun
```
or (on Windows systems):
```shell
./gradlew.bat bootRun
```
Once the system has started,
the API documentation including links to endpoints is available here:
http://localhost:8080/doc.html
## Release and artifact publication
These steps are achieved by the following 2 plugins:
* release plugin: https://plugins.gradle.org/plugin/net.researchgate.release
* maven-publish plugin: https://docs.gradle.org/current/userguide/publishing_maven.html
### Release plugin
This plugin is used to:
* check for a clean workspace and ensure that the local and remote git repos are in sync
* read current (snapshot) version from [./gradle.properties](./gradle.properties)
* create a git tag for this version (by removing the `-SNAPSHOT` postfix)
* set the next (snapshot) version in [./gradle.properties](./gradle.properties)
The plugin is run locally via the command line:
`./gradlew release`
The version scheme defaults can be overridden interactively if necessary.
### Maven-publish plugin
This plugin publishes all *release* and *snapshot* artifacts to the respective Artifactory maven repos.
Please note:
* This plugin is not intended to be started locally, but runs in the CI server.
### Update the gradle verification-metadata.xml when changing dependencies
```
./gradlew --write-verification-metadata sha256
```