Skip to main content

GeoJSON API

Introduction

The GeoJSON API is provided as a library to convert GeoJSON to and from MapML. The GeoJSON API can be added to any document as long as it is preceded by the mampl-viewer module, i.e.

<!doctype html>
<html lang="en">
<head>
<script type="module" src="mapml-viewer.js"></script>
<script src="lib/geojson.js"></script>
</head>
<body>
...
</body>
</html>

GeoJSON To MapML

FunctionReturnsDescription
geojson2mapml(<Object | String> json, <Object> options)A MapML <layer-> element.Convert a GeoJSON feature or feature collection string or object to MapML <layer-> containing one or more <map-feature> elements.
tip

Check out this application using the geojson2mapml API!

Parameters

ParameterDescription
<String | Object> jsonA GeoJSON string or object.
<Object> optionsA set of key/value pairs that customize the output MapML layer. All options are optional and described below.

Options

<Object> A set of key/value pairs that customize the output MapML layer. All options are optional and detailed below.

OptionTypeDefaultDescription
label<String>json.name, json.title or "Layer"Sets the output layer's label.
projection<String>OSMTILESets the output layer's projection. Defined values include: OSMTILE, CBMTILE, WGS84, and APSTILE.
caption<String | Function>Uses the label valueA function that accepts the feature JSON and returns a string, OR a string that is the name of a property to be mapped to the featurecaption. If a matching property is not found, the string provided will be used as the feature caption value. See basic options usage for an example.
properties<Function | String | HTMLElement>Properties will be mapped to an HTML table.Specifies how the properties are mapped. <Function> - A function that accepts one argument - the GeoJSON feature object - and which must return an HTMLElement that becomes the single child element of the <properties> element. <String> - A string that will be parsed and used as the single child element of the <properties> element for all features. <HTMLElement> - an element that will be used as the single child element of <properties> element for all features. See basic options usage for an example.
geometryFunction<Function>MapML geometry will mirror the GeoJSON geometry value<Function> A function to modify the generated descendants of <map-geometry> which can add classes, hyperlinks and span's to the instance. Plain <map-geometry> element will be created by default. The function accepts two arguments: The generated child element of <map-geometry> and the feature json object to return a modified child element of the <map-geometry> element. See basic options usage for an example.

Examples

Basic options usage

Showcasing how use each option.

geojson2mapml label option
geojson2mapml(json, {label: "Downtown Ottawa"});

Options string

An example showcasing how strings can be used to set label, projection, caption and properties options.

let json = {
"name": "Default Name",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-75.6916809,45.4186964]
},
"properties": {"desc": "This is a Point"}
};

// GeoJSON To MapML
let output = geojson2mapml(json, {label: "Example 1", projection: "CBMTILE", caption: "desc", properties: "<h3>This is a property heading</h3>"});
Click to view the output HTMLElement
<layer- label="Example 1" checked="">
<map-meta name="projection" content="CBMTILE"></map-meta>
<map-meta name="cs" content="gcrs"></map-meta>
<map-feature>
<map-featurecaption>This is a Point</map-featurecaption>
<map-geometry>
<map-point>
<map-coordinates>-75.6916809 45.4186964</map-coordinates>
</map-point>
</map-geometry>
<map-properties>
<h3>This is a property heading</h3>
</map-properties>
</map-feature>
</layer->

Options function

An example showcasing how functions can be used to set caption and properties options.

let json = {
"name": "Default Name",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-75.6916809,45.4186964]
},
"properties": {"desc": "This is a Point"}
};

// function to set caption
let cap = function c(j) {
let str = "This point is located at: (" + j.geometry.coordinates[0] + ", " + j.geometry.coordinates[1] + ").";
return str;
}

// function to set properties
let prop = function f(p) {
let parser = new DOMParser();
return parser.parseFromString("<h1>" + p.properties.desc + "'s property</h1>", "text/html").body.firstChild;
}

// GeoJSON To MapML
let output = geojson2mapml(json, {label: "Example 2", caption: cap, properties: prop});
Click to view the output HTMLElement
<layer- label="Example 2" checked="">
<map-meta name="projection" content="OSMTILE"></map-meta>
<map-meta name="cs" content="gcrs"></map-meta>
<map-feature>
<map-featurecaption>This point is located at: (-75.6916809, 45.4186964).</map-featurecaption>
<map-geometry>
<map-point>
<map-coordinates>-75.6916809 45.4186964</map-coordinates>
</map-point>
</map-geometry>
<map-properties>
<h1>This is a Point's property</h1>
</map-properties>
</map-feature>
</layer->

