1OSMIUM-EXPORT(1) OSMIUM-EXPORT(1)
2
3
4
6 osmium-export - export OSM data
7
9 osmium export [OPTIONS] OSM-FILE
10
12 The OSM data model with its nodes, ways, and relations is very differ‐
13 ent from the data model usually used for geodata with features having
14 point, linestring, or polygon geometries (or their cousins, the multi‐
15 point, multilinestring, or multipolygon geometries).
16
17 The export command transforms OSM data into a more usual GIS data
18 model. Nodes will be translated into points and ways into linestrings
19 or polygons (if they are closed ways). Multipolygon and boundary rela‐
20 tions will be translated into multipolygons. This transformation is
21 not loss-less, especially information in non-multipolygon, non-boundary
22 relations is lost.
23
24 All tags are preserved in this process. Note that most GIS formats
25 (such as Shapefiles, etc.) do not support arbitrary tags. Transforma‐
26 tion into other GIS formats will need extra steps mapping tags to a
27 limited list of attributes. This is outside the scope of this command.
28
29 The osmium export command has to keep an index of the node locations in
30 memory or in a temporary file on disk while doing its work. There are
31 several different ways it can do that which have different advantages
32 and disadvantages. The default is good enough for most cases, but see
33 the osmium-index-types(5) man page for details.
34
35 Objects with invalid geometries are silently omitted from the output.
36 This is the case for ways with less than two nodes or closed ways or
37 relations that can’t be assembled into a valid (multi)polygon. See the
38 options --show-errors/-e and --stop-on-error/-E for how to modify this
39 behaviour.
40
41 The input file will be read twice (once for the relations, once for
42 nodes and ways), so this command can not read its input from STDIN.
43
44 This command will not work on full history files.
45
46 This command will work with negative IDs on OSM objects (for instance
47 on files created with JOSM).
48
50 -c, --config=FILE
51 Read configuration from specified file.
52
53 -C, --print-default-config
54 Print the default config to STDOUT. Useful if you want to
55 change it and not write the whole thing manually. If you use
56 this option all other options are ignored.
57
58 -e, --show-errors
59 Output any geometry errors on STDERR. This includes ways with a
60 single node or areas that can’t be assembled from multipolygon
61 relations. This output is not suitable for automated use, there
62 are other tools that can create very detailed errors reports
63 that are better for that (see https://osmcode.org/osm-area-
64 tools/).
65
66 -E, --stop-on-error
67 Usually geometry errors (due to missing node locations or broken
68 polygons) are ignored and the features are omitted from the out‐
69 put. If this option is set, any error will immediately stop the
70 program.
71
72 --geometry-types=TYPES
73 Specify the geometry types that should be written out. Usually
74 all created geometries (points, linestrings, and (multi)poly‐
75 gons) are written to the output, but you can restrict the types
76 using this option. TYPES is a comma-separated list of the types
77 (“point”, “linestring”, and “polygon”).
78
79 -a, --attributes=ATTRS
80 In addition to tags, also export attributes specified in this
81 comma-separated list. By default, none are exported. See the
82 ATTRIBUTES section below for the known attributes list and an
83 explanation.
84
85 -i, --index-type=TYPE
86 Set the index type. For details see the osmium-index-types(5)
87 man page.
88
89 -I, --show-index-types
90 Shows a list of available index types. For details see the os‐
91 mium-index-types(5) man page. If you use this options all other
92 options are ignored.
93
94 -n, --keep-untagged
95 If this is set, features without any tags will be in the ex‐
96 ported data. By default these features will be omitted from the
97 output. Tags are the OSM tags, not attributes (like id, ver‐
98 sion, uid, ...) without the tags removed by the exclude_tags or
99 include_tags settings.
100
101 -r, --omit-rs
102 Do not print the RS (0x1e, record separator) character when us‐
103 ing the GeoJSON Text Sequence Format. Ignored for other for‐
104 mats. THIS OPTION IS DEPRECATED, PLEASE USE “-x
105 print_record_separator=false” INSTEAD.
106
107 -u, --add-unique-id=TYPE
108 Add a unique ID to each feature. TYPE can be either counter in
109 which case the first feature will get ID 1, the next ID 2 and so
110 on. The type of object does not matter in this case. Or the
111 TYPE is type_id in which case the ID is a string, the first
112 character is the type of object (`n' for nodes, `w' for
113 linestrings created from ways, and `a' for areas created from
114 ways and/or relations, after that there is a unique ID based on
115 the original OSM object ID(s). If the input file has negative
116 IDs, this can create IDs such as `w-12'. In spaten exports the
117 ID is written into the @fid field. For counter the value will
118 be an integer, for type_id it will be a string.
119
120 -x, --format-option=OPTION(=VALUE)
121 Set an output format option. The options available depend on
122 the output format. See the OUTPUT FORMAT OPTIONS section for
123 available options. If the VALUE is not set, the OPTION will be
124 set to “true”. If needed you can specify this option multiple
125 times to set several options. Options set on the command line
126 overwrite options set in the config file.
127
129 -h, --help
130 Show usage help.
131
132 -v, --verbose
133 Set verbose mode. The program will output information about
134 what it is doing to STDERR.
135
136 --progress
137 Show progress bar. Usually a progress bar is only displayed if
138 STDOUT and STDERR are detected to be TTY. With this option a
139 progress bar is always shown. Note that a progress bar will
140 never be shown when reading from STDIN or a pipe.
141
142 --no-progress
143 Do not show progress bar. Usually a progress bar is displayed
144 if STDOUT and STDERR are detected to be a TTY. With this option
145 the progress bar is suppressed. Note that a progress bar will
146 never be shown when reading from STDIN or a pipe.
147
149 -F, --input-format=FORMAT
150 The format of the input file(s). Can be used to set the input
151 format if it can’t be autodetected from the file name(s). This
152 will set the format for all input files, there is no way to set
153 the format for some input files only. See osmium-file-for‐
154 mats(5) or the libosmium manual for details.
155
157 -f, --output-format=FORMAT
158 The format of the output file. Can be used to set the output
159 file format if it can’t be autodetected from the output file
160 name. See the OUTPUT FORMATS section for a list of formats.
161
162 --fsync
163 Call fsync after writing the output file to force flushing buf‐
164 fers to disk.
165
166 -o, --output=FILE
167 Name of the output file. Default is `-' (STDOUT).
168
169 -O, --overwrite
170 Allow an existing output file to be overwritten. Normally os‐
171 mium will refuse to write over an existing file.
172
174 The config file is in JSON format. The top-level is an object which
175 contains the following optional names:
176
177 • attributes: An object specifying which attributes of OSM objects to
178 export. See the ATTRIBUTES section.
179
180 • format_options: An object specifying output format options. The op‐
181 tions available depend on the output format. See the OUTPUT FORMAT
182 OPTIONS section for available options. These options can also be set
183 using the command line option --format-option/-x.
184
185 • linear_tags: An expression specifying tags that should be treated as
186 linear tags. See below for details and also look at the AREA HAN‐
187 DLING section.
188
189 • area_tags: An expression specifying tags that should be treated as
190 area tags. See below for details and also look at the AREA HANDLING
191 section.
192
193 • exclude_tags: A list of tag expressions. Tags matching these expres‐
194 sions are excluded from the output. See the FILTER EXPRESSION sec‐
195 tion.
196
197 • include_tags: A list of tag expressions. Tags matching these expres‐
198 sions are included in the output. See the FILTER EXPRESSION section.
199
200 The area_tags and linear_tags can have the following values:
201
202 true All tags match. (An empty list [] can also be used to mean the
203 same, but this use is deprecated because it can be confusing.)
204
205 false No tags match.
206
207 Array The array contains one or more expressions as described in the
208 FILTER EXPRESSION section.
209
210 null If the area_tags or linear_tags is set to null or not set at
211 all, the inverse of the other setting is used. So if you do not
212 set the linear_tags but have some expressions in area_tags, ar‐
213 eas will be created for all objects matching those expressions
214 and linestrings for everything else. This can be simpler, be‐
215 cause you only have to keep one list, but in cases where an ob‐
216 ject can be interpreted as both an area and a linestring, only
217 one interpretation will be used.
218
219 The exclude_tags and include_tags options are mutually exclusive. If
220 you want to just exclude some tags but leave most tags untouched, use
221 the exclude_tags setting. If you only want a defined list of tags, use
222 include_tags.
223
224 When no config file is specified, the following settings are used:
225
226 {
227 "attributes": {
228 "type": false,
229 "id": false,
230 "version": false,
231 "changeset": false,
232 "timestamp": false,
233 "uid": false,
234 "user": false,
235 "way_nodes": false
236 },
237 "format_options": {
238 },
239 "linear_tags": true,
240 "area_tags": true,
241 "exclude_tags": [],
242 "include_tags": []
243 }
244
246 A filter expression specifies a tag or tags that should be matched in
247 the data.
248
249 Some examples:
250
251 amenity
252 Matches all objects with the key “amenity”.
253
254 highway=primary
255 Matches all objects with the key “highway” and value “primary”.
256
257 highway!=primary
258 Matches all objects with the key “highway” and a value other
259 than “primary”.
260
261 type=multipolygon,boundary
262 Matches all objects with key “type” and value “multipolygon” or
263 “boundary”.
264
265 name,name:de=Kastanienallee,Kastanienstrasse
266 Matches any object with a “name” or “name:de” tag with the value
267 “Kastanienallee” or “Kastanienstrasse”.
268
269 addr:* Matches all objects with any key starting with “addr:”
270
271 name=*Paris
272 Matches all objects with a name that contains the word “Paris”.
273
274 If there is no equal sign (“=”) in the expression only keys are matched
275 and values can be anything. If there is an equal sign (“=”) in the ex‐
276 pression, the key is to the left and the value to the right. An excla‐
277 mation sign (“!”) before the equal sign means: A tag with that key, but
278 not the value(s) to the right of the equal sign. A leading or trailing
279 asterisk (“*”) can be used for substring or prefix matching, respec‐
280 tively. Commas (“,”) can be used to separate several keys or values.
281
282 All filter expressions are case-sensitive. There is no way to escape
283 the special characters such as “=”, “*” and “,”. You can not mix
284 comma-expressions and “*”-expressions.
285
287 All OSM objects (nodes, ways, and relations) have attributes, areas in‐
288 herit their attributes from the ways and/or relations they were created
289 from. The attributes known to osmium export are:
290
291 • type (`node', `way', or `relation')
292
293 • id (64 bit object ID)
294
295 • version (version number)
296
297 • changeset (changeset ID)
298
299 • timestamp (time of object creation in seconds since Jan 1 1970)
300
301 • uid (user ID)
302
303 • user (user name)
304
305 • way_nodes (ways only, array with node IDs)
306
307 For areas, the type will be way or relation if the area was created
308 from a closed way or a multipolygon or boundary relation, respectively.
309 The id for areas is the id of the closed way or the multipolygon or
310 boundary relation.
311
312 By default the attributes will not be in the export, because they are
313 not necessary for most uses of OSM data. If you are interested in some
314 (or all) attributes, add an attributes object to the config file. Add
315 a member for each attribute you are interested in, the value can be ei‐
316 ther false (do not output this attribute), true (output this attribute
317 with the attribute name prefixed by the @ sign) or any string, in which
318 case the string will be used as the attribute name.
319
320 Another option is to specify attributes list in a comma-separated
321 string for the --attributes/-a command-line option. This way you can‐
322 not control column names, but also you won’t have to create a config
323 file.
324
325 Depending on your choice of values for the attributes objects, at‐
326 tributes can have the same name as tag keys. If this is the case, the
327 conflicting tag is silently dropped. So if there is a tag “@id=foo”
328 and you have set id to true in the attributes object, the tag will not
329 show up in the output.
330
331 Note that the id is not necessarily unique. Even the combination type
332 and id is not unique, because a way may end up in the output file as
333 LineString and as (Multi)Polygon. See the --add-unique-id/-u option
334 for a unique ID.
335
337 Multipolygon relations will be assembled into multipolygon geometries
338 forming areas. Some closed ways will also form areas. Here are the
339 detailed rules:
340
341 Non-closed way
342 A non-closed way (with the last node location not the same as
343 the first node location) is always (regardless of any tags) a
344 linestring, not an area.
345
346 Relation
347 A relation tagged type=multipolygon or type=boundary is always
348 (regardless of any tags) assembled into an area.
349
350 Closed way
351 For a closed way (with the last node location the same as the
352 first node location) the tags are checked: If the way has an
353 area=yes tag, an area is created. If the way has an area=no
354 tag, a linestring is created. An area tag with a value other
355 than yes or no is ignored. The configuration settings area_tags
356 and linear_tags can be used to augment the area check. If any
357 of the tags matches the area_tags, an area is created. If any
358 of the tags matches the linear_tags, a linestring is created.
359 If both match, an area and a linestring is created. This is im‐
360 portant because some objects have tags that make them both, an
361 area and a linestring.
362
364 The following output formats are supported:
365
366 • geojson (alias: json): GeoJSON (RFC7946). The output file will con‐
367 tain a single FeatureCollection object. This is the default format.
368
369 • geojsonseq (alias: jsonseq): GeoJSON Text Sequence (RFC8142). Each
370 line (beginning with a RS (0x1e, record separator) and ending in a
371 linefeed character) contains one GeoJSON object. Used for streaming
372 GeoJSON.
373
374 • pg: PostgreSQL COPY text format. One line per object containing the
375 WGS84 geometry as WKB, the tags in JSON format and, optionally, more
376 columns for id and attributes. You have to create the table manu‐
377 ally, then use the PostgreSQL COPY command to import the data. En‐
378 able verbose output to see the SQL commands needed to create the ta‐
379 ble and load the data.
380
381 • spaten: Spaten, a binary format that is suitable for large data sets.
382
383 • text (alias: txt): A simple text format with the geometry in WKT for‐
384 mat followed by the comma-delimited tags. This is mainly intended
385 for debugging at the moment. THE FORMAT MIGHT CHANGE WITHOUT NOTICE!
386
388 • print_record_separator (default: true). Set to false to not print
389 the RS (0x1e, record separator) character when using the GeoJSON Text
390 Sequence Format. Ignored for other formats.
391
392 • tags_type (default: jsonb). Set to hstore to use HSTORE format in‐
393 stead of JSON/JSONB when using the Pg Format. Ignored in other for‐
394 mats.
395
397 osmium export exits with exit code
398
399 0 if everything went alright,
400
401 1 if there was an error processing the data, or
402
403 2 if there was a problem with the command line arguments.
404
406 osmium export will usually keep all node locations and all objects
407 needed for assembling the areas in memory. For larger data files, this
408 can need several tens of GBytes of memory. See the osmium-index-
409 types(5) man page for details.
410
412 Export into GeoJSON format:
413
414 osmium export data.osm.pbf -o data.geojson
415
416 Use a config file and export into GeoJSON Text Sequence format:
417
418 osmium export data.osm.pbf -o data.geojsonseq -c export-config.json
419
421 • osmium(1), osmium-file-formats(5), osmium-index-types(5), osmium-add-
422 node-locations-to-ways(1)
423
424 • Osmium website (https://osmcode.org/osmium-tool/)
425
426 • GeoJSON (http://geojson.org/)
427
428 • RFC7946 (https://tools.ietf.org/html/rfc7946)
429
430 • RFC8142 (https://tools.ietf.org/html/rfc8142)
431
432 • Line delimited JSON (https://en.wikipedia.org/wiki/JSON_Stream‐
433 ing#Line_delimited_JSON)
434
435 • Spaten Geo Format (https://thomas.skowron.eu/spaten/)
436
438 Copyright (C) 2013-2022 Jochen Topf <jochen@topf.org>.
439
440 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/li‐
441 censes/gpl.html>. This is free software: you are free to change and
442 redistribute it. There is NO WARRANTY, to the extent permitted by law.
443
445 If you have any questions or want to report a bug, please go to
446 https://osmcode.org/contact.html
447
449 Jochen Topf <jochen@topf.org>.
450
451
452
453 1.14.0 OSMIUM-EXPORT(1)