This section documents API usage specific to this template, so for an introduction we suggest you refer to the generic API documentation instead.

Template data

There are three different formats in which you can supply data to this template. The most convenient for you to use likely depends on the source of your data, as described below.

1. Array of arrays, and a bindings object

You can supply arrays of arrays to opts.data, which might look like:

{
    data: {
        markers: [
            [ "MarkersColumn1Value1", "MarkersColumn2Value1",
            [ "MarkersColumn1Value2", "MarkersColumn2Value2",
            [ "MarkersColumn1Value3", "MarkersColumn2Value3",
            ...
        ],
        icons: [
            [ "IconsColumn1Value1", "IconsColumn2Value1",
            [ "IconsColumn1Value2", "IconsColumn2Value2",
            [ "IconsColumn1Value3", "IconsColumn2Value3",
            ...
        ]
    }
}

where each array of arrays represents the rows in a data sheet.

To tell the API how the values from each column should be associated with the keys that the template is expecting, you must also supply an object attached to opts.bindings. (The meanings of the keys in the bindings object are documented below.) The minimal bindings you can supply for this template are as shown in this example:

{
    template: "_599",
    version: "_4",
    bindings: {
        markers: {
            lat: 0, // index of a column in your data
            long: 1, // index of a column in your data
        },
        icons: {
            category_name: 0, // index of a column in your data
            icon: 1, // index of a column in your data
        }
    },
    data: {
        markers: [
            [ "MarkersColumn1Value1", "MarkersColumn2Value1",
            [ "MarkersColumn1Value2", "MarkersColumn2Value2",
            [ "MarkersColumn1Value3", "MarkersColumn2Value3",
            ...
        ],
        icons: [
            [ "IconsColumn1Value1", "IconsColumn2Value1",
            [ "IconsColumn1Value2", "IconsColumn2Value2",
            [ "IconsColumn1Value3", "IconsColumn2Value3",
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "_599",
    version: "_4",
    bindings: {
        markers: {
            lat: 0, // index of a column in your data
            long: 1, // index of a column in your data
            category: 2, // index of a column in your data
            name: 3, // index of a column in your data
            description: 4, // index of a column in your data
            image: 5, // index of a column in your data
            link: 6, // index of a column in your data
            metadata: [7, 8, ...], // index(es) of column(s) in your data
        },
        icons: {
            category_name: 0, // index of a column in your data
            icon: 1, // index of a column in your data
            background_color: 2, // index of a column in your data
            background_padding: 3, // index of a column in your data
            size: 4, // index of a column in your data
            color: 5, // index of a column in your data
            opacity: 6, // index of a column in your data
            stroke_width: 7, // index of a column in your data
            stroke: 8, // index of a column in your data
        }
    },
    data: {
        markers: [
            [ "MarkersColumn1Value1", "MarkersColumn2Value1",
            [ "MarkersColumn1Value2", "MarkersColumn2Value2",
            [ "MarkersColumn1Value3", "MarkersColumn2Value3",
            ...
        ],
        icons: [
            [ "IconsColumn1Value1", "IconsColumn2Value1",
            [ "IconsColumn1Value2", "IconsColumn2Value2",
            [ "IconsColumn1Value3", "IconsColumn2Value3",
            ...
        ]
    }
}

2. Array of objects with arbitrary keys, and a bindings object

This format is most likely useful when you have data from an external source, such as CSV data loaded from d3-dsv. You should supply this attached to the opts.data, which might look like:

{
        markers: [
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            ...
        ],
        icons: [
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            ...
        ]
    }

... but with the keys being the column headers from your source data instead. You must also supply an object attached to opts.bindings. The minimal bindings you can supply for this template are as shown in this example:

{
    template: "_599",
    version: "_4",
    bindings: {
        markers: {
            lat: "MarkersHeader1",
            long: "MarkersHeader2",
        },
        icons: {
            category_name: "IconsHeader1",
            icon: "IconsHeader2",
        }
    },
    data: {
        markers: [
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            ...
        ],
        icons: [
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "_599",
    version: "_4",
    bindings: {
        markers: {
            lat: "MarkersHeader1",
            long: "MarkersHeader2",
            category: "MarkersHeader3",
            name: "MarkersHeader4",
            description: "MarkersHeader5",
            image: "MarkersHeader6",
            link: "MarkersHeader7",
            metadata: ["MarkersHeader8", "MarkersHeader9", ...],
        },
        icons: {
            category_name: "IconsHeader1",
            icon: "IconsHeader2",
            background_color: "IconsHeader3",
            background_padding: "IconsHeader4",
            size: "IconsHeader5",
            color: "IconsHeader6",
            opacity: "IconsHeader7",
            stroke_width: "IconsHeader8",
            stroke: "IconsHeader9",
        }
    },
    data: {
        markers: [
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            { "MarkersHeader1": ..., "MarkersHeader2": ..., ... },
            ...
        ],
        icons: [
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            { "IconsHeader1": ..., "IconsHeader2": ..., ... },
            ...
        ]
    }
}

(As before, the keys containing "Header" would be replaced by column names from your data source.)

3. Array of objects with template-defined keys

There is an alternative format you can use, which is likely to be easier to use if your data is not from a spreadsheet source. With this alternative format you supply your data to the template as an array of objects, attached to opts.data, where the keys must be those used by the template, as documented below. In this case there is no need to supply a bindings object, since the key names are already those expected by the template. The required properties in the data object are as follows (scroll down for a description of what each property is):

{
    template: "_599",
    version: "_4",
    data: {
    markers: [
        {
            lat: ...,
            long: ...,
            metadata: [...]
        },
        ...
    ],
    icons: [
        {
            category_name: ...,
            icon: ...
        },
        ...
    ]
},
    ...
}

And the full list of all possible properties is as follows:

{
    template: "_599",
    version: "_4",
    data: {
    markers: [
        {
            lat: ...,
            long: ...,
            category: ...,
            name: ...,
            description: ...,
            image: ...,
            link: ...,
            metadata: [...]
        },
        ...
    ],
    icons: [
        {
            category_name: ...,
            icon: ...,
            background_color: ...,
            background_padding: ...,
            size: ...,
            color: ...,
            opacity: ...,
            stroke_width: ...,
            stroke: ...
        },
        ...
    ]
},
    ...
}

Meanings of the template data keys:

• markers.lat: lat
• markers.long: long
• markers.category: Category of place. Values should match the 'Category' column in the Icon styles sheet.
• markers.name: Name of place, shown in popup
• markers.description: Description of place, shown in popup
• markers.image: Image, shown in popup
• markers.link: Link to open when user clicks marker
• markers.metadata: Extra information you want to add to the popup
• icons.category_name: Values should match the 'Category' column in the Places sheet, and should not be repeated.
• icons.icon: The image for the marker. Can be a Font Awesome icon name, e.g. 'circle' or 'chevron-right'; a D3 SVG icon name, e.g. 'd3-star' or 'd3-cross'; an image URL; or an emoji.
• icons.background_color: Background colour, e.g. '#fff' or 'red'
• icons.background_padding: Background padding in pixels, e.g. 2
• icons.size: Pixel size of the icon
• icons.color: Colour of the icon - this can be a hex value like '#fff', or a web-safe value like 'red'
• icons.opacity: Opacity of the icon between 0 and 1, e.g. 0.5
• icons.stroke_width: Border width in pixels, e.g. 24
• icons.stroke: Border colour, e.g. '#fff' or 'red'

Template settings

Options for opts.state.

Design

tint_fill color

Map tint.

tint_opacity number

Map tint opacity.

tiles_url string

Styles.

tiles_opacity number

Opacity.

custom_tiles_url string

Custom tile url. Specify a url to a custom tileset, with {} as variables, eg. https://stamen-tiles-{s}.a.ssl.fastly.net/terrain/{z}/{x}/{y}.png

custom_tiles_url_retina string

Custom tile url for retina (optional). Specify a url to a custom retina tileset that will be loaded on retina devices, with {} as variables, eg. https://stamen-tiles-{s}.a.ssl.fastly.net/terrain/{z}/{x}/{y}@2x.png

attribution string

Tiles attribution. Add the appropriate attribution for your map tiles

Map starting point

map_start_center_lat number

Latitude.

map_start_center_long number

Longitude.

map_zoom number

Zoom.

Popups

popup text

Text in popup. Use {{column_name}} to add a value from your data in the popup. Note the column must be selected for this to work.

Legend

show_legend boolean

Show legend.

legend_title string

Title.

legend_background color

Background.

legend_opacity number

Opacity.

legend_textcolor color

Text color.

legend_size number

Icon size.

legend_showborder boolean

Show border.

Default icon styles

default_icon_icon string

Icon content. This will be used when nothing is specified in the data. Can be a letter, emoji or Font Awesome icon name

default_icon_size number

Size.

default_icon_fill color

Colour. Ignored for emoji

default_icon_background color

Background colour.

default_icon_opacity number

Opacity.

default_icon_background_padding number

Padding.

default_icon_stroke_width number

Border width.

default_icon_stroke color

Border colour.

default_icon_pointer_offset boolean

Add pointer to circle.

default_icon_category string

Category label.

enable_icon_random_offset boolean

Spread out icons with same coordinates. Useful, for example, to spread out markers positioned at the center of a postcode or zip code

icon_random_offset number

Offset in pixels.

Map limits

disable_zoom boolean

Disable zoom & panning.

map_min_lat number

Min lat.

map_max_lat number

Max lat.

map_min_long number

Min lng.

map_max_long number

Max lng.

map_min_zoom number

Min zoom level.

map_max_zoom number

Min zoom level.

Animations

pan_duration number

Animation duration. Speed of panning animation in story mode (in seconds)

Custom CSS

css text

Custom CSS styles. Custom CSS definitions to override the defaults