PanoramicData.Maps.Abstractions 0.2.9

PanoramicData.Maps

Open-source static map image rendering with markers, icons, lines and polygon overlays, plus a thin geocoding passthrough — for a self-hosted Photon + Protomaps / MapLibre map stack. A drop-in, self-hostable alternative to the Google Static Maps + Geocoding APIs.

Renders natively with SkiaSharp — no headless browser, no Node.js.

See docs/DEPLOYMENT.md for Kubernetes setup, dependencies and dataset options (planet vs alternatives), and CONTRIBUTING.md to contribute.

Maps are rendered by driving MapLibre GL JS in headless Chromium (via Playwright) and screenshotting the result, so any MapLibre style and overlay works exactly as it would in a browser.

Status: early scaffold (0.x). The HTTP API and rendering work; the container image and CI are being finalised.

Components

HTTP API

center/marker coordinates in the query API are lat,lon (Google-compatible). Set location= (a place name) instead of center= to have it geocoded. format=png (default) or jpeg.

Markers

Markers are drawn as Google-style teardrop pins, anchored at the tip, so a coordinate is where the pin points. size: accepts Google's four names, each a visibly different pin:

scale: sets an arbitrary relative size instead, and the image's own scale=2 doubles everything for @2x output. Two deliberate differences from Google: a label: is drawn at every size (Google drops it on its two smallest), because a small marker in a report still needs its identity; and a label of more than one character is shrunk to fit the pin head rather than spilling over it.

Marker icons

markers=icon:<name>|<lat>,<lng> draws a named icon from the map style's own sprite sheet instead of a pin - cafe, train_station, museum, peak, bar and about fifty others. GET /v1/icons lists what the configured style offers, because the names are not guessable.

• An icon is centred on its coordinate (these are point glyphs, not pins), and size:/scale: size it just as they size a pin.
• A label: alongside an icon is drawn underneath it with a halo, rather than over the glyph.
• An unknown name falls back to a pin and logs a warning, so a typo does not silently change the map.
• Remote icon URLs are rejected with a 400. Fetching caller-supplied URLs from a public service is an SSRF exposure, not a convenience; the sprite sheet comes from the same host as the tiles and nothing else is ever contacted.

The sprite URL is normally discovered from the style JSON's sprite field. Set Maps__SpriteUrl when that URL is not reachable from wherever the renderer runs (a common case when the style advertises a public hostname and the renderer resolves an internal one).

Example POST body

{
  "location": "London",
  "zoom": 12, "width": 800, "height": 600,
  "markers": [{ "location": { "longitude": -0.1278, "latitude": 51.5074 }, "color": "#dc2626", "label": "HQ" }],
  "paths":   [{ "points": [{ "longitude": -0.16, "latitude": 51.507 }, { "longitude": -0.07, "latitude": 51.508 }], "color": "#7c3aed" }],
  "polygons":[{ "points": [{ "longitude": -0.16, "latitude": 51.49 }, { "longitude": -0.16, "latitude": 51.52 }, { "longitude": -0.10, "latitude": 51.52 }, { "longitude": -0.10, "latitude": 51.49 }] }]
}

Building URLs from .NET

StaticMapUrlBuilder writes the query the service parses, so callers do not assemble descriptor strings by hand. It lives in PanoramicData.Maps.Abstractions, which has no renderer dependencies - safe to reference from a UI project or a report macro.

var url = StaticMapUrlBuilder.Build("https://maps.panoramicdata.com", new MapRequest
{
    Center  = new GeoPoint(-0.1278, 51.5074),   // longitude, latitude
    Zoom    = 12,
    Width   = 800,
    Height  = 600,
    Markers = [new MarkerSpec { Location = new GeoPoint(-0.1278, 51.5074), Color = "red", Label = "A" }]
});

The builder and the service's parser are tested against each other by round-trip - build a URL, parse it back, compare - so the two halves of the grammar cannot drift apart.

It never writes an API key. Authentication is the caller's business, and a key in a URL is visible to anything that can see the URL: send it as the X-Api-Key header, or put a proxy in front.

Blazor

@using PanoramicData.Maps
@using PanoramicData.Maps.Blazor

<StaticMap BaseUrl="/api/maps"
           Location="Maidenhead, Berkshire"
           Zoom="13"
           Width="640" Height="360"
           class="rounded" />

Renders a plain <img> - no JavaScript, so none of the interop-lifetime and disposal hazards that come with a scripted map. Markers, Paths, Polygons and Regions take the same models the URL builder does; unmatched attributes (class, style, data-*) are applied to the image; loading defaults to lazy; and Alt defaults to a description of the map rather than nothing. If there is nothing to draw yet, or BaseUrl is not set, it renders nothing rather than a broken image - and never throws, because an exception during render takes the Blazor circuit with it.

There is no ApiKey parameter, deliberately. A key placed in an image URL is published to every browser that loads the page - including under Blazor Server, where it lands in the rendered HTML. Point BaseUrl at a same-origin endpoint that adds the key server-side:

// In the host application. The key stays on the server; the browser only ever sees /api/maps.
app.MapGet("/api/maps/staticmap", async (HttpRequest request, IHttpClientFactory factory, CancellationToken ct) =>
{
    var client = factory.CreateClient();
    client.DefaultRequestHeaders.Add("X-Api-Key", mapsApiKey);
    var upstream = await client.GetAsync($"https://maps.panoramicdata.com/staticmap{request.QueryString}", ct);
    return Results.Stream(await upstream.Content.ReadAsStreamAsync(ct), upstream.Content.Headers.ContentType?.ToString());
});

Configuration (Maps section / env vars)

API-key enforcement is off by default so the open-source image works out of the box; the canonical hosted service enables it to meter and monetise access.

Licence

MIT (code). Map data is © OpenStreetMap contributors (ODbL) and must be attributed in rendered output; Protomaps basemap styles are CC0. MapLibre GL JS is BSD-3-Clause.