README.md

Overpass.jl

Julia wrapper for the OpenStreetMap Overpass API.

• Query Overpass API
• Helper functions
• Meaningful error messages
• Few dependencies

Inspired by the python packages overpy and overpass.

Install

julia> ]
pkg> add Overpass

Usage

Query overpass

Get requested elements from OpenStreetMap through Overpass API. The result is provided as string and has to be parsed depending on the format you specified in your query.

💡 Tipp: Use Overpass Turbo to build your queries and use the export feature to save them as .overpassql either as standalone or raw

using Overpass
Overpass.query("waterfountains.overpassql", bbox=(48.22, 16.36, 48.22, 16.36))
# "{\n  \"version\": 0.6,\n  \"generator\": \"Overpass API…"

Overpass.query can handle .overpassql and .ql files. For short queries it is also possible to inline it directly:

# Standard example of https://overpass-turbo.eu/
Overpass.query("[out:json];node[amenity=drinking_water]({{bbox}});out;", bbox=(48.22, 16.36, 48.22, 16.36))
# "{\n  \"version\": 0.6,\n  \"generator\": \"Overpass API…"

Argument	Description	Datatype
bbox	Coordinates to replace {{bbox}} shortcut	NTuple{4, Number}
center	Coordinates to replace {{center}} shortcut	NTuple{2, Number}

Result parsing

To keep the package small and flexible, the response is not parsed but returned as a string. Depending on the use case, the string can then be parsed, saved, etc.

Change Overpass endpoint

Sets the endpoint for the Overpass API.

Overpass.set_endpoint("https://overpass.private.coffee/api/")

Default endpoint is https://overpass-api.de/api/. See list of endpoints in OSM Wiki.

⚠️ Endpoint URL must have a trailing slash

Endpoint status

Receive current Status of Overpass API endpoint.

Overpass.status()

The returned Status struct provides the following fields:

• connection_id::String
• server_time::DateTime
• endpoint::Union{Nothing, String}
• rate_limit::Int
• avalible_slots::Union{Nothing, Int}

Overpass turbo URL

Get URL to open your query in Overpass Turbo.

Overpass Turbo is a web based graphical user interface for Overpass. Its very useful to build and debug your queries with Overpass Turbo.

The query can be provided directly or as a path to a .ql/.overpassql file.

Overpass.turbo_url("drinking_water.overpassql")
# "https://overpass-turbo.eu/?Q=%5Bout%3Ajson%5D%3Bnode%5Bamenity%3Ddrinking_water…"

Overpass Turbo shortcuts

These Overpass Turbo shortcuts are supported:

Shortcut	Status
{{bbox}}	supported
{{center}}	supported
{{date:string}}	supported
{{geocodeId:name}}	not yet supported
{{geocodeArea:name}}	not yet supported
{{geocodeBbox:name}}	not yet supported
{{geocodeCoords:name}}	not yet supported

The {{date}} shortcut

The {{date}} shortcut can represent:

1. The current UTC date and time.
2. A relative date calculated using offsets (e.g., 7 days ago, 1 month ago).

When using the {{date}} shortcut in your query, it is replaced with a date string in ISO 8601 format, ensuring compatibility with Overpass API queries.

Query Placeholder	Meaning	Replacement Example
{{date}}	Current date and time in UTC	2024-12-02T12:00:00Z
{{date:7 days}}	7 days ago from now in UTC	2024-11-25T12:00:00Z
{{date:-1 month}}	1 month into the future in UTC	2025-01-02T12:00:00Z
{{date:2 years}}	2 years ago from now in UTC	2022-12-02T12:00:00Z

** ⚠️ Warning: The implementation of Overpass Turbo calculates the offset for the {{date}} shortcut in seconds, ignoring leap years and leap seconds. In contrast, Overpass.jl provides a calculation the actual calendar structure when replacing the placeholder. **

See: Overpass Turbo Available Shortcuts for more details.

Contributors

Gregor Wehrle 🤔 📓 💻

Martin Scheidt 🤔 📓 💻

See also

Package
LightOSM.jl	Download, save and analyze networks via Overpass API
OpenStreetMapX.jl	Analyze OSM roads from .osm or .pbf files
OSMToolset.jl	Read and analyze OSM XML files