Skip to content

YAML front-matter config

The real power of Ultra lies in it's easy configuration of MapLibre with the a query's YAML front-matter.

style

Customize the MapLibre style. See Styling for more information.

Example:

---
style: https://example.com/style.json
---

server

Use a different Overpass or SPARQL server.

Example:

---
server:  https://overpass.private.coffee/api/
---

Only applies to Overpass queries.

popupTemplate

Customize the interactive popup with a LiquidJS template. Or set it to false to disable the interactive popup.

---
popupTemplate: "{{type}} {{id}} - {{tags.name}}"
---

type

Specify the type of source in the query.

Default: auto

auto

Automatically detects and chooses the right query provider out of the following:

  • overpass
  • geojson
  • kml
  • gpx
  • tcx
  • vector
  • raster
  • raw
  • osmxml
  • osmjson
  • osmWebsite
  • osmWiki
  • taginfo

See each provider for how it is auto-detected

overpass

An Overpass QL query. Results converted into a GeoJSON source with osmtogeojson.

Detected if:

  • Parses as XML and the top level tag is osm-script
  • Matches one of the regexes defined here

osmWebsite

Parses a URL to an node/way/relation on osm.org and fetches that element using an Overpass query using out geom;

Detected if:

  • A URL on osm.org starting with node/way/relation

osmWiki

Perform an Overpass query using nwr and out geom; for an OSM wiki URL starting with Tag: or Key:

Detected if:

  • A URL to the OSM wiki starting with Tag: or Key:

taginfo

Perform an Overpass query using nwr and out geom; for an taginfo URL for keys or tags.

Detected if:

  • A URL starting with http://taginfo.openstreetmap.org or http://taginfo.geofabrik.de and with a path ending in /keys/:key or /tags/:key=:value.

osmxml

An OSM XML document or a URL to one. Converted into a GeoJSON source with osmtogeojson.

Detected if:

  • Parses as XML and the top level tag is osm
  • Parses as a URL and the path matches that of an node/:id, way/:id/full, or relation/:id/full OSM API route

osmjson

An OSM JSON document or a URL to one. Converted into a GeoJSON source with osmtogeojson.

Detected if:

  • Parses as JSON and contains a version key containing the value 0.6 at the top level.
  • Parses as a URL and the path matches that of an node/:id, way/:id/full, or relation/:id/full OSM API route

sparql

Make a GeoSPARQL query to load data.

Note: requrires you to specify a server.

Examples:

ohsome

An ohsome API filter.

Automatically adds the current bbox with the bboxes param and properties=tags,metadata using the extracts endpoint.

For more complex ohsome API usage, make a request using the geojson provider with a custom BBOX format.

geojson

A JSON-encoded GeoJSON object or a URL to a GeoJSON file.

Detected if:

  • Parses as JSON and contains a type with a valid GeoJSON type.

kml

A KML file or URL to a KML file.

Detected if

  • Parses as XML and contains a top level kml tag

gpx

A GPX file or URL to a GPX file.

Detected if

  • Parses as XML and contains a top level gpx tag

tcx

A TCX file or URL to a TCX file.

Detected if

  • Parses as XML and contains a top level tcx tag

raw

A full MapLibre Source as JSON or YAML.

Detected if

  • Parses as JSON or YAML and contains a valid MapLibre Source type.

raster

A line delimited list of tile URLs for a raster source or a TileJSON url

Detected if

  • tile URLs ending in .png, .jpg, .jpeg, or .webp.
  • A JSON document or URL to a JSON document containing a tilejson key and a format key equal to png, jpg, or webp.

vector

A line delimited list of tile URLs for a vector source or a TileJSON url

Detected if

  • A JSON document or URL to a JSON document containing a tilejson key and a format key equal to pbf.

options

When an Ultra query is run in "interactive map" mode, you can specify the MapOptions that are passed to the MapLibre constructor.

For example, you can use this to fit to bounds rather than relying on the z/x/y URL parameters, making for a more consistent experience across screen sizes. EG:

---
options:
  bounds: [-77.64656066894544,37.577235791111384,-76.92558288574232,38.13563674858875]
---

controls

When an Ultra query is run in "interactive map" mode, you can specify controls to be added to the map with the controls key in the YAML-front matter. The key should contain a list of objects. Each object must specify a type key containing the name of a control present in MapLibre. It can optionally contain an options key who's contents are passed to the control's constructor and a position key that is passed to map.addControl.

For example, to add a NavigationControl to your map:

---
controls:
  - type: NavigationControl
    options:
      visualizePitch: true
    position: bottom-left
---

querySources

Specify which sources can be queried by mouse-click

---
querySources: [ultra] # this is the default
---