API Reference

read_pbf(filename; node_callback, way_callback, relation_callback)

Read OpenStreetMap data from a PBF (Protocol Buffer Format) file.

Arguments

• filename::String: Path to the PBF file to read

Keyword Arguments

• node_callback::Union{Function,Nothing}=nothing: Optional callback function for filtering nodes
• way_callback::Union{Function,Nothing}=nothing: Optional callback function for filtering ways
• relation_callback::Union{Function,Nothing}=nothing: Optional callback function for filtering relations

Callback Functions

Callback functions should accept one argument of the respective type (Node, Way, or Relation) and return either:

• An object of the same type (element will be included in the result)
• nothing (element will be excluded from the result)

Returns

• OpenStreetMap: Complete OSM dataset with nodes, ways, relations, and metadata

Examples

# Read all data
osmdata = read_pbf("map.pbf")

# Filter to only include restaurants
function keep_restaurants(node)
    if node.tags !== nothing && haskey(node.tags, "amenity") && node.tags["amenity"] == "restaurant"
        return node
    end
    return nothing
end
osmdata = read_pbf("map.pbf", node_callback=keep_restaurants)

# Filter multiple element types
osmdata = read_pbf("map.pbf",
    node_callback=keep_restaurants,
    way_callback=way -> way.tags !== nothing && haskey(way.tags, "highway") ? way : nothing
)

See Also

• read_osm: Read OSM XML files
• fetch_overpass: Query data from Overpass API

read_osm(filename; node_callback, way_callback, relation_callback)

Read OpenStreetMap data from an XML file.

Arguments

• filename::String: Path to the OSM XML file to read

Keyword Arguments

• node_callback::Union{Function,Nothing}=nothing: Optional callback function for filtering nodes
• way_callback::Union{Function,Nothing}=nothing: Optional callback function for filtering ways
• relation_callback::Union{Function,Nothing}=nothing: Optional callback function for filtering relations

Callback Functions

Callback functions should accept one argument of the respective type (Node, Way, or Relation) and return either:

• An object of the same type (element will be included in the result)
• nothing (element will be excluded from the result)

Returns

• OpenStreetMap: Complete OSM dataset with nodes, ways, relations, and metadata

Examples

# Read all data
osmdata = read_osm("map.osm")

# Filter to only include restaurants
function keep_restaurants(node)
    if node.tags !== nothing && haskey(node.tags, "amenity") && node.tags["amenity"] == "restaurant"
        return node
    end
    return nothing
end
osmdata = read_osm("map.osm", node_callback=keep_restaurants)

See Also

• read_pbf: Read OSM PBF files
• fetch_overpass: Query data from Overpass API

fetch_overpass(bbox; kwargs...)

Query OpenStreetMap data from Overpass API using a bounding box.

Arguments

• bbox::BBox: Geographic bounding box to query

Keyword Arguments

• timeout::Int64=25: Query timeout in seconds

Returns

• OpenStreetMap: OSM data within the specified bounding box

Examples

bbox = BBox(54.0, 9.0, 55.0, 10.0)
osmdata = fetch_overpass(bbox)

fetch_overpass(position, radius; kwargs...)

Query OpenStreetMap data from Overpass API using a center point and radius.

Arguments

• position::Position: Center point for the query
• radius::Real: Radius in meters around the center point

Keyword Arguments

• timeout::Int64=25: Query timeout in seconds

Returns

• OpenStreetMap: OSM data within the specified radius

Examples

center = Position(54.2619665, 9.9854149)
osmdata = fetch_overpass(center, 1000)  # 1km radius

fetch_overpass(bounds; timeout)

Query OpenStreetMap data from Overpass API using a bounds string.

Arguments

• bounds::String: Bounds string in Overpass API format (e.g., "54.0,9.0,55.0,10.0" or "around:1000,54.0,9.0")

Keyword Arguments

• timeout::Int64=25: Query timeout in seconds

Returns

• OpenStreetMap: OSM data matching the query

Examples

# Bounding box query
osmdata = fetch_overpass("54.0,9.0,55.0,10.0")

