DOCSEARCHbyAlgolia
Submit Docs

mapkick.js

repository·master·Indexed 19 days ago

https://github.com/ankane/mapkick.js

A lightweight JavaScript library for creating interactive maps using Mapbox or MapLibre engines. It supports point maps with markers, area maps using GeoJSON Polygons, live data updates via refresh intervals, and historical data animation through replay mode. Features include customizable tooltips, movement trails for tracked objects, and a pre-configured mapkick-bundle for Mapbox GL JS.

Tokens
3.2K
Snippets
15
Records
16
Agent score
63%

What's inside mapkick.js

  1. Implement Live Updates and Trails

    master

    You can create a live map by providing a URL and a refresh interval (in seconds). This will periodically fetch new data from the remote source.

    • refresh: number: Interval in seconds.
    • trail: boolean: If true, shows trails of previous positions.
    • trail: {len: number}: Sets the length of the trail.
    • id: Data points must include an id attribute to be correctly identified and tracked during updates.
    // Refresh every 10 seconds with trails
new Mapkick.Map("map", url, {trail: true, refresh: 10})

// Refresh every 10 seconds with a trail length of 10
new Mapkick.Map("map", url, {trail: {len: 10}, refresh: 10})

  2. Replay Data with time attribute

    master

    To animate data over time, enable replay: true. For this to work, each data point must have an id (to identify the object) and a time attribute (to indicate when the measurement occurred).

    Supported time formats:

    • Date object
    • Timestamp (or sequence number)
    • String (will be parsed)
    const data = [
  {id: "bus-1", lat: ..., lon: ..., time: t0},
  {id: "bus-1", lat: ..., lon: ..., time: t1}
];

new Mapkick.Map("map", data, {replay: true})

  3. Install Mapkick.js with MapLibre

    master

    To use MapLibre as the underlying mapping engine, include the MapLibre GL CSS and JS files, followed by mapkick.js. You can set global Mapkick options, such as the map style, via Mapkick.options.

    <link href="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
<script src="mapkick.js"></script>
<script>
  Mapkick.options = {style: "https://demotiles.maplibre.org/style.json"}
</script>

  4. Install Mapkick.js with Mapbox

    master

    To use Mapbox as the underlying mapping engine, you must first obtain a Mapbox access token. Include the Mapbox GL JS CSS and JS files, followed by mapkick.js, in the <head> of your HTML. You must set the mapboxgl.accessToken globally.

    <link href="https://api.mapbox.com/mapbox-gl-js/v3.25.0/mapbox-gl.css" rel="stylesheet" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.25.0/mapbox-gl.js"></script>
<script src="mapkick.js"></script>
<script>
  mapboxgl.accessToken = "YOUR-TOKEN"
</script>

  5. Enable Live Updates and Replay mode

    master

    Mapkick supports both real-time updates and historical replays.

    Live Updates (refresh): Set the refresh option to a number of seconds. Mapkick will periodically re-fetch the data from the provided URL or function and update the map.

    Replay Mode (replay): If replay: true is set, Mapkick will treat the data as a time series. It groups data by timestamp and automatically iterates through the frames, updating the map at each step.

    Example:

    // Live updates every 5 seconds
const map = new Mapkick.Map('map-id', 'https://api.example.com/data.json', {
  refresh: 5
});

// Replay historical data
const map = new Mapkick.Map('map-id', data, {
  replay: true
});

  6. Create an Area Map

    master

    An Area Map displays shapes using GeoJSON Polygon or MultiPolygon geometries. Each area can have a label, tooltip, and color.

    new Mapkick.AreaMap("map", [{
  geometry: {type: "Polygon", coordinates: [...]},
  label: "Hot Chicken Takeover",
  tooltip: "5 stars",
  color: "#0090ff"
}])

  8. Create a Point Map

    master

    A Point Map displays markers at specific coordinates. You can pass data as an array of objects, a URL returning JSON, or a callback function.

    For each data point, you can specify:

    • latitude or lat
    • longitude, lon, or lng
    • icon: Supports Maki icons
    • label: A text label
    • tooltip: Text shown on hover/click
    • color: Hex color code
    • id: Used for identifying objects in live updates or replay
    // Using an array
new Mapkick.Map("map", [{latitude: 37.7829, longitude: -122.4190, icon: "restaurant", label: "Hot Chicken Takeover", tooltip: "5 stars", color: "#f84d4d"}])

// Using a URL
new Mapkick.Map("map", "/restaurants")

// Using a callback
function fetchData(success, fail) {
  success([{latitude: 37.7829, longitude: -122.4190}])
}
new Mapkick.Map("map", fetchData)

  9. Configure Mapkick Map options

    master

    When initializing new Mapkick.Map(containerId, data, options), you can pass an options object to customize behavior:

    • markers: {color: "#hex"}: Set marker color.
    • tooltips: {hover: boolean}: Set to false to show tooltips on click instead of hover.
    • tooltips: {html: boolean}: Allow HTML in tooltips (requires manual sanitization).
    • style: "URL_OR_STRING": Set the map style.
    • zoom: number: Set initial zoom level.
    • controls: boolean: Show/hide map controls.
    • library: object: Pass options directly to the underlying Mapbox or MapLibre library (e.g., {hash: true}).
    new Mapkick.Map("map", data, {markers: {color: "#f84d4d"}, tooltips: {hover: false}, zoom: 15, controls: true})

  10. Configure Trails for moving objects

    master

    You can visualize the movement history of objects by enabling trail in the options. This requires your data to have a unique identifier (e.g., id) and a time property.

    Options:

    • trail: (Boolean) Enables trail rendering.
    • trail.len: (Number) The maximum number of points to keep in the trail history.

    Requirements:

    • Data must include an id field to group points into a single line.
    • Data must include a time field (timestamp or Date string) to support replay mode.
    const options = {
  trail: {
    len: 10
  }
};

const data = [
  { id: 'car-1', longitude: -122, latitude: 37, time: '2023-01-01T10:00:00Z' },
  { id: 'car-1', longitude: -122.1, latitude: 37.1, time: '2023-01-01T10:01:00Z' }
];

const map = new Mapkick.Map('map-id', data, options);

  11. Configure Tooltips and Hover behavior

    master

    Mapkick provides built-in tooltips. To enable them, include a tooltip property in your data objects.

    Configuration Options:

    • tooltips.hover: (Boolean) If true, tooltips appear on mouseenter. If false, tooltips appear on click.
    • tooltips.html: (Boolean) If true, the tooltip string is treated as HTML. If false, it is treated as plain text.

    Data Example:

    { longitude: -122, latitude: 37, tooltip: '<strong>Hello!</strong>' }
    const options = {
  tooltips: {
    hover: true,
    html: true
  }
};

const map = new Mapkick.Map('map-id', data, options);

  12. Initialize a Point Map with Mapkick.Map

    master

    Use Mapkick.Map to create a map that displays individual points (markers). You can provide data as an array of objects, a URL to a JSON endpoint, or a function that returns data.

    Markers can be customized using the color and icon properties in your data rows. If icon is set to "mapkick", it uses a default styled marker.

    Data Requirements for Points: Each data object must contain either longitude/latitude (or lng/lat, lon/lat) or a GeoJSON geometry object.

    // Using an array of data
const data = [
  { longitude: -122.41, latitude: 37.77, label: 'San Francisco', color: '#ff0000' },
  { longitude: -122.42, latitude: 37.78, label: 'Oakland', color: '#00ff00' }
];

const map = new Mapkick.Map('map-element-id', data, {
  zoom: 12,
  center: [-122.41, 37.77]
});