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, SPARQL, & Esri.

popupTemplate

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

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

popupOnHover

Show the features inspection popup on hover rather than on click.

---
popupOnHover: true
---

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
  • esri
  • vector
  • raster
  • raw
  • osmxml
  • osmjson
  • osmWebsite
  • osmWiki
  • taginfo
  • dsv
  • javascript

See each provider for how it is auto-detected

overpass

An Overpass QL query. Results converted into a GeoJSON source with osm2geojson-ultra.

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 osm2geojson-ultra.

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 [osm2geojson-ultra.

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 SPARQL query to load data.

Note: requires you to specify a server.

Examples:

qlever

Make a SPARQL query against QLever to load data.

Use server to specify a backend slug. Default: osm-planet.

sophox

Make a SPARQL query against Sophox to load data.

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

esri

Load vector features from an Esri FeatureServer or MapServer.

Detected if

  • A URL ending in /FeatureServer/NUMBER or /MapServer/NUMBER

Simple usage

To load all features in a layer, specify the layer URL on the EsriServer as the query text

Advanced usage

To specify query parameters, specify them as the query text using YAML encoding. Specify the layer URL using server.

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.

dsv

,, \t, ;, or | delimited values. Can only represent points. Header must include columns matching the the regexes /(lat)(itude)?/ and /l(on|ng)(gitude)?. The delmiter is automatically detected.

postpass

An SQL query to be executed on a Postpass server. Server results are modified to have the same structure as overpass

Warning

Postpass is in very early stages of development, so Ultra may lag behind as new versions of the API are released. This provider defaults to the version 0.2 of the GeoFabrik Postpass API & Schema

javascript

A javascript module that exports a source function (can be async) that returns a MapLibre source object.

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
---

transform

This allows you to specify javascript to mutate the query result before it is added to the map style. Your code must export a function that accepts GeoJSON as a parameter and returns GeoJSON. To import libraries, use a CDN like skypack.dev or esm.sh.

For example, to buffer highways by 10 meters:

---
transform: |
    import { buffer } from "https://cdn.skypack.dev/@turf/buffer";

    export default function(data) {
        return buffer(data, 0.01);
    }
---
[bbox:{{bbox}}];
way[highway];
out geom;