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       -i, --index-type=TYPE
80              Set the index type.  For details see  the  osmium-index-types(5)
81              man page.
82
83       -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
88       -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
95       -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
101       -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
114       -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

COMMON OPTIONS

123       -h, --help
124              Show usage help.
125
126       -v, --verbose
127              Set  verbose  mode.   The  program will output information about
128              what it is doing to STDERR.
129
130       --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
136       --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

INPUT OPTIONS

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

OUTPUT OPTIONS

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
156       --fsync
157              Call fsync after writing the output file to force flushing  buf‐
158              fers to disk.
159
160       -o, --output=FILE
161              Name of the output file.  Default is `-' (STDOUT).
162
163       -O, --overwrite
164              Allow  an  existing  output  file  to  be overwritten.  Normally
165              osmium will refuse to write over an existing file.
166

CONFIG FILE

168       The config file is in JSON format.  The top-level is  an  object  which
169       contains the following optional names:
170
171       · attributes:  An  object specifying which attributes of OSM objects to
172         export.  See the ATTRIBUTES section.
173
174       · 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
179       · 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
183       · 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
187       · 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
191       · include_tags: A list of tag expressions.  Tags matching these expres‐
192         sions are included in the output.  See the FILTER EXPRESSION section.
193
194       The area_tags and linear_tags can have the following values:
195
196       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
199       false  No tags match.
200
201       Array  The  array  contains one or more expressions as described in the
202              FILTER EXPRESSION section.
203
204       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
213       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
218       When no config file is specified, the following settings are used:
219
220              {
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

FILTER EXPRESSIONS

240       A filter expression specifies a tag or tags that should be  matched  in
241       the data.
242
243       Some examples:
244
245       amenity
246              Matches all objects with the key “amenity”.
247
248       highway=primary
249              Matches all objects with the key “highway” and value “primary”.
250
251       highway!=primary
252              Matches  all  objects  with  the key “highway” and a value other
253              than “primary”.
254
255       type=multipolygon,boundary
256              Matches all objects with key “type” and value “multipolygon”  or
257              “boundary”.
258
259       name,name:de=Kastanienallee,Kastanienstrasse
260              Matches any object with a “name” or “name:de” tag with the value
261              “Kastanienallee” or “Kastanienstrasse”.
262
263       addr:* Matches all objects with any key starting with “addr:”
264
265       name=*Paris
266              Matches all objects with a name that contains the word “Paris”.
267
268       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
277       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

ATTRIBUTES

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
286       · type (`node', `way', or `relation')
287
288       · id (64 bit object ID)
289
290       · version (version number)
291
292       · changeset (changeset ID)
293
294       · timestamp (time of object creation in seconds since Jan 1 1970)
295
296       · uid (user ID)
297
298       · user (user name)
299
300       · way_nodes (ways only, array with node IDs)
301
302       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
307       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
315       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
321       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

AREA HANDLING

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
331       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
336       Relation
337              A  relation  tagged type=multipolygon or type=boundary is always
338              (regardless of any tags) assembled into an area.
339
340       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

OUTPUT FORMATS

354       The following output formats are supported:
355
356       · geojson (alias: json): GeoJSON (RFC7946).  The output file will  con‐
357         tain a single FeatureCollection object.  This is the default format.
358
359       · 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
364       · 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
371       · spaten: Spaten, a binary format that is suitable for large data sets.
372
373       · 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

OUTPUT FORMAT OPTIONS

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
382       · 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

DIAGNOSTICS

387       osmium export exits with exit code
388
389       0      if everything went alright,
390
391       1      if there was an error processing the data, or
392
393       2      if there was a problem with the command line arguments.
394

MEMORY USAGE

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 osmium-index-
399       types(5) man page for details.
400

EXAMPLES

402       Export into GeoJSON format:
403
404              osmium export data.osm.pbf -o data.geojson
405
406       Use a config file and export into GeoJSON Text Sequence format:
407
408              osmium export data.osm.pbf -o data.geojsonseq -c export-config.json
409

SEE ALSO

411       · osmium(1), osmium-file-formats(5), osmium-index-types(5), osmium-add-
412         node-locations-to-ways(1)
413
414       · Osmium website (https://osmcode.org/osmium-tool/)
415
416       · GeoJSON (http://geojson.org/)
417
418       · RFC7946 (https://tools.ietf.org/html/rfc7946)
419
420       · RFC8142 (https://tools.ietf.org/html/rfc8142)
421
422       · Line   delimited   JSON   (https://en.wikipedia.org/wiki/JSON_Stream
423         ing#Line_delimited_JSON)
424
425       · Spaten Geo Format (https://thomas.skowron.eu/spaten/)
426
428       Copyright (C) 2013-2020 Jochen Topf <jochen@topf.org>.
429
430       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

CONTACT

436       If  you  have  any  questions  or  want  to  report a bug, please go to
437       https://osmcode.org/contact.html
438

AUTHORS

440       Jochen Topf <jochen@topf.org>.
441
442
443
444                                    1.12.1                    OSMIUM-EXPORT(1)
Impressum