OSMIUM-GETPARENTS(1)

📦
version 1.19.1 · 6 versions
, in fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 OSMIUM-GETPARENTS — the manual, but make it make sense 💖

okay bestie, welcome to osmium-getparents(1), the manual page for the osmium getparents command. yes it's a real man page, yes it's from the osmium fam, and yes we're gonna get through it together. grab a snack 🍓

✨ NAME ✨

osmium-getparents — get parents of objects from an OSM file 🫶

✨ SYNOPSIS ✨

osmium getparents [OPTIONS] OSM-FILE ID...
osmium getparents [OPTIONS] OSM-FILE -i ID-FILE
osmium getparents [OPTIONS] OSM-FILE -I ID-OSM-FILE

🌸 DESCRIPTION 🌸

So the whole vibe here: you hand it some IDs, and it goes into the input file and finds every object that references the objects with those IDs, then writes them out. Meaning: it'll grab ways referencing any of your specified node IDs, and relations referencing any specified node, way, or relation IDs. it's giving "who's talking about you" energy 💅

But — and this is the part people always get wrong — it only resolves one level of indirection. So no relations of relations, and no relations referencing ways that reference your specified node IDs. One hop, that's it, periodt.

Your IDs can come from three places:

  • straight up on the command line (first case in the synopsis 👆)
  • read from text files with one ID per line (second case)
  • read from OSM files (third case)

and honestly? you can mix and match all three. no rules, live your truth 🌈

All objects with these IDs get read from OSM-FILE and written to the output. And if you throw in the --add-self/-s option, the objects with the specified IDs themselves get added to the output too. main character gets an invite to their own party ✨

Objects get written out in the order they're found in OSM-FILE. Not sorted, not alphabetical, just vibes-in-file-order.

The input file is read only once. efficient queen 👑

On the command line or in the ID file, IDs look like this: TYPE-LETTER NUMBER. The type letter is n for nodes, w for ways, and r for relations. No type letter? Then n for nodes is assumed — or whatever the --default-type option says. So "n13 w22 17 r21" matches nodes 13 and 17, way 22, and relation 21. lowkey elegant.

The order the IDs appear in does not matter. And identical IDs can show up multiple times on the command line or in the ID file(s) — it's not gonna be weird about it.

On the command line, your ID list can be in separate arguments, or all crammed into a single argument separated by spaces, tabs, commas (,), semicolons (;), forward slashes (/), or pipe characters (|). however you wanna serve it 🎀

In an ID file (--id-file/-i), every line must start with an ID in the format described above. Leading space characters on the line get ignored. Lines can optionally contain a space character or a hash sign (#) after the ID — anything after that is ignored. (This is also how you can read files in OPL format, sneaky.) Empty lines are ignored. clean.

⚠️ Important-ish caveat bestie: all objects get taken from OSM-FILE. The ID-OSM-FILE is only used to detect which objects to get. This might matter if there are different object versions in the different files. don't get caught out 🙈

OSM-FILE can be a history file, and then all matching versions of the objects get copied to the output. love that for you.

And finally: this command will not work with negative IDs. nope. not happening. 💀

✨ OPTIONS ✨

  • --default-type=TYPE — Use TYPE (node, way, or relation) for IDs that have no type prefix (default: node). You're also allowed to just use the first character of the type here. shortcuts, we love them.
  • -i, --id-file[=FILE] — Read IDs from a text file instead of from the command line. Use the special name - to read from STDIN. Every line of the file must start with an ID in the format described above. Lines can optionally contain a space character or a hash sign (#) after the ID — that character and everything after it is ignored. (Which, again, lets you read files in OPL format.) Empty lines are also ignored. This option can be used multiple times.
  • -I, --id-osm-file=OSMFILE — Like -i but get the IDs from an OSM file instead. Also usable multiple times.
  • -s, --add-self — Also add all objects with the specified IDs to the output. yes, them too.
  • --verbose-ids — Also print all requested IDs. Usually disabled, because these lists can get quite long (fr fr, we're talking huge). This option implies --verbose.

🦋 COMMON OPTIONS 🦋

  • -h, --help — Show usage help.
  • -v, --verbose — Set verbose mode. The program outputs info about what it's doing to STDERR.
  • --progress — Show a progress bar. Usually a progress bar is only displayed if STDOUT and STDERR are detected to be TTY. With this option it's always shown. Note that a progress bar will never be shown when reading from STDIN or a pipe.
  • --no-progress — Do not show a progress bar. Usually a progress bar is displayed if STDOUT and STDERR are detected to be a TTY. With this option it gets suppressed. And same deal: a progress bar will never be shown when reading from STDIN or a pipe.

🌈 INPUT OPTIONS 🌈

  • -F, --input-format=FORMAT — The format of the input file(s). Use this to set the input format when it can't be autodetected from the file name(s). Heads up: this sets the format for all input files — there is no way to set the format for just some of them. See osmium-file-formats(5) or the libosmium manual for the deets.

💜 OUTPUT OPTIONS 💜

  • -f, --output-format=FORMAT — The format of the output file. Use this to set the output file format when it can't be autodetected from the output file name. See osmium-file-formats(5) or the libosmium manual for details.
  • --fsync — Call fsync after writing the output file to force flushing buffers to disk. safety first ✨
  • --generator=NAME — The name and version of the program generating the output file. It gets added to the header of the output file. Default is osmium/ plus the version of osmium.
  • -o, --output=FILE — Name of the output file. Default is - (STDOUT).
  • -O, --overwrite — Allow an existing output file to be overwritten. Normally osmium refuses to write over an existing file. (it's protecting you 💖)
  • --output-header=OPTION=VALUE — Add an output header option. This command line option can be used multiple times for different OPTIONs. See the osmium-output-headers(5) man page for the list of available header options. For some commands you can use the special format OPTION! (that's an exclamation mark after the OPTION with no value set) to set the value to the same as in the input file.

🩺 DIAGNOSTICS 🩺

osmium getparents exits with exit code:

  • 0 — if there was no error. slay.
  • 1 — if there was an error processing the data. 😭
  • 2 — if there was a problem with the command line arguments. 🙈

🧠 MEMORY USAGE 🧠

osmium getparents does all its work on the fly and only keeps a table of all the IDs it needs in main memory. lightweight king 👑

🌟 EXAMPLES 🌟

Output all ways referencing nodes 17 or 1234, and all relations with nodes 17 or 1234, or way 42, or relation 111 as members, to STDOUT in OPL format:

osmium getparents -f opl planet.osm.pbf n1234 w42 n17 r111

look at that. one line. iconic. 💅

👀 SEE ALSO 👀

Copyright (C) 2013-2026 Jochen Topf <jochen@topf.org>.

License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

📬 CONTACT 📬

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

👑 AUTHORS 👑

Jochen Topf <jochen@topf.org>.

and that's the whole page bestie, you made it 🥳 this was osmium-getparents(1) from version 1.19.1 — go forth, find those parents, and remember: one level of indirection only. mwah 💋🦋

📦 where this page comes from