Skip to main content
RahroWhere to?

Rahro for developers

Embed the map, directions and place pages on your site with a few lines of code.

Open the Embed BuilderManage API keys

Quick start

Add the script once per page, then an element with data-rahro-map wherever you want a map. widget.js is under 5 KB gzipped, only creates iframes and loads nothing until the element scrolls into view.

<script src="https://rahromap.ir/sdk/v1/widget.js" async></script>

<div data-rahro-map data-lat="35.6997" data-lon="51.3380" data-zoom="15"
     data-label="..." data-lang="en" style="height:360px"></div>

<div data-rahro-place="x3f8k2m1q9" data-lang="en" style="height:320px"></div>

iframe embeds

Three ready pages: a map with a pin, a route between two points and a place card. ?lang= picks the language, so one snippet works on every page of your site.

<iframe src="https://rahromap.ir/embed/map?ll=35.6997,51.338&z=15&lang=en"
        width="100%" height="360" style="border:0" loading="lazy"></iframe>
<!-- https://rahromap.ir/embed/directions?from=lat,lon&to=lat,lon&to_name=...&lang=en -->
<!-- https://rahromap.ir/embed/place/{id}?lang=en -->

@rahro/maps SDK

Build embed URLs, mount iframes and sign static map URLs. Importable without npm from /sdk/v1/maps.mjs; web components: <rahro-map>, <rahro-directions> and <rahro-place-card>.

<div id="map" style="height:360px"></div>
<script type="module">
  import { mountMap } from "https://rahromap.ir/sdk/v1/maps.mjs";
  mountMap(document.getElementById("map"), { base: "https://rahromap.ir", lat: 35.6997, lon: 51.338, zoom: 15, lang: "en" });
</script>

<!-- web components (after widget.js) -->
<rahro-map lat="35.6997" lon="51.338" zoom="15" lang="en"></rahro-map>
<rahro-directions to-lat="35.7" to-lon="51.4" to-name="..." lang="en"></rahro-directions>
<rahro-place-card place="x3f8k2m1q9" lang="en"></rahro-place-card>

API keys

Create a publishable key (pk_) for browser embeds and a secret key (sk_) for servers and for signing static maps. The full key is shown only once.

Origins can be spoofed; quotas and rate limits are what really protect a publishable key. Keep secret keys on your server.

Static map images

GET /v1/static/map with key, skid (the id of one of your secret keys) and sig. The signature is HMAC-SHA256, base64url, over the sorted query string without sig; the signing secret is the SHA-256 hex digest of your secret key, so the secret itself never appears in a URL. Sign on your server only.

For now the response is a simple SVG (grid, pin, label and coordinates), not real map tiles; real rendering with tileserver-gl comes later without changing the URL or the signature.

// Node 18+ — sign on your server, never in the browser.
import { createHash, createHmac } from "node:crypto";

const secret = createHash("sha256").update(process.env.RAHRO_SECRET_KEY).digest("hex");
const query = new URLSearchParams({
  ll: "35.6997,51.338", z: "15", w: "600", h: "400",
  key: "pk_...",               // your publishable (or secret) key
  skid: "<secret key id>",     // id of the secret key, shown on the keys page
}).toString();
const canonical = query.split("&").sort().join("&");
const sig = createHmac("sha256", secret).update(canonical).digest("base64url");
const url = `https://rahromap.ir/v1/static/map?${query}&sig=${sig}`;

oEmbed

Place pages carry oEmbed discovery links: tools like WordPress embed the place card when you paste the page URL. Endpoint: GET /oembed?url=

GET https://rahromap.ir/oembed?url=https%3A%2F%2Frahromap.ir%2Fplace%2Fx3f8k2m1q9&maxwidth=600