Developer guide

MapForHuman is an internal map-platform pilot. It delivers CFHM vector drawing commands from an owned, versioned open-data archive. The SDK applies presentation locally. Public developer accounts, a public npm package and production service guarantees are not available yet.

Choose an integration

Access model

Pilot access is operator-assisted. A CFH application needs an owner, an environment, source permissions and usage allowances before it can call the service. Its backend authenticates users and calls MapForHuman with a registered service identity. Browser requests stay on the application's origin through a narrow gateway. Never embed a service secret in JavaScript, a mobile binary or a game client.

The current service-token registration is MOTS-specific; another app requires the planned registry generalization and onboarding checks. Opening the studio requires an approved pilot account. The public product page grants neither API access nor a user account.

Current game SDK example

This uses the actual 0.3.0 API. Obtain the internal package from the CFH maintainer and bundle its game-map.mjs entry as a local module; it is not an npm-registry installation. Configure an authenticated same-origin /maps gateway that forwards the approved catalog and scene routes. The example intentionally does not call the protected service from the public website.

import {
  GameMapClient, gameAddress, paintGameCell,
  gameAttribution, attributionHTML,
} from './sdk/game-map.mjs';

const client = new GameMapClient({ apiBase: '/maps' });
await client.connect();

const address = gameAddress(-122.339, 47.613);
const cell = await client.cell(
  address.zoom, address.tileX, address.tileY,
);

const canvas = document.querySelector('canvas');
canvas.width = 512;
canvas.height = 512;
paintGameCell(canvas, cell);

// Use the SDK's sanitized attribution renderer with SDK-generated entries.
document.querySelector('#attribution').innerHTML =
  attributionHTML(gameAttribution(cell));

Provide a visible canvas and #attribution element in the host page. Handle rejected requests with a retry action and readable error. A source cell can be reused for several display cells; higher display zoom does not add source detail. The 0.3.0 package has bounded in-memory reuse and request coalescing. Its cancellation and lifecycle surface is less complete than the planned general client.

Current web control

The web control is available in the repository at src/sdk/map-control/control.ts; it is not yet a standalone public package. A host supplies a sized container, an approved theme and source IDs. Its methods include setTheme, setSources, setHeatmap, addGeofence, track and destroy. A React host should construct it once for a mounted element and dispose it on unmount.

The planned framework separates a reusable client from a view, so multiple maps can share requests and memory limits. Planned names such as @cfh/map-core and @cfh/map-web describe the design and should not be used as current install commands.

Data, themes and attribution

Approved sources are selected by identity, not arbitrary provider URLs. The current worldwide basemap combines OpenStreetMap with Natural Earth through Protomaps. Source selection cannot remove a contributor from data already combined in that basemap. The service enforces contributor permissions before delivery.

Keep required attribution visible and linked for the data actually rendered. Theme changes must not conceal it. Fonts, icons and marketplace artwork need their own rights review. No enterprise-licensed map data is admitted. The public preview uses the already-owned baseline and retains linked OpenStreetMap attribution. See OpenStreetMap copyright and license information and Protomaps basemap documentation.

Themes change presentation locally. A future theme marketplace will use validated declarative themes; purchasing a theme will not transfer rights to the map dataset. Marketplace checkout and creator payouts are not live.

Cache and offline behavior

Cache only responses explicitly permitted for public geometry reuse. Use versioned URLs and bounded storage. Community reports, account preferences, contribution history and review decisions remain private and are not shared map-cache entries.

Current offline behavior is limited to previously available content; startup and private workflows still need connectivity. Downloadable region packs, offline startup guarantees and storage management are planned. Show stale/offline state clearly and hide expired safety reports. A cached map is not a current emergency information service.

Errors and diagnostics

Do not report the studio's existing community round-trip counter as basemap performance. Future SDK diagnostics will split cache lookup, download, decode and viewport readiness. Include SDK/protocol revision, device/browser, request ID and cache tier in support evidence. Exclude credentials, account data and precise user locations unless the user explicitly opts into a protected diagnostic workflow.

Before shipping an integration

• Confirm app identity, allowed sources, daily limits and a disable switch with the pilot owner.
• Test an authorized user, a denied user, quota exhaustion and expired credentials.
• Keep attribution visible through themes, screenshots, fullscreen and fallback rendering.
• Exercise rapid pan/zoom, repeat visits, slow/offline network and cache failure.
• Validate heatmap and geofence semantics with known fixtures; reporting density is not a safety score.
• Use app-owned rules for gameplay and product decisions. Map geometry alone is not authoritative navigation, emergency advice or legal eligibility.
• Pin the SDK version and retain a tested rollback. Native and console integrations need independent platform validation.

Product direction

The next release work is a shared request/cache core, a packaged web control, clearer diagnostics and service delivery improvements. Then come validated native adapters, offline packs and theme commerce. Platform support, prices and service levels will be published when those gates are met; the current pilot should not be treated as a production SLA.