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://osm‐
64 code.org/osm-area-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 -i, --index-type=TYPE
80 Set the index type. For details see the osmium-index-types(5)
81 man page.
82 -I, --show-index-types
84 Shows a list of available index types. For details see the
85 osmium-index-types(5) man page. If you use this options all
86 other options are ignored.
87 -n, --keep-untagged
89 If this is set, features without any tags will be in the
90 exported data. By default these features will be omitted from
91 the output. Tags are the OSM tags, not attributes (like id,
92 version, uid, ...) without the tags removed by the exclude_tags
93 or include_tags settings.
94 -r, --omit-rs
96 Do not print the RS (0x1e, record separator) character when
97 using the GeoJSON Text Sequence Format. Ignored for other for‐
98 mats. THIS OPTION IS DEPRECATED, PLEASE USE “-x
99 print_record_separator=false” INSTEAD.
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
165 osmium 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
175 options 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,
207 areas will be created for all objects matching those expressions
208 and linestrings for everything else. This can be simpler,
209 because you only have to keep one list, but in cases where an
210 object 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
270 expression, the key is to the left and the value to the right. An
271 exclamation sign (“!”) before the equal sign means: A tag with that
272 key, but not the value(s) to the right of the equal sign. A leading or
273 trailing asterisk (“*”) can be used for substring or prefix matching,
274 respectively. Commas (“,”) can be used to separate several keys or
275 values.
276 All filter expressions are case-sensitive. There is no way to escape
278 the special characters such as “=”, “*” and “,”. You can not mix
279 comma-expressions and “*”-expressions.
280
282 All OSM objects (nodes, ways, and relations) have attributes, areas
283 inherit their attributes from the ways and/or relations they were cre‐
284 ated from. The attributes known to osmium export are:
285 · type (`node', `way', or `relation')
287 · id (64 bit object ID)
289 · version (version number)
291 · changeset (changeset ID)
293 · timestamp (time of object creation in seconds since Jan 1 1970)
295 · uid (user ID)
297 · user (user name)
299 · way_nodes (ways only, array with node IDs)
301 For areas, the type will be way or relation if the area was created
303 from a closed way or a multipolygon or boundary relation, respectively.
304 The id for areas is the id of the closed way or the multipolygon or
305 boundary relation.
306 By default the attributes will not be in the export, because they are
308 not necessary for most uses of OSM data. If you are interested in some
309 (or all) attributes, add an attributes object to the config file. Add
310 a member for each attribute you are interested in, the value can be
311 either false (do not output this attribute), true (output this
312 attribute with the attribute name prefixed by the @ sign) or any
313 string, in which case the string will be used as the attribute name.
314 Depending on your choice of values for the attributes objects,
316 attributes can have the same name as tag keys. If this is the case,
317 the conflicting tag is silently dropped. So if there is a tag
318 “@id=foo” and you have set id to true in the attributes object, the tag
319 will not show up in the output.
320 Note that the id is not necessarily unique. Even the combination type
322 and id is not unique, because a way may end up in the output file as
323 LineString and as (Multi)Polygon. See the --add-unique-id/-u option
324 for a unique ID.
325
327 Multipolygon relations will be assembled into multipolygon geometries
328 forming areas. Some closed ways will also form areas. Here are the
329 detailed rules:
330 Non-closed way
332 A non-closed way (with the last node location not the same as
333 the first node location) is always (regardless of any tags) a
334 linestring, not an area.
335 Relation
337 A relation tagged type=multipolygon or type=boundary is always
338 (regardless of any tags) assembled into an area.
339 Closed way
341 For a closed way (with the last node location the same as the
342 first node location) the tags are checked: If the way has an
343 area=yes tag, an area is created. If the way has an area=no
344 tag, a linestring is created. An area tag with a value other
345 than yes or no is ignored. The configuration settings area_tags
346 and linear_tags can be used to augment the area check. If any
347 of the tags matches the area_tags, an area is created. If any
348 of the tags matches the linear_tags, a linestring is created.
349 If both match, an area and a linestring is created. This is
350 important because some objects have tags that make them both, an
351 area and a linestring.
352
354 The following output formats are supported:
355 · geojson (alias: json): GeoJSON (RFC7946). The output file will con‐
357 tain a single FeatureCollection object. This is the default format.
358 · geojsonseq (alias: jsonseq): GeoJSON Text Sequence (RFC8142). Each
360 line (beginning with a RS (0x1e, record separator) and ending in a
361 linefeed character) contains one GeoJSON object. Used for streaming
362 GeoJSON.
363 · pg: PostgreSQL COPY text format. One line per object containing the
365 WGS84 geometry as WKB, the tags in JSON format and, optionally, more
366 columns for id and attributes. You have to create the table manu‐
367 ally, then use the PostgreSQL COPY command to import the data.
368 Enable verbose output to see the SQL commands needed to create the
369 table and load the data.
370 · spaten: Spaten, a binary format that is suitable for large data sets.
372 · text (alias: txt): A simple text format with the geometry in WKT for‐
374 mat followed by the comma-delimited tags. This is mainly intended
375 for debugging at the moment. THE FORMAT MIGHT CHANGE WITHOUT NOTICE!
376
378 · print_record_separator (default: true). Set to false to not print
379 the RS (0x1e, record separator) character when using the GeoJSON Text
380 Sequence Format. Ignored for other formats.
381 · tags_format (default: jsonb). Set to hstore to use HSTORE format
383 instead of JSON/JSONB when using the Pg Format. Ignored in other
384 formats.
385
387 osmium export exits with exit code
388 0 if everything went alright,
390 1 if there was an error processing the data, or
392 2 if there was a problem with the command line arguments.
394
396 osmium export will usually keep all node locations and all objects
397 needed for assembling the areas in memory. For larger data files, this
398 can need several tens of GBytes of memory. See the
399 osmium-index-types(5) man page for details.
400
402 Export into GeoJSON format:
403 osmium export data.osm.pbf -o data.geojson
405 Use a config file and export into GeoJSON Text Sequence format:
407 osmium export data.osm.pbf -o data.geojsonseq -c export-config.json
409
411 · osmium(1), osmium-file-formats(5), osmium-index-types(5),
412 osmium-add-node-locations-to-ways(1)
413 · Osmium website (https://osmcode.org/osmium-tool/)
415 · GeoJSON (http://geojson.org/)
417 · RFC7946 (https://tools.ietf.org/html/rfc7946)
419 · RFC8142 (https://tools.ietf.org/html/rfc8142)
421 · Line delimited JSON (https://en.wikipedia.org/wiki/JSON_Stream‐
423 ing#Line_delimited_JSON)
424 · Spaten Geo Format (https://thomas.skowron.eu/spaten/)
426
428 Copyright (C) 2013-2019 Jochen Topf <jochen@topf.org>.
429 License GPLv3+: GNU GPL version 3 or later
431 <https://gnu.org/licenses/gpl.html>. This is free software: you are
432 free to change and redistribute it. There is NO WARRANTY, to the
433 extent permitted by law.
434
436 If you have any questions or want to report a bug, please go to
437 https://osmcode.org/contact.html
438
440 Jochen Topf <jochen@topf.org>.
441 1.11.1 OSMIUM-EXPORT(1)