GIS Tools - Bookmarkable Map States

What Are Bookmarkable Map States?

A bookmarkable map state is a serialized snapshot of an interactive web map encoded into a URL or share string. When you click "share" on a slippy map and get back a link that opens the same view another person sees, that link is a bookmarkable map state. The minimum it captures is the map center (longitude, latitude) and the zoom level. A more complete implementation also captures bearing, pitch, the active basemap, the list of visible vector layers, their styling, and any active filters.

Bookmarkable states matter because spatial work is inherently a conversation about "look at this place." Without a way to share an exact view, you end up writing instructions like "zoom into Brooklyn, then pan north until you see the cemetery, then turn on the parcels layer." That is brittle, slow, and frequently wrong. A bookmark URL replaces all of it with a single link.

The gis.tools bookmarkable map state tool encodes the current viewer state into a URL fragment using a compact, URL-safe scheme. Because the encoding lives in the fragment (the part after the #), it never travels to a server, so even private workflows that load sensitive local files can produce shareable links without leaking the underlying data. The bookmark only describes the view; the recipient still needs the same source files to see the same features.

This is a different concept from a saved tile cache, a persistent project file, or a server-side map document. It is the lightest-weight possible mechanism for collaboration and is the foundation of most modern web map sharing.

How Map State Encoding Works

Fragment-based serialization

The bookmark tool serializes the current state into a JSON-like structure, then base64-encodes it (or uses a more compact field-by-field scheme) and appends it to the URL after the # character. Because browsers do not send the fragment to the server, the encoded state is purely client-side. Reloading the URL parses the fragment, decodes the state, and replays it onto the map.

What gets encoded

A typical bookmark captures:

Center coordinates in WGS84 longitude/latitude
Zoom level as a floating-point number (often 0-22)
Bearing in degrees (0 = north up)
Pitch in degrees (0 = straight down, 60 = oblique)
Active basemap identifier
Layer visibility as a list of toggled layer IDs
Layer styles for any layers the user restyled
Filters currently applied via the Attribute Filter Builder or Spatial Filter

Round-tripping

When the URL is loaded, the parser walks through each field in the encoded state and applies it back to the map. The order matters: basemap loads first, then vector layers register, then visibility toggles, then styles, then filters, then finally the camera animates to the saved center/zoom/bearing/pitch.

Key Parameters and Options

Precision

Coordinates are typically rounded to 5-6 decimal places (about 1 meter at the equator) to keep URLs short. Zoom is rounded to 2 decimal places.

Compression

For large filter expressions or many active layers, the encoder may apply a compression pass (LZ-string is common in JavaScript) before base64 encoding to keep URLs under the 2,000-character practical limit imposed by most browsers and email clients.

Whitelist vs full state

You can configure whether to encode every possible field or only a subset. A minimal bookmark with just center+zoom+basemap is usually sufficient for ad-hoc sharing; a full bookmark including styles is better for archival.

Practical Applications

Newsroom collaboration

A data journalist exploring a leaked dataset wants to send their editor the exact view that proves a hotspot of suspicious activity. Instead of taking a screenshot, they share the bookmark URL. The editor opens it, sees the same hotspot, and can pan around to verify the surrounding context. The reproducibility of a URL beats the static nature of a screenshot every time, especially when the editor wants to explore neighboring areas.

Academic supplementary material

A published paper about urban heat islands references a specific block group in Phoenix. The authors include a bookmark URL in the supplementary materials so reviewers and readers can replicate the exact view used in Figure 3. Combined with the source GeoJSON deposited in a data repository, the bookmark gives readers an exact path back to the original visualization.

Field crew dispatch

A conservation biologist identifies a likely nesting site and sends the bookmark to the field crew via SMS. The crew opens the link on their phone, sees the same map, and can navigate to the location without re-typing coordinates. This eliminates a class of transcription errors that creep in whenever coordinates are dictated over a radio.

Stakeholder review

A city planning office reviewing a development proposal sends council members a bookmark that loads the parcel boundary, the proposed footprint, the surrounding land use, and a satellite basemap. Council members can interact with the same view from their own laptops without installing GIS software.

Bug reports

When a user finds a rendering glitch in a web map, they can send a bookmark URL along with the bug report so the developer reproduces the exact state without guesswork. Bug reports for map applications are notoriously hard to reproduce because the bug usually depends on a precise camera position; a bookmark eliminates that ambiguity.

Teaching

GIS instructors share bookmark URLs with their classes pointing at specific examples — a sliver polygon, an antimeridian crossing, a CRS mismatch — and students load the link to see the issue first-hand. Lecture notes become live documents where each illustration is a clickable link rather than a static figure.

Step-by-Step Workflow

Open the GeoJSON, KML, Shapefile & GIS File Viewer and load your data files.
Pan, zoom, and configure the view: choose a basemap, toggle layers, adjust styling.
Click the bookmark/share button to generate a URL.
Copy the URL to your clipboard.
Send it via email, Slack, or paste it into a document.
The recipient opens the link in their browser, and the map replays your saved state.

Common Pitfalls and Gotchas

Bookmark does not include the data. A bookmark only encodes the view, not the GeoJSON or shapefile underneath. The recipient must load the same source file independently.
URL length limits. Browsers and email clients usually break URLs longer than 2,000 characters. Heavy bookmarks with custom styles may overflow.
Floating-point drift. Truncating coordinates to 5 decimal places introduces ~1m of error. For survey-grade workflows, use higher precision or pair the bookmark with a centerpoint marker.
Antimeridian wrap. A bookmark centered exactly on longitude 180 may render slightly differently in different libraries due to wrap handling.
Stale layer IDs. If the underlying file's layer ID changes between sessions, the bookmark's visibility toggles will silently fail.
Cross-version compatibility. A bookmark encoded by viewer version 1.x may not parse cleanly in version 2.x if the schema changed.
Mobile keyboards mangling URLs. Long bookmarks pasted into mobile apps sometimes get word-wrapped or have characters auto-corrected.

Tips for Best Results

Use bookmarks for ad-hoc sharing; use saved project files for archival.
Include the source data filename in the bookmark URL or alongside it so recipients know what to load.
Shorten very long bookmark URLs through a URL shortener — but be aware shorteners log clicks.
Test your bookmark in an incognito window before sending to verify it round-trips.
For accessibility, pair bookmark URLs with a one-line description of what the recipient will see.
Keep bookmarks under 1,500 characters to leave headroom for email clients that re-encode URLs.
When sharing across teams with different default basemaps, explicitly include the basemap ID in the bookmark.

Comparison with Other Map Sharing Approaches

Google Maps, Mapbox Studio, and ArcGIS Online all support shareable URLs but lock you into their hosted platforms. The gis.tools bookmark tool is library- and host-agnostic — it encodes state for any client-side viewer that can interpret the same fragment scheme. Compared to QGIS project files (.qgs), bookmarks are vastly lighter but cannot describe the data sources themselves. Compared to web map services like WMS or WMTS, bookmarks describe the view of a map, not the map itself.

The trade-off is that bookmarks assume the recipient has the same data. For workflows where you want to bundle data with the view, export to a Print/Export Composer PDF or share the underlying GeoJSON file directly.

Performance Considerations

Bookmark encoding and decoding are O(1) operations and add no measurable overhead to map navigation. The constraint is URL length: browsers vary in what they accept, but 2,000 characters is a safe upper bound. For very complex states, consider storing the full state in browser localStorage and using the bookmark URL only as a key reference.

Data Privacy and Browser-Based Processing

Bookmarks generated by gis.tools live entirely in the URL fragment, which is never sent to any server. Your data, your filter expressions, and your styling decisions stay on your machine. The recipient of a bookmark URL also processes everything locally; no telemetry is collected when they open the link. This is especially important for journalists, lawyers, and researchers who need to discuss spatial findings without exposing the underlying data to third parties.

Related GIS Concepts

URL fragments. The portion of a URL after the # character, which browsers do not send to servers. Used for in-page anchors and client-side state encoding.

Permalinks. Permanent links that always point to the same resource. Bookmarks are a kind of permalink for map views.

Project files. Persistent, file-based descriptions of a GIS workspace including data sources, layer order, and styling. QGIS .qgs and ArcGIS .mxd files are the canonical examples.

Web map services (WMS). OGC standard for serving pre-rendered map images from a server. Different abstraction layer than bookmarks.

Frequently Asked Questions

Does the bookmark contain my data?

No. The bookmark only encodes the view (center, zoom, layer visibility, styles). The recipient must load the same source files independently.

How long can a bookmark URL be?

In practice, keep them under 2,000 characters. Most browsers and email clients work reliably below that threshold.

Can I bookmark filtered views?

Yes. If your viewer supports the Attribute Filter Builder or Spatial Filter, the active filter expression is captured in the bookmark.

Is the bookmark URL private?

The URL fragment never leaves your browser unless you explicitly share it. Once shared, anyone with the link can replay your saved view (assuming they have the same source data).

What if the data file changes?

The bookmark will still load the saved view, but if features were added or removed, the visible content will reflect the new file rather than the original.

Current View

Bookmarks (0)

Tips