Default options

An example showcasing default output when no options are provided.

let json = {
"title": "Point Geometry",
"bbox": [-75.916809, 45.886964, -75.516809, 45.26964],
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-75.6916809, 45.4186964]
},
"properties": {
"prop0": "This is a Point"
}
}]
};

// GeoJSON To MapML
let output = geojson2mapml(json);
Click to view the output HTMLElement
<layer- label="Point Geometry" checked="">
<map-meta name="extent" content="top-left-longitude=-75.916809, top-left-latitude=45.886964, bottom-right-longitude=-75.516809,bottom-right-latitude=45.26964"></map-meta>
<map-meta name="projection" content="OSMTILE"></map-meta>
<map-meta name="cs" content="gcrs"></map-meta>
<map-feature>
<map-featurecaption>Point Geometry</map-featurecaption>
<map-geometry>
<map-point>
<map-coordinates>-75.6916809 45.4186964</map-coordinates>
</map-point>
</map-geometry>
<map-properties>
<table>
<thead>
<tr>
<th role="columnheader" scope="col">Property name</th>
<th role="columnheader" scope="col">Property value</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">prop0</th>
<td itemprop="prop0">This is a Point</td>
</tr>
</tbody>
</table>
</map-properties>
</map-feature>
</layer->

MapML To GeoJSON

FunctionReturnsDescription
mapml2geojson(<HTMLLayerElement> element, <Object> options)A JavaScript (GeoJSON) feature collection objectThis function transforms the <feature> element children of a <layer-> element to a GeoJSON FeatureCollection object. You supply options to control the transformation. This function must be used inside a windows.onload event.
caution

mapml2geojson must be called inside a windows.onload event to work properly. i.e.

window.onload = (event) => {
mapml2geojson(json);
};

Parameters

ParameterDescription
<HTMLLayerElement> elementA <layer-> element.
<Object> optionsYou supply parameters via an options object with predefined option names.

Options

<Object> A set of key/value pairs that customize the output GeoJSON object. All are optional and detailed below.

OptionTypeDefaultDescription
propertyFunction<Function>n/aA function you supply that maps the features' <map-properties> element to a GeoJSON "properties" member, since only you know the markup design in your <map-properties> value. If you don't supply this option, a default function will attempt to reverse a <table> child of the <map-properties> element, as if that table was generated by the default properties option function from geojson2mapml.
transform<Boolean>trueTransform <map-coordinates> values to gcrs (longitude,latitude) values, if they are not already so. GeoJSON recommends using WGS 84 longitude,latitude coordinates, so this is the default behaviour.
Notes

mapml2geojson, by default, will transform coordinates to gcrs before serialization, if necessary. Note that all geographic CRS are not equivalent, and the interpretation of such coordinates is not guaranteed to conform to WGS 84 / GPS coordinates, and therefore may not conform to the GeoJSON recommendation, which requires longitude,latitude coordinates that are encoded as WGS 84. The projection engine used to implement this conversion is not capable of transforming coordinates from one ellipsoid to another, and so the resulting JSON SHOULD (somehow, tbd) be tagged with the datum in use by the projection of the layer.


Examples

Default options

An example showcasing default GeoJSON output when no options are provided.

<layer- label="Point Geometry" checked="">
<map-meta name="extent" content="top-left-longitude=-75.916809, top-left-latitude=45.886964, bottom-right-longitude=-75.516809,bottom-right-latitude=45.26964"></map-meta>
<map-meta name="projection" content="OSMTILE"></map-meta>
<map-meta name="cs" content="gcrs"></map-meta>
<map-feature>
<map-featurecaption>Point Geometry</map-featurecaption>
<map-geometry>
<map-point>
<map-coordinates>-75.6916809 45.4186964</map-coordinates>
</map-point>
</map-geometry>
<map-properties>
<table>
<thead>
<tr>
<th role="columnheader" scope="col">Property name</th>
<th role="columnheader" scope="col">Property value</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">prop0</th>
<td itemprop="prop0">This is a Point</td>
</tr>
</tbody>
</table>
</map-properties>
</map-feature>
</layer->
<script>
window.onload = (event) => {
let output = mapml2geojson(document.querySelector('layer-'))
};
</script>
Click to view the output GeoJSON
{
"title": "Point Geometry",
"bbox": [-75.916809, 45.886964, -75.516809, 45.26964],
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-75.6916809, 45.4186964]
},
"properties": {
"prop0": "This is a Point"
}
}]
}