README.md 8.3 KB
Newer Older
Lukas Loos's avatar
Lukas Loos committed
1
2
# ohsome2X

3
4
5
> 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.
Michael Auer's avatar
Michael Auer committed
6

7
> Output: Creates a GeoJSON File or new result table in your PostgreSQL/PostGIS database. 
8

9
The package includes a library with a single class to run. 
Michael Auer's avatar
Michael Auer committed
10

11
Additionally it includes `ohsome2x-cli`, a command-line tool with a configuration wizard to create and run a query-configuration-JSON.
Michael Auer's avatar
Michael Auer committed
12

13
This library/tool makes use of the ohsome API (https://api.ohsome.org) as data backend and many other great open-source libraries.
Michael Auer's avatar
Michael Auer committed
14

15
16
17
18
19
20
21
22
23
24
25
26
27
28
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

29
30
31
32
33
34
//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

35
36
37
38
//contributors
users/count/groupBy/boundary
```

39
This software is developed by [HeiGIT](https://heigit.org):
Michael Auer's avatar
Michael Auer committed
40

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

43
44
45
46
47
48
## 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`.
Michael Auer's avatar
Michael Auer committed
49

50
To run the command-line wizard:
51
```sh
52
53
54
55
56
57
58
59
60
61
62
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
-------------------------
Michael Auer's avatar
Michael Auer committed
63
64
```

65
### 2. With installation as library to use it in your Node.js script
66

67
68
69
70
71
72
73
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:
Michael Auer's avatar
Michael Auer committed
74

75
76
77
    ```
    $ npm run build
    ```
78

79
80
81
82
83
3. Write your own JavaScript or TypeScript file:

    ```
    See Examples and API section to learn how to do it. Enjoy!
    ```
84
85
86
87
88
89
   
## 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
90
```json
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
{
  "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]
          ]]}}]}
```

108
109
110
111
##### 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

112
```json
113
{
114
115
  "ohsomeQuery": {
    "queryType": "elements/count/groupBy/boundary",
116
    "filter": "building=* and building!=no and geometry:polygon",
117
    "time": "2008/2020/P1Y"
118
  },
119
120
121
122
  "source": {
    "geometryId": "id",
    "name": "heidelberg.geojson",
    "store": { "path": "heidelberg.geojson", "type": "geojson" }
123
  },
124
125
126
127
128
129
130
131
  "target": {
    "horizontalTimestampColumns": false,
    "createGeometry": true,
    "transformToWebmercator": false,
    "storeZeroValues": true,
    "computeValuePerArea": true,
    "name": "heidelberg_buildings_count.geojson",
    "store": { "path": "heidelberg_buildings_count.geojson", "type": "geojson" }
132
133
134
135
136
137
  }
}
```

##### Step 3. Run the Query
```bash
138
$ npx @giscience/ohsome2x run --conf myquery.json
139
140
141
142
143
```



## API
144
### Basic Usage
145
Node:
146
```js
Michael Auer's avatar
Michael Auer committed
147
const Ohsome2X = require('@giscience/ohsome2x');
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

// 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
Michael Auer's avatar
Michael Auer committed
164
import Ohsome2X = require('@giscience/ohsome2x'); 
165
import {Ohsome2XConfig} from '@giscience/ohsome2x/dist/config_types_interfaces';
166
167
168
169
170
171
172
173
174
175
176
177
178
179

// 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);
```

180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250

### 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
251
252

- [OhsomeHeX](https://ohsome.org/apps/osm-history-explorer) - The OSM History Explorer: Uses this library as backend
253
- [ohsome API](https://api.ohsome.org) - WebAPI to query OSM History Data
254
- [OSHDB](https://github.com/GIScience/oshdb) - The OpenStreetMap History Database: Query OSM History Data with Java
255
- [ohsome.org](https://ohsome.org) - Get information about all these technologies and more
256
- [heigit.org](https://heigit.org) - The Heidelberg Institute for Geoinformation Technology: The non-profit company behind all those useful tools.