# Radius query
osmdata = fetch_overpass("around:1000,54.2619665,9.9854149")

See Also

• read_pbf: Read OSM PBF files
• read_osm: Read OSM XML files

OpenStreetMap

Container for complete OpenStreetMap data including nodes, ways, relations, and metadata.

Fields

• nodes::Dict{Int64,Node}: Dictionary mapping node IDs to Node objects
• ways::Dict{Int64,Way}: Dictionary mapping way IDs to Way objects
• relations::Dict{Int64,Relation}: Dictionary mapping relation IDs to Relation objects
• meta::Dict{String,Any}: Metadata about the dataset (bounding box, timestamps, etc.)

Constructors

• OpenStreetMap(): Create empty OpenStreetMap object
• OpenStreetMap(nodes, ways, relations, meta): Create with pre-populated data

Examples

osmdata = OpenStreetMap()
osmdata = read_pbf("map.pbf")  # Load from file

Node

Represents an OpenStreetMap node (point) with geographic coordinates and optional tags.

Fields

• position::Position: Geographic coordinates of the node
• tags::Union{Dict{String,String},Nothing}: Key-value pairs describing the node, or nothing if no tags
• info::Union{Info,Nothing}: Optional metadata (version, timestamp, changeset, user, etc.)

Examples

node = Node(Position(54.2619665, 9.9854149), Dict("amenity" => "restaurant"), nothing)

Way

Represents an OpenStreetMap way (path) as an ordered list of node references.

Fields

• refs::Vector{Int64}: Ordered list of node IDs that form the way
• tags::Union{Dict{String,String},Nothing}: Key-value pairs describing the way, or nothing if no tags
• info::Union{Info,Nothing}: Optional metadata (version, timestamp, changeset, user, etc.)
• positions::Union{Vector{Position},Nothing}: Optional node locations (LocationsOnWays feature)

Examples

way = Way([12345, 67890, 11111], Dict("highway" => "primary"), nothing, nothing)

Relation

Represents an OpenStreetMap relation (grouping) of nodes, ways, and other relations.

Fields

• refs::Vector{Int64}: List of element IDs that are members of this relation
• types::Vector{String}: Types of each member ("node", "way", or "relation")
• roles::Vector{String}: Roles of each member in the relation
• tags::Union{Dict{String,String},Nothing}: Key-value pairs describing the relation, or nothing if no tags
• info::Union{Info,Nothing}: Optional metadata (version, timestamp, changeset, user, etc.)

Examples

relation = Relation([12345, 67890], ["node", "way"], ["stop", "platform"], Dict("route" => "bus"), nothing)

BBox

Represents a geographic bounding box with latitude and longitude boundaries.

Fields

• bottom_lat::Float64: Minimum latitude (southern boundary)
• left_lon::Float64: Minimum longitude (western boundary)
• top_lat::Float64: Maximum latitude (northern boundary)
• right_lon::Float64: Maximum longitude (eastern boundary)

Examples

bbox = BBox(54.0, 9.0, 55.0, 10.0)  # lat_min, lon_min, lat_max, lon_max

Position

Represents a geographic coordinate with latitude and longitude.

Fields

• lat::Float64: Latitude in decimal degrees (-90 to 90)
• lon::Float64: Longitude in decimal degrees (-180 to 180)

Examples

coord = Position(54.2619665, 9.9854149)

Info

Optional metadata for OSM elements (nodes, ways, relations). Contains versioning and attribution information.

Fields

• version::Union{Int32,Nothing}: Version number of this element
• timestamp::Union{DateTime,Nothing}: Last modification timestamp
• changeset::Union{Int64,Nothing}: Changeset ID that created/modified this version
• uid::Union{Int32,Nothing}: User ID of the modifier
• user::Union{String,Nothing}: Username of the modifier
• visible::Union{Bool,Nothing}: Visibility flag (for historical data)

Examples

info = Info(1, DateTime(2023, 1, 1), 12345, 100, "mapper", true)
info_minimal = Info(nothing, nothing, nothing, nothing, nothing, nothing)