API

Types

Element 

Element

Abstract supertype for all OSM element types (Node, Way, Relation).

All subtypes have id::Int64 and tags::Dict{String,String} fields.

LatLon 

LatLon(lat, lon)

A lightweight latitude/longitude coordinate pair. Implements GeoInterface.PointTrait.

Examples

julia> p = LatLon(40.748, -73.985)
LatLon(40.748, -73.985)

julia> GeoInterface.x(p)
-73.985

julia> GeoInterface.y(p)
40.748

Member 

Member

A member of an OSM relation.

Fields

  • type::String: Element type ("node", "way", or "relation").
  • ref::Int64: OSM ID of the referenced element.
  • role::String: Role within the relation (e.g. "outer", "inner", "stop").
  • geometry::Vector{LatLon}: Coordinates (populated when query uses out geom).

Examples

julia> m = Member(type="way", ref=123, role="outer")
Member("way", 123, "outer", LatLon[])

Node 

Node <: Element

An OpenStreetMap node (point feature). Implements GeoInterface.PointTrait.

Fields

  • id::Int64: OSM node ID.
  • lat::Float64: Latitude.
  • lon::Float64: Longitude.
  • tags::Dict{String,String}: Key-value tags.

Examples

julia> n = Node(id=1, lat=40.748, lon=-73.985, tags=Dict("name" => "Example"))
Node(1, 40.748, -73.985, Dict("name" => "Example"))

OverpassResponse 

OverpassResponse

The parsed response from an Overpass API query.

Fields

  • version::Float64: API version (typically 0.6).
  • generator::String: Generator string from the API.
  • timestamp::String: OSM data timestamp.
  • elements::Vector{Element}: All returned elements.

Examples

julia> r = query("node[amenity=cafe](35.9,-79.1,36.1,-78.8); out geom;")

julia> nodes(r)  # filter to just Node elements

julia> ways(r)   # filter to just Way elements

QLStatement 

QLStatement

A composable Overpass QL statement built using OQL with dot and bracket syntax.

Use overpass_ql to convert to a string, or pass directly to query.

Examples

julia> OQL.node["amenity" => "cafe"]
node[amenity=cafe]

julia> OQL.way["building"]["name" => r"^Duke"i]
way[building][name~"^Duke",i]

Relation 

Relation <: Element

An OpenStreetMap relation (a group of elements with roles).

Fields

  • id::Int64: OSM relation ID.
  • tags::Dict{String,String}: Key-value tags.
  • members::Vector{Member}: Ordered list of members.

Examples

julia> r = Relation(id=1, tags=Dict("type" => "multipolygon"),
               members=[Member(type="way", ref=100, role="outer")])

Way 

Way <: Element

An OpenStreetMap way (line or polygon feature). Implements GeoInterface.LineStringTrait when geometry data is available (query uses out geom).

Fields

  • id::Int64: OSM way ID.
  • tags::Dict{String,String}: Key-value tags.
  • node_ids::Vector{Int64}: Ordered list of constituent node IDs.
  • geometry::Vector{LatLon}: Coordinates (populated when query uses out geom).

Examples

julia> w = Way(id=1, tags=Dict("highway" => "residential"), node_ids=[1,2,3],
               geometry=[LatLon(40.0,-74.0), LatLon(40.1,-74.1), LatLon(40.2,-74.2)])

Functions

bbox_string 

bbox_string(ext::Extent) -> String

Convert an Extents.Extent to an Overpass bbox string "(south,west,north,east)".

Examples

julia> bbox_string(Extent(X=(-79.1, -78.8), Y=(35.9, 36.1)))
"(35.9,-79.1,36.1,-78.8)"

nodes 

nodes(response::OverpassResponse) -> Vector{Node}

Return all Node elements from an OverpassResponse.

overpass_ql 

overpass_ql(s::QLStatement) -> String

Convert a QLStatement to its Overpass QL string representation.

Examples

julia> overpass_ql(OQL.node["amenity" => "cafe"])
"node[amenity=cafe]"

query 

query(ql::String; bbox=nothing, endpoint=DEFAULT_ENDPOINT) -> OverpassResponse

Execute an Overpass QL query and return the parsed response.

[out:json] is automatically prepended if not already present in the query.

If bbox is provided as an Extents.Extent, a global [bbox:south,west,north,east] setting is prepended to the query, applying the bounding box to all statements.

Examples

julia> using Extents

julia> r = query("node[amenity=cafe]; out geom;",
                  bbox=Extent(X=(-79.1, -78.8), Y=(35.9, 36.1)))

julia> r = query("node[amenity=cafe](35.9,-79.1,36.1,-78.8); out geom;")
query(s::QLStatement; out=:geom, bbox=nothing, endpoint=DEFAULT_ENDPOINT) -> OverpassResponse

Execute a QLStatement built with OQL.

The out keyword controls the output verbosity/geometry (default :geom). Accepts a Symbol (e.g. :geom, :body, :center, :skel) or a String for full control (e.g. "body qt 100").

Examples

julia> using Extents

julia> r = query(OQL.node["amenity" => "cafe"],
                 bbox=Extent(X=(-79.1, -78.8), Y=(35.9, 36.1)))

julia> r = query(OQL.way["building"], bbox=ext, out=:center)

relations 

relations(response::OverpassResponse) -> Vector{Relation}

Return all Relation elements from an OverpassResponse.

ways 

ways(response::OverpassResponse) -> Vector{Way}

Return all Way elements from an OverpassResponse.

Constants

DEFAULT_ENDPOINT 

String(s::AbstractString)

Create a new String from an existing AbstractString.

String(v::AbstractVector{UInt8})

Create a new String object using the data buffer from byte vector v. If v is a Vector{UInt8} it will be truncated to zero length and future modification of v cannot affect the contents of the resulting string. To avoid truncation of Vector{UInt8} data, use String(copy(v)); for other AbstractVector types, String(v) already makes a copy.

When possible, the memory of v will be used without copying when the String object is created. This is guaranteed to be the case for byte vectors returned by take! on a writable IOBuffer and by calls to read(io, nb). This allows zero-copy conversion of I/O data to strings. In other cases, Vector{UInt8} data may be copied, but v is truncated anyway to guarantee consistent behavior.

String <: AbstractString

The default string type in Julia, used by e.g. string literals.

Strings are immutable sequences of Chars. A String is stored internally as a contiguous byte array, and while they are interpreted as being UTF-8 encoded, they can be composed of any byte sequence. Use isvalid to validate that the underlying byte sequence is valid as UTF-8.

X509Name to string.

OQL 

OQL

Query builder for Overpass QL statements. Use dot syntax to select element types (node, way, relation, rel, nwr) and bracket syntax to add tag filters.

Examples

julia> OQL.node
node

julia> OQL.node["amenity" => "cafe"]
node[amenity=cafe]

julia> OQL.nwr["building"]
nwr[building]