CommutemapDocs

Integration & serving model

This repo is structured to support a pilot portal first, then scale to multiple portals with one backend and usage-based billing (events).

Partner iframe (recommended for v1)

Partners embed a single URL. We validate both the partner origin and a short-lived signed token before rendering the interactive map.

<iframe src="https://commutemap.io/embed/map?token=YOUR_SIGNED_TOKEN&listingId=123" width="100%" height="520" loading="lazy" referrerpolicy="strict-origin-when-cross-origin" style="border:0;" ></iframe>

Until your DNS is configured, you can temporarily use your Vercel preview host (https://<project>.vercel.app) as the embed host. Once DNS is live, switch embeds to commutemap.io.

How the token works

For security, the iframe URL must include token. The token encodes:

  • partnerId (who is embedding)
  • originHost (which domain may embed)
  • listingId (optional; helps prevent token reuse across listings)
  • exp short TTL (e.g. 5–30 minutes)

Serving model (fast + secure)

  • Marketing pages: normal Next.js pages, cached on Vercel Edge/CDN.
  • Embed surface: /embed/* with strict CSP + allowlisted partners + token.
  • Future: move commute computation to a dedicated API (edge or regional) and cache results per listing.

Is there a better idea than iframe?

Yes, eventually: a small JS SDK or Web Component (e.g. <commute-map>) is faster and gives deeper integration. But iframe is the easiest/lowest-risk partner rollout for v1; we can add the SDK later without breaking the iframe contract.

What I still need from you

Your tt file only includes the long-term business notes. To implement the real interactive map, please add the missing product spec: commute modes (car, transit, bike), target POIs (work address?), supported cities, KPIs/events, and which map provider you want (Mapbox/Google/OSM).

Partner data: what’s “industry standard”?

Portals typically provide listing data either via XML feeds (e.g. OpenImmo / Immo XML variants) or via a REST API. The exact schema differs per portal, so we define a minimal, stable “Commutemap listing contract” and build adapters per partner.

Minimal fields we need (v1): - id (string) - title (string) - address OR (recommended) lat/lng - city/region (optional) - price, livingArea, rooms (optional for UI) Strong recommendation: - partner sends lat/lng (geocoding on their side), because geocoding adds cost + latency.

For the prototype, we use sample listings around Wien + Niederösterreich. In production, partners will pass at least id + lat/lngto the embed.

For public transport isochrones we use Navitia via a server-side proxy endpoint: /api/isochrones/transit. This keeps your Navitia API key secret (never exposed to the browser).

Vercel env vars: - NAVITIA_API_KEY=... (required) - NAVITIA_COVERAGE=... (required: must include Vienna) - NAVITIA_BASE_URL=https://api.navitia.io/v1 (optional)

You can get a Navitia API key by creating an account at navitia.io and generating a token in their dashboard.