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 This command will not work on full history files.
42 This command will work with negative IDs on OSM objects (for instance
44 on files created with JOSM).
45
47 -c, –config=FILE
48 Read configuration from specified file.
49 -C, –print-default-config
51 Print the default config to STDOUT. Useful if you want to
52 change it and not write the whole thing manually. If you use
53 this option all other options are ignored.
54 -e, –show-errors
56 Output any geometry errors on STDERR. This includes ways with a
57 single node or areas that can't be assembled from multipolygon
58 relations. This output is not suitable for automated use, there
59 are other tools that can create very detailed errors reports
60 that are better for that (see https://osm‐
61 code.org/osm-area-tools/).
62 -E, –stop-on-error
64 Usually geometry errors (due to missing node locations or broken
65 polygons) are ignored and the features are omitted from the out‐
66 put. If this option is set, any error will immediately stop the
67 program.
68 –geometry-types=TYPES
70 Specify the geometry types that should be written out. Usually
71 all created geometries (points, linestrings, and (multi)poly‐
72 gons) are written to the output, but you can restrict the types
73 using this option. TYPES is a comma-separated list of the types
74 (“point”, “linestring”, and “polygon”).
75 -i, –index-type=TYPE
77 Set the index type. For details see the osmium-index-types(5)
78 man page.
79 -I, –show-index-types
81 Shows a list of available index types. For details see the
82 osmium-index-types(5) man page. If you use this options all
83 other options are ignored.
84 -n, –keep-untagged
86 If this is set, features without any tags will be in the
87 exported data. By default these features will be omitted from
88 the output. Tags are the OSM tags, not attributes (like id,
89 version, uid, ...) without the tags removed by the exclude_tags
90 or include_tags settings.
91 -r, –omit-rs
93 Do not print the RS (0x1e, record separator) character when
94 using the GeoJSON Text Sequence Format. Ignored for other for‐
95 mats.
96 -u, –add-unique-id=TYPE
98 Add a unique ID to each feature. TYPE can be either counter in
99 which case the first feature will get ID 1, the next ID 2 and so
100 on. The type of object does not matter in this case. Or the
101 TYPE is type_id in which case the ID is a string, the first
102 character is the type of object (`n' for nodes, `w' for
103 linestrings created from ways, and `a' for areas created from
104 ways and/or relations, after that there is a unique ID based on
105 the original OSM object ID(s). If the input file has negative
106 IDs, this can create IDs such as `w-12'.
107
109 -h, –help
110 Show usage help.
111 -v, –verbose
113 Set verbose mode. The program will output information about
114 what it is doing to STDERR.
115 –progress
117 Show progress bar. Usually a progress bar is only displayed if
118 STDOUT and STDERR are detected to be TTY. With this option a
119 progress bar is always shown. Note that a progress bar will
120 never be shown when reading from STDIN or a pipe.
121 –no-progress
123 Do not show progress bar. Usually a progress bar is displayed
124 if STDOUT and STDERR are detected to be a TTY. With this option
125 the progress bar is suppressed. Note that a progress bar will
126 never be shown when reading from STDIN or a pipe.
127
129 -F, –input-format=FORMAT
130 The format of the input file(s). Can be used to set the input
131 format if it can't be autodetected from the file name(s). This
132 will set the format for all input files, there is no way to set
133 the format for some input files only. See osmium-file-for‐
134 mats(5) or the libosmium manual for details.
135
137 -f, –output-format=FORMAT
138 The format of the output file. Can be used to set the output
139 file format if it can't be autodetected from the output file
140 name. See the OUTPUT FORMATS section for a list of formats.
141 –fsync Call fsync after writing the output file to force flushing buf‐
143 fers to disk.
144 -o, –output=FILE
146 Name of the output file. Default is `-' (STDOUT).
147 -O, –overwrite
149 Allow an existing output file to be overwritten. Normally
150 osmium will refuse to write over an existing file.
151
153 The config file is in JSON format. The top-level is an object which
154 contains the following optional names:
155 · attributes: An object specifying which attributes of OSM objects to
157 export. See the ATTRIBUTES section.
158 · linear_tags: An expression specifying tags that should be treated as
160 linear tags. See below for details and also look at the AREA HAN‐
161 DLING section.
162 · area_tags: An expression specifying tags that should be treated as
164 area tags. See below for details and also look at the AREA HANDLING
165 section.
166 · exclude_tags: A list of tag expressions. Tags matching these expres‐
168 sions are excluded from the output. See the FILTER EXPRESSION sec‐
169 tion.
170 · include_tags: A list of tag expressions. Tags matching these expres‐
172 sions are included in the output. See the FILTER EXPRESSION section.
173 The area_tags and linear_tags can have the following values:
175 true All tags match. (An empty list [] can also be used to mean the
177 same, but this use is deprecated because it can be confusing.)
178 false No tags match.
180 Array The array contains one or more expressions as described in the
182 FILTER EXPRESSION section.
183 null If the area_tags or linear_tags is set to null or not set at
185 all, the inverse of the other setting is used. So if you do not
186 set the linear_tags but have some expressions in area_tags,
187 areas will be created for all objects matching those expressions
188 and linestrings for everything else. This can be simpler,
189 because you only have to keep one list, but in cases where an
190 object can be interpreted as both an area and a linestring, only
191 one interpretation will be used.
192 The exclude_tags and include_tags options are mutually exclusive. If
194 you want to just exclude some tags but leave most tags untouched, use
195 the exclude_tags setting. If you only want a defined list of tags, use
196 include_tags.
197 When no config file is specified, the following settings are used:
199 {
201 "attributes": {
202 "type": false,
203 "id": false,
204 "version": false,
205 "changeset": false,
206 "timestamp": false,
207 "uid": false,
208 "user": false,
209 "way_nodes": false
210 },
211 "linear_tags": true,
212 "area_tags": true,
213 "exclude_tags": [],
214 "include_tags": []
215 }
216
218 A filter expression specifies a tag or tags that should be matched in
219 the data.
220 Some examples:
222 amenity
224 Matches all objects with the key “amenity”.
225 highway=primary
227 Matches all objects with the key “highway” and value “primary”.
228 highway!=primary
230 Matches all objects with the key “highway” and a value other
231 than “primary”.
232 type=multipolygon,boundary
234 Matches all objects with key “type” and value “multipolygon” or
235 “boundary”.
236 name,name:de=Kastanienallee,Kastanienstrasse
238 Matches any object with a “name” or “name:de” tag with the value
239 “Kastanienallee” or “Kastanienstrasse”.
240 addr:* Matches all objects with any key starting with “addr:”
242 name=*Paris
244 Matches all objects with a name that contains the word “Paris”.
245 If there is no equal sign (“=”) in the expression only keys are matched
247 and values can be anything. If there is an equal sign (“=”) in the
248 expression, the key is to the left and the value to the right. An
249 exclamation sign (“!”) before the equal sign means: A tag with that
250 key, but not the value(s) to the right of the equal sign. A leading or
251 trailing asterisk (“*”) can be used for substring or prefix matching,
252 respectively. Commas (“,”) can be used to separate several keys or
253 values.
254 All filter expressions are case-sensitive. There is no way to escape
256 the special characters such as “=”, “*” and “,”. You can not mix
257 comma-expressions and “*”-expressions.
258
260 All OSM objects (nodes, ways, and relations) have attributes, areas
261 inherit their attributes from the ways and/or relations they were cre‐
262 ated from. The attributes known to osmium export are:
263 · type (`node', `way', or `relation')
265 · id (64 bit object ID)
267 · version (version number)
269 · changeset (changeset ID)
271 · timestamp (time of object creation in seconds since Jan 1 1970)
273 · uid (user ID)
275 · user (user name)
277 · way_nodes (ways only, array with node IDs)
279 For areas, the type will be way or relation if the area was created
281 from a closed way or a multipolygon or boundary relation, respectively.
282 The id for areas is the id of the closed way or the multipolygon or
283 boundary relation.
284 By default the attributes will not be in the export, because they are
286 not necessary for most uses of OSM data. If you are interested in some
287 (or all) attributes, add an attributes object to the config file. Add
288 a member for each attribute you are interested in, the value can be
289 either false (do not output this attribute), true (output this
290 attribute with the attribute name prefixed by the @ sign) or any
291 string, in which case the string will be used as the attribute name.
292 Depending on your choice of values for the attributes objects,
294 attributes can have the same name as tag keys. If this is the case,
295 the conflicting tag is silently dropped. So if there is a tag
296 “@id=foo” and you have set id to true in the attributes object, the tag
297 will not show up in the output.
298 Note that the id is not necessarily unique. Even the combination type
300 and id is not unique, because a way may end up in the output file as
301 LineString and as (Multi)Polygon. See the --add-unique-id option for a
302 unique ID.
303
305 Multipolygon relations will be assembled into multipolygon geometries
306 forming areas. Some closed ways will also form areas. Here are the
307 detailed rules:
308 Non-closed way
310 A non-closed way (with the last node location not the same as
311 the first node location) is always (regardless of any tags) a
312 linestring, not an area.
313 Relation
315 A relation tagged type=multipolygon or type=boundary is always
316 (regardless of any tags) assembled into an area.
317 Closed way
319 For a closed way (with the last node location the same as the
320 first node location) the tags are checked: If the way has an
321 area=yes tag, an area is created. If the way has an area=no
322 tag, a linestring is created. An area tag with a value other
323 than yes or no is ignored. The configuration settings area_tags
324 and linear_tags can be used to augment the area check. If any
325 of the tags matches the area_tags, an area is created. If any
326 of the tags matches the linear_tags, a linestring is created.
327 If both match, an area and a linestring is created. This is
328 important because some objects have tags that make them both, an
329 area and a linestring.
330
332 The following output formats are supported:
333 · geojson (alias: json): GeoJSON (RFC7946). The output file will con‐
335 tain a single FeatureCollection object. This is the default format.
336 · geojsonseq (alias: jsonseq): GeoJSON Text Sequence (RFC8142). Each
338 line (beginning with a RS (0x1e, record separator) and ending in a
339 linefeed character) contains one GeoJSON object. Used for streaming
340 GeoJSON.
341 · pg: PostgreSQL COPY text format. One line per object containing the
343 WGS84 geometry as WKB, the tags in JSON format and, optionally, more
344 columns for id and attributes. You have to create the table manu‐
345 ally, then use the PostgreSQL COPY command to import the data.
346 Enable verbose output to see the SQL commands needed to create the
347 table and load the data.
348 · text (alias: txt): A simple text format with the geometry in WKT for‐
350 mat followed by the comma-delimited tags. This is mainly intended
351 for debugging at the moment. THE FORMAT MIGHT CHANGE WITHOUT NOTICE!
352
354 osmium export exits with exit code
355 0 if everything went alright,
357 1 if there was an error processing the data, or
359 2 if there was a problem with the command line arguments.
361
363 osmium export will usually keep all node locations and all objects
364 needed for assembling the areas in memory. For larger data files, this
365 can need several tens of GBytes of memory. See the
366 osmium-index-types(5) man page for details.
367
369 Export into GeoJSON format:
370 osmium export data.osm.pbf -o data.geojson
372 Use a config file and export into GeoJSON Text Sequence format:
374 osmium export data.osm.pbf -o data.geojsonseq -c export-config.json
376
378 · osmium(1), osmium-file-formats(5), osmium-index-types(5),
379 osmium-add-node-locations-to-ways(1)
380 · Osmium website (https://osmcode.org/osmium-tool/)
382 · GeoJSON (http://geojson.org/)
384 · RFC7946 (https://tools.ietf.org/html/rfc7946)
386 · RFC8142 (https://tools.ietf.org/html/rfc8142)
388 · Line delimited JSON (https://en.wikipedia.org/wiki/JSON_Stream‐
390 ing#Line_delimited_JSON)
391
393 Copyright (C) 2013-2018 Jochen Topf <jochen@topf.org>.
394 License GPLv3+: GNU GPL version 3 or later
396 <https://gnu.org/licenses/gpl.html>. This is free software: you are
397 free to change and redistribute it. There is NO WARRANTY, to the
398 extent permitted by law.
399
401 If you have any questions or want to report a bug, please go to
402 https://osmcode.org/contact.html
403
405 Jochen Topf <jochen@topf.org>.
406 1.10.0 OSMIUM-EXPORT(1)