@trailstash/ultra/docs/yaml.md

A web based tool for making MapLibre GL maps with data from sources such as Overpass, GeoJSON, GPX, KML, TCX, etc

# 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](https://jekyllrb.com/docs/front-matter/).

## `style`

Customize the MapLibre style. See [Styling](./style.md) 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/
---
```

<small>Only applies to Overpass, SPARQL, & Esri.</small>

## `popupTemplate`

Customize the interactive popup with a [LiquidJS](https://liquidjs.com/) 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`

See each provider for how it is auto-detected

### `overpass`

An [Overpass QL](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL) query. Results
converted into a [GeoJSON source](https://maplibre.org/maplibre-style-spec/sources/#geojson) with
[`osm2geojson-ultra`](https://github.com/dschep/osm2geojson-ultra).

Detected if:

- Parses as XML and the top level tag is `osm-script`
- Matches one of the regexes defined [here](https://gitlab.com/trailstash/ultra/-/blob/main/lib/queryProviders/overpass.js#L11-34)

### `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](https://wiki.openstreetmap.org/wiki/OSM_XML) document or a URL to one. Converted into
a [GeoJSON source](https://maplibre.org/maplibre-style-spec/sources/#geojson) with
[`osm2geojson-ultra`](https://github.com/dschep/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](https://wiki.openstreetmap.org/wiki/OSM_JSON) document or a URL to one. Converted
into a [GeoJSON source](https://maplibre.org/maplibre-style-spec/sources/#geojson) with
[[`osm2geojson-ultra`](https://github.com/dschep/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](https://www.w3.org/TR/sparql11-query/) query to load data. 

**Note:** requires you to specify a [server](#server).

Examples:

 * [Qlever](./Examples/qlever.md)
 * [Wikidata Query Service](./Examples/wikidata-sparql.md)
 * [Sophox](./Examples/sophox.md)

### `qlever`

Make a [SPARQL](https://www.w3.org/TR/sparql11-query/) query against QLever to load data. 

Use [server](#server) to specify a backend slug. Default: `osm-planet`.

### `sophox`

Make a [SPARQL](https://www.w3.org/TR/sparql11-query/) query against Sophox to load data. 

### `ohsome`

An [ohsome API](https://api.ohsome.org/) [filter](https://docs.ohsome.org/ohsome-api/v1/filter.html).

Automatically adds the current bbox with the [`bboxes` param](https://docs.ohsome.org/ohsome-api/v1/boundaries.html#bboxes) and `properties=tags,metadata` using the [extracts endpoint](https://docs.ohsome.org/ohsome-api/v1/endpoints.html#elements-extraction).

For more complex ohsome API usage, make a request using the [`geojson`](#geojson) provider with [a
custom BBOX format](./Examples/alt-bbox-format.md).

### `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`](#server).

### `raw`

A full [MapLibre Source](https://maplibre.org/maplibre-style-spec/sources/) 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](https://maplibre.org/maplibre-style-spec/sources/#tiles_1) for
a [raster source](https://maplibre.org/maplibre-style-spec/sources/#raster) or a [TileJSON
url](https://maplibre.org/maplibre-style-spec/sources/#url_1)

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](https://maplibre.org/maplibre-style-spec/sources/#tiles_2) for
a [vector source](https://maplibre.org/maplibre-style-spec/sources/#vector) or a [TileJSON
url](https://maplibre.org/maplibre-style-spec/sources/#url_2)

Detected if

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

### `postpass`

An SQL query to be executed on a [Postpass](https://github.com/woodpeck/postpass) server. Server
results are modified to have the same structure as [overpass](#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](https://github.com/woodpeck/postpass-ops) &
    [Schema](https://github.com/woodpeck/postpass-ops/blob/main/SCHEMA.md)

## `options`

When an Ultra query is run in "interactive map" mode, you can specify the
[`MapOptions`](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/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`](https://maplibre.org/maplibre-gl-js/docs/API/classes/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](https://skypack.dev) or [esm.sh](https://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;
```