@giscience/ohsome2x v2.5.8
ohsome2X
Query OSM History Data (count, length, area) about specific OSM Features or OSM User activity (user-count) for your areas of interest.
Input: Accepts GeoJSON or PostgreSQL/PostGIS as input source.
Output: Creates a GeoJSON File or new result table in your PostgreSQL/PostGIS database.
The package includes a library with a single class to run.
Additionally it includes ohsome2x-cli
, a command-line tool with a configuration wizard to create and run a query-configuration-JSON.
This library/tool makes use of the ohsome API (https://api.ohsome.org) as data backend and many other great open-source libraries.
Currently supported ohsome API query types are:
//standard
elements/count/groupBy/boundary
elements/length/groupBy/boundary
elements/area/groupBy/boundary
elements/perimeter/groupBy/boundary
//ratio
elements/count/ratio/groupBy/boundary
elements/length/ratio/groupBy/boundary
elements/area/ratio/groupBy/boundary
elements/perimeter/ratio/groupBy/boundary
//group by tags within each boundary
elements/count/groupBy/boundary/groupBy/tag
elements/length/groupBy/boundary/groupBy/tag
elements/area/groupBy/boundary/groupBy/tag
elements/perimeter/groupBy/boundary/groupBy/tag
//contributors
users/count/groupBy/boundary
This software is developed by HeiGIT:
Usage
There are two ways how you can use ohsome2x.
1. Without installation using the npm package runner npx
Info: The
npx
command comes with the installation ofnpm
.
To run the command-line wizard:
Syntax info:
$ npx @giscience/ohsome2x
-------------------------
USAGE:
with 'npx'
npx @giscience/ohsome2x createconfig [(-o|--out) path]
npx @giscience/ohsome2x run (-c|--conf) fullConfig.json
as local command
node ohsome2x-cli.js createconfig [(-o|--out) path]
node ohsome2x-cli.js run (-c|--conf) fullConfig.json
-------------------------
2. With installation as library to use it in your Node.js script
For use as library in Node.js install the package:
$ npm install @giscience/ohsome2x
You find the built library in the
/dist
folder after executing:$ npm run build
Write your own JavaScript or TypeScript file:
See Examples and API section to learn how to do it. Enjoy!
Example
Query the number of buildings in a bbox around Heidelberg in a yearly resolution from 2008 to 2020
Step 1. You need some input (one or many polygons): heidelberg.geojson
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {"id": "Heidelberg"},
"geometry": {
"type": "Polygon",
"coordinates": [
[ [8.625984191894531, 49.38527827629032],
[8.735504150390625, 49.38527827629032],
[8.735504150390625, 49.433975502014675],
[8.625984191894531, 49.433975502014675],
[8.625984191894531, 49.38527827629032]
]]}}]}
Step 2. Specify your query as JSON-file (you can use the commandline wizard to create this): myquery.json
Info: for the filter Syntax see: https://docs.ohsome.org/ohsome-api/stable/filter.html
{
"ohsomeQuery": {
"queryType": "elements/count/groupBy/boundary",
"filter": "building=* and building!=no and geometry:polygon",
"time": "2008/2020/P1Y"
},
"source": {
"geometryId": "id",
"name": "heidelberg.geojson",
"store": { "path": "heidelberg.geojson", "type": "geojson" }
},
"target": {
"horizontalTimestampColumns": false,
"createGeometry": true,
"transformToWebmercator": false,
"storeZeroValues": true,
"computeValuePerArea": true,
"name": "heidelberg_buildings_count.geojson",
"store": { "path": "heidelberg_buildings_count.geojson", "type": "geojson" }
}
}
Step 3. Run the Query
$ npx @giscience/ohsome2x run --conf myquery.json
API
Basic Usage
Node:
const Ohsome2X = require('@giscience/ohsome2x');
// you can create this config using the command-line wizard, run: npx ohsome2x-cli
const config = {
ohsomeQuery: {...},
source: {...},
target: {...}
}
const ohsome2x = new Ohsome2X(config);
// This will return a Promise
ohsome2x.run().catch(console.log);
TypeScript:
import Ohsome2X = require('@giscience/ohsome2x');
import {Ohsome2XConfig} from '@giscience/ohsome2x/dist/config_types_interfaces';
// you can create this config using the command-line wizard, run: npx ohsome2x-cli
const config: Ohsome2XConfig = {
ohsomeQuery: {...},
source: {...},
target: {...}
}
const ohsome2x = new Ohsome2X(config);
// This will return a Promise
ohsome2x.run().catch(console.log);
Events
The Ohsome2X object currently provides 2 event types that can be listened to:
progress
for getting progress updates. Especially useful for iterative processing of large input datasetsprogress
provides the following object to your callback (use processed and total to compute a progress percentage):{ "type": "progress", "processed": <number> of already finished input geometries, "total": <number> of all input geometries, "cursor": <number> that indicates the current state of iterative processing in case you configured source and target as PostGIS-Stores and specified a fetchSize, "fetchSize": <number> fetchSize that is currently used to fetch the next chunk of source data, "timestamp": <string> ISO timestamp }
finished
to get some information on duration and finishing time:```json { "type": "finished", "duration": <string> a human readable duration like '2 days 13 hours 45 min 12 seconds', "duration_ms": <number> duration in milliseconds, "timestamp": <string> ISO timestamp } ```
Example:
const Ohsome2X = require('@giscience/ohsome2x');
// you can create this config using the command-line wizard, run: npx ohsome2x-cli const config = { ohsomeQuery: { "queryType": "users/count/groupBy/boundary", "filter": "natural=tree and type:node", "time": "2010/2020/P1Y" }, source: { "schema": "public", "name": "my_source_table_name", "geometryId": "id", // name of the id column. Can be numbers or strings. "geometryColumn": "geom", "fetchSize": 5000, // this option triggers an iterative processing "cursor": null, // can be used to resume an interrupted iterative processing at a certain position. Get this information from the 'fetch' event. "store": { "host": "your.postgis.server.com", "port": "5434", "database": "your_database_name", "user": "username", "password": "secret", "type": "postgis" } }, target: {...another PostGIS target config...} }
const ohsome2x = new Ohsome2X(config);
// define functions to be executed when an event is reported ohsome2x.on('progress', (evt)=>console.log(evt, ((evt.processed / evt.total) * 100).toFixed(0) +'%')); ohsome2x.on('finished', (evt)=>console.log(evt.duration));
// This will return a Promise ohsome2x.run().catch(console.log);
## Related
- [OhsomeHeX](https://ohsome.org/apps/osm-history-explorer) - The OSM History Explorer: Uses this library as backend
- [ohsome API](https://api.ohsome.org) - WebAPI to query OSM History Data
- [OSHDB](https://github.com/GIScience/oshdb) - The OpenStreetMap History Database: Query OSM History Data with Java
- [ohsome.org](https://ohsome.org) - Get information about all these technologies and more
- [heigit.org](https://heigit.org) - The Heidelberg Institute for Geoinformation Technology: The non-profit company behind all those useful tools.
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago