Map specspec v1

Map

A map is one JSON object, holding its own fields and its features.

squidmaps is in beta. Features, the map spec and these docs may change without notice, and things may occasionally break. Export a copy of any map that matters to you, and tell us when something isn't right: use Beta feedback, or email [email protected].

On this page

Fields
Types
Basemap
Extent
ZoomLimit
View
Legend
LegendRow
LegendSymbol
Panel
Feature
Geometry

Fields

Field	Type	Required	Description
`name`	`string` 1 to 100 characters	Yes	Shown at the top of the map's page and in link previews. Its page's address is made from it.
`description`	`string` at most 100000 characters	Yes	Markdown, shown under the name in the panel over the published map. HTML is escaped.
`basemap`	`Basemap or null`	Yes	The map under the features. Null shows none.
`extent`	`Extent`	Yes	Where the published map opens, and how far visitors can zoom and pan it.
`view`	`View or null`	Yes	Where the published map opens, unless its extent has initialBounds. Null until the map is first viewed in the editor; it then fits the features.
`legend`	`Legend or null`	Yes	A panel in the corner explaining the map's symbols. Null shows none.
`panel`	`Panel`	No, `{"featureList":false,"search":false}`	What the panel over the published map offers visitors besides its name and description.
`features`	`array of Feature`	Yes	The map's features, top of the list first. Points (and text) are drawn above lines, areas and images; within each, features earlier in the list are drawn on top.

Types

The objects inside a map. Where a type has several forms, one field (like type) says which.

Basemap

The map under the features, chosen by its type.

`type: "SQUIDMAPS"`

One of squidmaps' own basemaps, by name.

Field	Type	Required	Description
`type`	`"SQUIDMAPS"`	Yes
`style`	`"streets" \| "light" \| "gray" \| "dark"`	Yes	Which of squidmaps' basemaps.
`opacity`	`number` 0 to 1	No, `1`	From 0 (invisible) to 1 (opaque).
`labelVisibility`	`boolean`	No, `true`	Whether the basemap's own labels are shown.

`type: "CUSTOM"`

A custom basemap: one of squidmaps' basemaps with its colors and layers changed, saved to someone's account. Changes to it reach the maps that use it.

Field	Type	Required	Description
`type`	`"CUSTOM"`	Yes
`id`	`string` a UUID	Yes	The custom basemap's id.
`opacity`	`number` 0 to 1	No, `1`	From 0 (invisible) to 1 (opaque).
`labelVisibility`	`boolean`	No, `true`	Whether the basemap's own labels are shown.

`type: "STYLE"`

A MapLibre style, by its style JSON's URL.

Field	Type	Required	Description
`type`	`"STYLE"`	Yes
`name`	`string` 1 to 100 characters	Yes	What the editor calls the basemap.
`url`	`string` a URL	Yes	Where the basemap is served.
`opacity`	`number` 0 to 1	No, `1`	From 0 (invisible) to 1 (opaque).
`provider`	`string`	No	Who provides the style, for credit.

`type: "XYZ"`

Raster tiles, by a URL template with {z}, {x} and {y} in it.

Field	Type	Required	Description
`type`	`"XYZ"`	Yes
`name`	`string` 1 to 100 characters	Yes	What the editor calls the basemap.
`url`	`string` a URL	Yes	Where the basemap is served.
`opacity`	`number` 0 to 1	No, `1`	From 0 (invisible) to 1 (opaque).
`token`	`string`	No	An access token for the tiles, if they need one.
`tms`	`boolean`	No, `false`	Whether tile rows count up from the south (TMS).

`type: "TILEJSON"`

Raster tiles described by a TileJSON URL.

Field	Type	Required	Description
`type`	`"TILEJSON"`	Yes
`name`	`string` 1 to 100 characters	Yes	What the editor calls the basemap.
`url`	`string` a URL	Yes	Where the basemap is served.
`opacity`	`number` 0 to 1	No, `1`	From 0 (invisible) to 1 (opaque).
`token`	`string`	No	An access token for the tiles, if they need one.

Extent

Where the published map opens, and how far visitors can zoom and pan it.

Field	Type	Required	Description
`zoom`	`ZoomLimit`	Yes	The zoom levels the published map can be viewed at.
`bounds`	`Bounds or null`	No, `null`	An area visitors can't pan out of. Null lets them pan anywhere.
`initialBounds`	`Bounds or null`	No, `null`	An area the published map opens with fully in view. Null opens it at the saved view.

ZoomLimit

The zoom levels the published map can be viewed at.

`mode: "range"`

Visitors zoom between two levels.

Field	Type	Required	Description
`mode`	`"range"`	Yes
`min`	`number` 0 to 22	Yes	The farthest out. Below max.
`max`	`number` 0 to 22	Yes	The farthest in.

`mode: "fixed"`

Visitors see one zoom level, and can't zoom.

Field	Type	Required	Description
`mode`	`"fixed"`	Yes
`level`	`number` 0 to 22	Yes	The only zoom level.

View

Where the map is looking. The editor saves where it was left, and the published map opens there.

Field	Type	Required	Description
`center`	`[number, number]` items in turn: -180 to 180; -90 to 90	Yes	[longitude, latitude], in degrees.
`zoom`	`number` 0 to 22	Yes	A zoom level, as in MapLibre.

Legend

A panel in the bottom right corner of the published map, with a row for each symbol worth explaining.

Field	Type	Required	Description
`title`	`string` at most 100 characters	Yes	Shown above the rows. Empty for none.
`rows`	`array of LegendRow` 1 to 50 items	Yes	In display order.

LegendRow

A symbol and its label.

Field	Type	Required	Description
`label`	`string` at most 100 characters	Yes	Shown beside the symbol.
`symbol`	`LegendSymbol`	Yes	How a row's symbol is drawn: a copy of a feature's style, with the same fields as the feature properties for its kind. It stays as drawn when features change.

LegendSymbol

How a row's symbol is drawn: a copy of a feature's style, with the same fields as the feature properties for its kind. It stays as drawn when features change.

`type: "circle"`

A circle point's style.

Field	Type	Required	Description
`type`	`"circle"`	Yes
`fill`	`Color`	Yes	The circle's color.
`radius`	`number` 2 to 40	Yes	In pixels, not counting the stroke.
`stroke`	`Color`	Yes	The ring around the circle.
`strokeWidth`	`number` 0 to 10	Yes	The ring's width in pixels, outside the radius.
`icon`	`Icon or null`	Yes	A Font Awesome icon in the circle.
`iconColor`	`Color or null`	Yes	The icon's color. Without one, white or dark ink, whichever contrasts the fill.

`type: "emoji"`

An emoji point's style.

Field	Type	Required	Description
`type`	`"emoji"`	Yes
`emoji`	`Emoji`	Yes	One emoji, drawn as its Twemoji image.
`size`	`number` 12 to 64	Yes	The emoji's width and height in pixels.

`type: "marker"`

A marker pin's style.

Field	Type	Required	Description
`type`	`"marker"`	Yes
`shell`	`Color`	Yes	The pin's outer color.
`disc`	`Color`	Yes	The disc in the pin's head.
`icon`	`Icon or null`	Yes	A Font Awesome icon on the disc. Without one, it's empty.
`iconColor`	`Color or null`	Yes	The icon's color. Without one, white or dark ink, whichever contrasts the disc.

`type: "line"`

A line's style.

Field	Type	Required	Description
`type`	`"line"`	Yes
`color`	`Color`	Yes	The line's color.
`width`	`number` 0.5 to 20	Yes	In pixels.
`opacity`	`number` 0 to 1	Yes	From 0 (invisible) to 1 (opaque).
`dasharray`	`array of number` at most 8 items, each 0 to 100	Yes	Dash and gap lengths in turn, in line widths, like [4, 2]. Empty is solid.
`cap`	`"butt" \| "round" \| "square"`	Yes	How the line's ends are drawn.

`type: "area"`

An area's style.

Field	Type	Required	Description
`type`	`"area"`	Yes
`color`	`Color`	Yes	The line's color.
`width`	`number` 0.5 to 20	Yes	In pixels.
`opacity`	`number` 0 to 1	Yes	From 0 (invisible) to 1 (opaque).
`dasharray`	`array of number` at most 8 items, each 0 to 100	Yes	Dash and gap lengths in turn, in line widths, like [4, 2]. Empty is solid.
`cap`	`"butt" \| "round" \| "square"`	Yes	How the line's ends are drawn.
`fillColor`	`Color`	Yes	The area's inside color.
`fillOpacity`	`number` 0 to 1	Yes	From 0 (no fill) to 1 (opaque).

Panel

What the panel over the published map offers visitors besides its name and description.

Field	Type	Required	Description
`featureList`	`boolean`	No, `false`	A list of the map's features by folder, with a checkbox to hide each folder.
`search`	`boolean`	No, `false`	A box to find features by name or description.

Feature

A GeoJSON Feature with a required string id. Other members, like bbox, are kept.

Field	Type	Required	Description
`type`	`"Feature"`	Yes
`id`	`string` not empty	Yes	Unique within the map.
`geometry`	`Geometry or null`	Yes	Where the feature is. Null for a feature without one.
`properties`	`object`	Yes	Everything about the feature: its data, and how it looks and behaves, under "@"-prefixed keys. See Feature properties.

Geometry

A GeoJSON geometry (RFC 7946): Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon or GeometryCollection. Coordinates are [longitude, latitude] with at most six decimal places.

See the GeoJSON specification. Lines and areas are drawn as such; points as one of the point types.