1OSMIUM-EXPORT(1) OSMIUM-EXPORT(1)
2
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 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 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 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 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 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 This command will not work on full history files.
45 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 -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 -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 -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 --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 -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 -i, --index-type=TYPE
86 Set the index type. For details see the osmium-index-types(5)
87 man page.
88 -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 -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 -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 -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 -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 -v, --verbose
133 Set verbose mode. The program will output information about
134 what it is doing to STDERR.
135 --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 --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 --fsync
163 Call fsync after writing the output file to force flushing buf‐
164 fers to disk.
165 -o, --output=FILE
167 Name of the output file. Default is `-' (STDOUT).
168 -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 • attributes: An object specifying which attributes of OSM objects to
178 export. See the ATTRIBUTES section.
179 • 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 • 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 • 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 • 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 • include_tags: A list of tag expressions. Tags matching these expres‐
198 sions are included in the output. See the FILTER EXPRESSION section.
199 The area_tags and linear_tags can have the following values:
201 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 false No tags match.
206 Array The array contains one or more expressions as described in the
208 FILTER EXPRESSION section.
209 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 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 When no config file is specified, the following settings are used:
225 {
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 Some examples:
250 amenity
252 Matches all objects with the key “amenity”.
253 highway=primary
255 Matches all objects with the key “highway” and value “primary”.
256 highway!=primary
258 Matches all objects with the key “highway” and a value other
259 than “primary”.
260 type=multipolygon,boundary
262 Matches all objects with key “type” and value “multipolygon” or
263 “boundary”.
264 name,name:de=Kastanienallee,Kastanienstrasse
266 Matches any object with a “name” or “name:de” tag with the value
267 “Kastanienallee” or “Kastanienstrasse”.
268 addr:* Matches all objects with any key starting with “addr:”
270 name=*Paris
272 Matches all objects with a name that contains the word “Paris”.
273 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 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 • type (`node', `way', or `relation')
292 • id (64 bit object ID)
294 • version (version number)
296 • changeset (changeset ID)
298 • timestamp (time of object creation in seconds since Jan 1 1970)
300 • uid (user ID)
302 • user (user name)
304 • way_nodes (ways only, array with node IDs)
306 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 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 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 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 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 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 Relation
347 A relation tagged type=multipolygon or type=boundary is always
348 (regardless of any tags) assembled into an area.
349 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 • geojson (alias: json): GeoJSON (RFC7946). The output file will con‐
367 tain a single FeatureCollection object. This is the default format.
368 • 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 • 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 • spaten: Spaten, a binary format that is suitable for large data sets.
382 • 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 • 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 0 if everything went alright,
400 1 if there was an error processing the data, or
402 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 osmium export data.osm.pbf -o data.geojson
415 Use a config file and export into GeoJSON Text Sequence format:
417 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 • Osmium website (https://osmcode.org/osmium-tool/)
425 • GeoJSON (http://geojson.org/)
427 • RFC7946 (https://tools.ietf.org/html/rfc7946)
429 • RFC8142 (https://tools.ietf.org/html/rfc8142)
431 • Line delimited JSON (https://en.wikipedia.org/wiki/JSON_Stream‐
433 ing#Line_delimited_JSON)
434 • Spaten Geo Format (https://thomas.skowron.eu/spaten/)
436
438 Copyright (C) 2013-2022 Jochen Topf <jochen@topf.org>.
439 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 1.14.0 OSMIUM-EXPORT(1)