Vulpine Maps for developers

1. Iframe: the easiest way

Move the map in the preview and the code below updates automatically.

Copy

/embed URL parameters

Controlling the map from your page (postMessage)

Copyconst frame = document.querySelector('iframe').contentWindow
frame.postMessage({ type: 'vmaps:flyTo', center: [30.3158, 59.9391], zoom: 15 }, '*')
frame.postMessage({ type: 'vmaps:setTheme', theme: 'dark' }, '*')
frame.postMessage({ type: 'vmaps:addMarker', lngLat: [30.3158, 59.9391], title: 'Hermitage' }, '*')
frame.postMessage({ type: 'vmaps:clearMarkers' }, '*')

// The map reports moves and clicks
window.addEventListener('message', (e) => {
    if (e.data?.type === 'vmaps:click') console.log('click', e.data.lngLat)
    if (e.data?.type === 'vmaps:moveend') console.log('center', e.data.center, 'zoom', e.data.zoom)
})

2. JS SDK

A thin wrapper around MapLibre GL JS that sets up styles, theme and 3D. It returns a regular maplibregl.Map.

Copy<div id="map" style="height: 480px"></div>
<script src="https://map.vulpine.email/sdk.js"></script>
<script>
  VulpineMaps.createMap('map', {
    theme: 'auto',            // 'light' | 'dark' | 'auto'
    lang: 'auto',             // 'en' | 'ru' | 'auto' (browser language)
    center: [37.6175, 55.752], // [longitude, latitude]
    zoom: 15,
    pitch: 55,
  }).then(function (map) {
    VulpineMaps.addMarker(map, [37.6175, 55.752], { popup: 'Red Square' })
    // map.setTheme('dark')
  })
</script>

As an ES module

Copy<script type="module">
  import { createMap, addMarker, maplibregl } from 'https://map.vulpine.email/sdk.mjs'

  const map = createMap('map', { theme: 'dark', center: [30.3158, 59.9391], zoom: 14 })
  addMarker(map, [30.3158, 59.9391], { popup: 'Hermitage' })
</script>

3. Your own MapLibre: styles

If you already use MapLibre (plain web, React, Vue), all you need is a style URL.

Copyimport maplibregl from 'maplibre-gl'
import 'maplibre-gl/dist/maplibre-gl.css'

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://map.vulpine.email/styles/light-en.json',
  center: [37.6175, 55.752],
  zoom: 14,
})
// Switch the theme without reloading
map.setStyle('https://map.vulpine.email/styles/dark-en.json', { diff: true })
// 3D terrain
map.setTerrain({ source: 'dem', exaggeration: 1.4 })

4. Mobile apps

The styles work with MapLibre Native: Android, iOS, Flutter, React Native. Not every Native version supports the globe and sky; the map still works without them.

Android (Kotlin)

Copy// build.gradle: implementation("org.maplibre.gl:android-sdk:<version>")
mapView.getMapAsync { map ->
    map.setStyle("https://map.vulpine.email/styles/light-en.json")
    map.cameraPosition = CameraPosition.Builder()
        .target(LatLng(55.752, 37.6175)).zoom(14.0).tilt(45.0).build()
}

iOS (Swift)

Copyimport MapLibre

let mapView = MLNMapView(frame: view.bounds,
    styleURL: URL(string: "https://map.vulpine.email/styles/dark-en.json"))
mapView.setCenter(CLLocationCoordinate2D(latitude: 55.752, longitude: 37.6175),
                  zoomLevel: 14, animated: false)
view.addSubview(mapView)

Flutter / React Native

Copy// Flutter (maplibre_gl)
MapLibreMap(styleString: 'https://map.vulpine.email/styles/light-en.json', initialCameraPosition: ...)

// React Native (@maplibre/maplibre-react-native)
<MapView mapStyle="https://map.vulpine.email/styles/light-en.json" />

In a WebView, the iframe page is the simplest option: https://map.vulpine.email/embed?lat=55.752&lon=37.6175&z=14&lang=en.

5. Direct data access

Tiles and styles are served with CORS *. Search is limited to 5 requests per second per IP. With lang=en, search returns English names where OpenStreetMap has them.

Data and licenses

Everything is built on open data and open-source software. Keep the attribution on the map when embedding it; the iframe and the SDK show it automatically.