README.md 4.17 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
8
> 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. 
Michael Auer's avatar
Michael Auer committed
9

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

12
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
13

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

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

## Install
Michael Auer's avatar
Michael Auer committed
19

20
For use as library in Node.js:
21
```sh
22
23
24
$ npm install ohsome2x
```
To run the command-line wizard:
25
```sh
26
$ npx ohsome2x-cli
Michael Auer's avatar
Michael Auer committed
27
28
```

29

Michael Auer's avatar
Michael Auer committed
30
31
32
## Usage
There are two ways how you can use ohsome2x.

33
34
35
36
1. Use it as library in another Node.js project. You find the built library in the `/dist` folder after executing `npm run build`
2. Use the interactive command line interface. 

    Run: 
37
38
   ```sh
   $ npx ohsome2x-cli
39
   OR 
40
   $ node ./ohsome2x-cli/ohsome2x-cli.js
41
42
43
44
45
46
47
   ```
   
## 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
48
```json
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "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 (you can use the commandline wizard to create this): myquery.json
67
```json
68
{
69
70
71
72
73
74
  "ohsomeQuery": {
    "queryType": "elements/count/groupBy/boundary",
    "keys": "building",
    "values": "",
    "types": "polygon",
    "time": "2008/2020/P1Y"
75
  },
76
77
78
79
  "source": {
    "geometryId": "id",
    "name": "heidelberg.geojson",
    "store": { "path": "heidelberg.geojson", "type": "geojson" }
80
  },
81
82
83
84
85
86
87
88
  "target": {
    "horizontalTimestampColumns": false,
    "createGeometry": true,
    "transformToWebmercator": false,
    "storeZeroValues": true,
    "computeValuePerArea": true,
    "name": "heidelberg_buildings_count.geojson",
    "store": { "path": "heidelberg_buildings_count.geojson", "type": "geojson" }
89
90
91
92
93
94
95
96
97
98
99
100
101
102
  }
}
```

##### Step 3. Run the Query
```bash
$ npx ohsome2x-cli run --conf myquery.json
```



## API

Node:
103
```js
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
const Ohsome2X = require('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('ohsome2x'); 
import {Ohsome2XConfig} from '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);
```

### Related

- [OhsomeHeX](https://ohsome.org/apps/osm-history-explorer) - The OSM History Explorer: Uses this library as backend
- [OhsomeAPI](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.