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 -u, --add-unique-id=TYPE
102 Add a unique ID to each feature. TYPE can be either counter in
103 which case the first feature will get ID 1, the next ID 2 and so
104 on. The type of object does not matter in this case. Or the
105 TYPE is type_id in which case the ID is a string, the first
106 character is the type of object (`n' for nodes, `w' for
107 linestrings created from ways, and `a' for areas created from
108 ways and/or relations, after that there is a unique ID based on
109 the original OSM object ID(s). If the input file has negative
110 IDs, this can create IDs such as `w-12'. In spaten exports the
111 ID is written into the @fid field. For counter the value will
112 be an integer, for type_id it will be a string.
113 -x, --format-option=OPTION(=VALUE)
115 Set an output format option. The options available depend on
116 the output format. See the OUTPUT FORMAT OPTIONS section for
117 available options. If the VALUE is not set, the OPTION will be
118 set to “true”. If needed you can specify this option multiple
119 times to set several options. Options set on the command line
120 overwrite options set in the config file.
121
123 -h, --help
124 Show usage help.
125 -v, --verbose
127 Set verbose mode. The program will output information about
128 what it is doing to STDERR.
129 --progress
131 Show progress bar. Usually a progress bar is only displayed if
132 STDOUT and STDERR are detected to be TTY. With this option a
133 progress bar is always shown. Note that a progress bar will
134 never be shown when reading from STDIN or a pipe.
135 --no-progress
137 Do not show progress bar. Usually a progress bar is displayed
138 if STDOUT and STDERR are detected to be a TTY. With this option
139 the progress bar is suppressed. Note that a progress bar will
140 never be shown when reading from STDIN or a pipe.
141
143 -F, --input-format=FORMAT
144 The format of the input file(s). Can be used to set the input
145 format if it can’t be autodetected from the file name(s). This
146 will set the format for all input files, there is no way to set
147 the format for some input files only. See osmium-file-for‐
148 mats(5) or the libosmium manual for details.
149
151 -f, --output-format=FORMAT
152 The format of the output file. Can be used to set the output
153 file format if it can’t be autodetected from the output file
154 name. See the OUTPUT FORMATS section for a list of formats.
155 --fsync
157 Call fsync after writing the output file to force flushing buf‐
158 fers to disk.
159 -o, --output=FILE
161 Name of the output file. Default is `-' (STDOUT).
162 -O, --overwrite
164 Allow an existing output file to be overwritten. Normally os‐
165 mium will refuse to write over an existing file.
166
168 The config file is in JSON format. The top-level is an object which
169 contains the following optional names:
170 • attributes: An object specifying which attributes of OSM objects to
172 export. See the ATTRIBUTES section.
173 • format_options: An object specifying output format options. The op‐
175 tions available depend on the output format. See the OUTPUT FORMAT
176 OPTIONS section for available options. These options can also be set
177 using the command line option --format-option/-x.
178 • linear_tags: An expression specifying tags that should be treated as
180 linear tags. See below for details and also look at the AREA HAN‐
181 DLING section.
182 • area_tags: An expression specifying tags that should be treated as
184 area tags. See below for details and also look at the AREA HANDLING
185 section.
186 • exclude_tags: A list of tag expressions. Tags matching these expres‐
188 sions are excluded from the output. See the FILTER EXPRESSION sec‐
189 tion.
190 • include_tags: A list of tag expressions. Tags matching these expres‐
192 sions are included in the output. See the FILTER EXPRESSION section.
193 The area_tags and linear_tags can have the following values:
195 true All tags match. (An empty list [] can also be used to mean the
197 same, but this use is deprecated because it can be confusing.)
198 false No tags match.
200 Array The array contains one or more expressions as described in the
202 FILTER EXPRESSION section.
203 null If the area_tags or linear_tags is set to null or not set at
205 all, the inverse of the other setting is used. So if you do not
206 set the linear_tags but have some expressions in area_tags, ar‐
207 eas will be created for all objects matching those expressions
208 and linestrings for everything else. This can be simpler, be‐
209 cause you only have to keep one list, but in cases where an ob‐
210 ject can be interpreted as both an area and a linestring, only
211 one interpretation will be used.
212 The exclude_tags and include_tags options are mutually exclusive. If
214 you want to just exclude some tags but leave most tags untouched, use
215 the exclude_tags setting. If you only want a defined list of tags, use
216 include_tags.
217 When no config file is specified, the following settings are used:
219 {
221 "attributes": {
222 "type": false,
223 "id": false,
224 "version": false,
225 "changeset": false,
226 "timestamp": false,
227 "uid": false,
228 "user": false,
229 "way_nodes": false
230 },
231 "format_options": {
232 },
233 "linear_tags": true,
234 "area_tags": true,
235 "exclude_tags": [],
236 "include_tags": []
237 }
238
240 A filter expression specifies a tag or tags that should be matched in
241 the data.
242 Some examples:
244 amenity
246 Matches all objects with the key “amenity”.
247 highway=primary
249 Matches all objects with the key “highway” and value “primary”.
250 highway!=primary
252 Matches all objects with the key “highway” and a value other
253 than “primary”.
254 type=multipolygon,boundary
256 Matches all objects with key “type” and value “multipolygon” or
257 “boundary”.
258 name,name:de=Kastanienallee,Kastanienstrasse
260 Matches any object with a “name” or “name:de” tag with the value
261 “Kastanienallee” or “Kastanienstrasse”.
262 addr:* Matches all objects with any key starting with “addr:”
264 name=*Paris
266 Matches all objects with a name that contains the word “Paris”.
267 If there is no equal sign (“=”) in the expression only keys are matched
269 and values can be anything. If there is an equal sign (“=”) in the ex‐
270 pression, the key is to the left and the value to the right. An excla‐
271 mation sign (“!”) before the equal sign means: A tag with that key, but
272 not the value(s) to the right of the equal sign. A leading or trailing
273 asterisk (“*”) can be used for substring or prefix matching, respec‐
274 tively. Commas (“,”) can be used to separate several keys or values.
275 All filter expressions are case-sensitive. There is no way to escape
277 the special characters such as “=”, “*” and “,”. You can not mix
278 comma-expressions and “*”-expressions.
279
281 All OSM objects (nodes, ways, and relations) have attributes, areas in‐
282 herit their attributes from the ways and/or relations they were created
283 from. The attributes known to osmium export are:
284 • type (`node', `way', or `relation')
286 • id (64 bit object ID)
288 • version (version number)
290 • changeset (changeset ID)
292 • timestamp (time of object creation in seconds since Jan 1 1970)
294 • uid (user ID)
296 • user (user name)
298 • way_nodes (ways only, array with node IDs)
300 For areas, the type will be way or relation if the area was created
302 from a closed way or a multipolygon or boundary relation, respectively.
303 The id for areas is the id of the closed way or the multipolygon or
304 boundary relation.
305 By default the attributes will not be in the export, because they are
307 not necessary for most uses of OSM data. If you are interested in some
308 (or all) attributes, add an attributes object to the config file. Add
309 a member for each attribute you are interested in, the value can be ei‐
310 ther false (do not output this attribute), true (output this attribute
311 with the attribute name prefixed by the @ sign) or any string, in which
312 case the string will be used as the attribute name.
313 Another option is to specify attributes list in a comma-separated
315 string for the --attributes/-a command-line option. This way you can‐
316 not control column names, but also you won’t have to create a config
317 file.
318 Depending on your choice of values for the attributes objects, at‐
320 tributes can have the same name as tag keys. If this is the case, the
321 conflicting tag is silently dropped. So if there is a tag “@id=foo”
322 and you have set id to true in the attributes object, the tag will not
323 show up in the output.
324 Note that the id is not necessarily unique. Even the combination type
326 and id is not unique, because a way may end up in the output file as
327 LineString and as (Multi)Polygon. See the --add-unique-id/-u option
328 for a unique ID.
329
331 Multipolygon relations will be assembled into multipolygon geometries
332 forming areas. Some closed ways will also form areas. Here are the
333 detailed rules:
334 Non-closed way
336 A non-closed way (with the last node location not the same as
337 the first node location) is always (regardless of any tags) a
338 linestring, not an area.
339 Relation
341 A relation tagged type=multipolygon or type=boundary is always
342 (regardless of any tags) assembled into an area.
343 Closed way
345 For a closed way (with the last node location the same as the
346 first node location) the tags are checked: If the way has an
347 area=yes tag, an area is created. If the way has an area=no
348 tag, a linestring is created. An area tag with a value other
349 than yes or no is ignored. The configuration settings area_tags
350 and linear_tags can be used to augment the area check. If any
351 of the tags matches the area_tags, an area is created. If any
352 of the tags matches the linear_tags, a linestring is created.
353 If both match, an area and a linestring is created. This is im‐
354 portant because some objects have tags that make them both, an
355 area and a linestring.
356
358 The following output formats are supported:
359 • geojson (alias: json): GeoJSON (RFC7946). The output file will con‐
361 tain a single FeatureCollection object. This is the default format.
362 • geojsonseq (alias: jsonseq): GeoJSON Text Sequence (RFC8142). Each
364 line (beginning with a RS (0x1e, record separator) and ending in a
365 linefeed character) contains one GeoJSON object. Used for streaming
366 GeoJSON.
367 • pg: PostgreSQL COPY text format. One line per object containing the
369 WGS84 geometry as WKB, the tags in JSON format and, optionally, more
370 columns for id and attributes. You have to create the table manu‐
371 ally, then use the PostgreSQL COPY command to import the data. En‐
372 able verbose output to see the SQL commands needed to create the ta‐
373 ble and load the data.
374 • spaten: Spaten, a binary format that is suitable for large data sets.
376 • text (alias: txt): A simple text format with the geometry in WKT for‐
378 mat followed by the comma-delimited tags. This is mainly intended
379 for debugging at the moment. THE FORMAT MIGHT CHANGE WITHOUT NOTICE!
380
382 • print_record_separator (default: true). Set to false to not print
383 the RS (0x1e, record separator) character when using the GeoJSON Text
384 Sequence Format. Ignored for other formats.
385 • tags_type (default: jsonb). Set to hstore to use HSTORE format in‐
387 stead of JSON/JSONB when using the Pg Format. Ignored in other for‐
388 mats.
389
391 osmium export exits with exit code
392 0 if everything went alright,
394 1 if there was an error processing the data, or
396 2 if there was a problem with the command line arguments.
398
400 osmium export will usually keep all node locations and all objects
401 needed for assembling the areas in memory. For larger data files, this
402 can need several tens of GBytes of memory. See the osmium-index-
403 types(5) man page for details.
404
406 Export into GeoJSON format:
407 osmium export data.osm.pbf -o data.geojson
409 Use a config file and export into GeoJSON Text Sequence format:
411 osmium export data.osm.pbf -o data.geojsonseq -c export-config.json
413
415 • osmium(1), osmium-file-formats(5), osmium-index-types(5), osmium-add-
416 node-locations-to-ways(1)
417 • Osmium website (https://osmcode.org/osmium-tool/)
419 • GeoJSON (http://geojson.org/)
421 • RFC7946 (https://tools.ietf.org/html/rfc7946)
423 • RFC8142 (https://tools.ietf.org/html/rfc8142)
425 • Line delimited JSON (https://en.wikipedia.org/wiki/JSON_Stream‐
427 ing#Line_delimited_JSON)
428 • Spaten Geo Format (https://thomas.skowron.eu/spaten/)
430
432 Copyright (C) 2013-2023 Jochen Topf <jochen@topf.org>.
433 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/li‐
435 censes/gpl.html>. This is free software: you are free to change and
436 redistribute it. There is NO WARRANTY, to the extent permitted by law.
437
439 If you have any questions or want to report a bug, please go to
440 https://osmcode.org/contact.html
441
443 Jochen Topf <jochen@topf.org>.
444 1.16.0 OSMIUM-EXPORT(1)