npm package: @giscience/ohsome2x
Description: convenience library to query ohsome-api using nodejs
Author: M. Auer
Latest version: 2.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](https://heigit.org):

<img src="https://heigit.org/wp-content/uploads/2018/01/HeiGIT_Logo_cut-505x100@2x.png" alt="HeiGIT Logo" height="80px" width="404px">

## 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 of `npm`.

To run the command-line wizard:
```sh
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

1. For use as library in Node.js install the package:

    ```sh
    $ npm install @giscience/ohsome2x
    ```

2. You find the built library in the `/dist` folder after executing:

    ```
    $ npm run build
    ```

3. 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
```json
{
  "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

```json
{
  "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
```bash
$ npx @giscience/ohsome2x run --conf myquery.json
```



## API
### Basic Usage
Node:
```js
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:
```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 datasets

    `progress` provides the following object to your callback (use processed and total to compute a progress percentage):
    ```json
    {
        "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:
  
  ```js
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.