1OSMIUM-EXPORT(1)                                              OSMIUM-EXPORT(1)
2
3
4

NAME

6       osmium-export - export OSM data
7

SYNOPSIS

9       osmium export [OPTIONS] OSM-FILE
10

DESCRIPTION

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

OPTIONS

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

COMMON OPTIONS

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

INPUT OPTIONS

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

OUTPUT OPTIONS

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

CONFIG FILE

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

FILTER EXPRESSIONS

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

ATTRIBUTES

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

AREA HANDLING

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

OUTPUT FORMATS

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

OUTPUT FORMAT OPTIONS

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

DIAGNOSTICS

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

MEMORY USAGE

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

EXAMPLES

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

SEE ALSO

421osmium(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

CONTACT

445       If  you  have  any  questions  or  want  to  report a bug, please go to
446       https://osmcode.org/contact.html
447

AUTHORS

449       Jochen Topf <jochen@topf.org>.
450
451
452
453                                    1.14.0                    OSMIUM-EXPORT(1)
Impressum