Embedding

The globe runs inside any page as an iframe. One line shows the map of a chapter next to the passage on your page; a few messages keep the two in step.

#Quick start

<iframe
  src="https://historyglobe.app/embed/v1?ref=Acts.16&locale=en"
  title="Map of Acts 16"
  style="width: 100%; height: 480px; border: 0; border-radius: 12px"
  allow="fullscreen"
  loading="lazy"
></iframe>

The map opens on the places of Acts 16 in the year of its events, and the map fills the frame. At the top is the chapter: select it to list its places in the order the text names them, and select a place to open its card. At the bottom is the year: select it to open the time slider. A link opens the same view in the full globe in a new tab. Credits are shown on the map itself, as the data licences require. The frame works at widths down to a phone screen; a height of 480 px is enough.

#A chapter or a passage

ref takes an OSIS reference with English book abbreviations and English verse numbering:

The map moves to the year of the passage: the recorded year of its chapters (chapters of 56 books are dated), or else the year of the tour that covers it; a whole book takes the year of the tour with the most stops in it. A passage with neither keeps the map’s current year.

#Parameters

The easiest way to build a view is to set it up on the full globe and copy the URL: the same parameters work after /embed/v1.

#Messages

The globe and your page communicate through postMessage. Every message is an object with type and v: 1. The globe sends only what happens on the map and never anything that identifies the reader; it accepts messages only from the page that holds the frame.

From the globe

view holds year, locale and layers and, when set, place, tour, stop, ref and camera.

To the globe

#Example: the map follows your reader

const globe = document.querySelector("iframe").contentWindow;

// When your reader opens a chapter, show it on the map.
function showChapter(osis) {
  globe.postMessage({ type: "hg:set-view", v: 1, view: { ref: osis } }, "*");
}

// When a verse is clicked on the map, open it in your reader.
window.addEventListener("message", (e) => {
  if (e.source !== globe) return;
  if (e.data?.type === "hg:verse-clicked") openVerse(e.data.osis);
});

#Places in any text

One more line links the Bible places that your own text names (an article, a sermon, a reading plan) to the globe. Point at a name, or tap it on a phone, and a card shows what the place is, where it is today, how many verses name it and where it lies on the map; the card leads to the globe.

<script src="https://historyglobe.app/hg-places.js" data-scope="article" charset="utf-8" defer></script>

Only names that point to one place are linked. A name shared by two places (Antioch, of Syria and of Pisidia), by a place and a person (Judah), or by a place and an ordinary word stays plain text, and so does a name the Bible’s own verses mostly use for something else (“Kadesh” there is Kadesh-barnea, not the Kadesh of the database). A place’s name that is also a first name (Jordan, Sharon) is left alone next to another capitalised word: Jordan Smith is a person, not the river. Russian names are found in all their cases: «в Египте», «из Антиохии Писидийской». Links, code, form fields, buttons and headings are left alone.

The script has no dependencies and sets no cookies. It reads one file of names from the globe (about 25 KB in English and 35 KB in Russian over the network, plus 7 KB of script), without your page's address as referrer, and changes only the names it links. It works under a strict Content Security Policy that allows the globe's address in script-src and connect-src. For text your page adds later, call HistoryGlobePlaces.scan(element) once the text is rendered: the script splits text nodes, so in a React or Vue page run it on content the framework no longer re-renders.

#Stability

/embed/v1 is a contract: within v1, parameters and messages are only added, never changed or removed. A breaking change will ship as /embed/v2, and v1 will keep working.

Data as of 3 October 2026