# EO-Map Embed Guide (machine-readable)

This is the public contract for putting EO-Map on a third-party site as an iframe.
Feature overview: https://eo-map.com/embed-map/
Human guide (live builder): https://eo-map.com/embed-guide
Native (non-iframe) JS embed: https://eo-map.com/embed-native.txt
Pinned loader: https://eo-map.com/embed/v1.js
Types: https://eo-map.com/embed/v1.d.ts
Human showcase (iframe or native copy): https://eo-map.com/embed-guide
If you are an LLM, implement from this file. Do not scrape the React app.

Product: EO-Map, a free 3D map of EVE Online (New Eden).
Canonical site: https://eo-map.com/

## Canonical iframe

https://eo-map.com/embed?...

Equivalent: https://eo-map.com/?embed=1&...
Trailing slashes /embed/ and /embed-guide/ are served.
Solar-system embed: https://eo-map.com/solar-system/{id}?embed=1

URL parameters are INITIAL state. After load, update the same iframe with
postMessage. Do not change iframe.src for each new system.

## Minimal example

<iframe
  src="https://eo-map.com/embed?system=30000142&zoom=50"
  width="100%"
  height="450"
  frameborder="0"
  allowfullscreen
></iframe>

Jita is 30000142. Useful single-system zoom is 50. 3D and security-status
colouring are the defaults. Open on EO-Map appears in the frame and must stay.

## URL parameters

system
  Numeric CCP SDE id. Selects and centres that system.
  Example: system=30000142 (Jita). Names are q=, not system=.

systems
  Comma-separated numeric ids for accent highlight rings.
  Nearby systems read better than a map-wide set. Add fit=1 so the camera
  frames exactly that set; an explicit zoom is unreliable with systems=.
  Example: systems=30000142,30000144,30000143&fit=1
  (Jita, Perimeter, Niyabainen)

q
  Exact system name. Resolved then stripped from the URL.
  Example: q=Jita

layout
  2d or 3d. Default 3d. Embed-only; does not write the visitor's full-app
  2D/3D preference.
  Example: layout=2d

coloring
  security or off. Default security, unless cinematic color= is set.
  Distinct from color=. Do not overload color= for security status.
  Example: coloring=off

zoom
  Camera distance 0.25-300. Useful single-system frame: 50.
  If omitted, the view is wide (165). Do not use old 1000/2500 values.
  Example: zoom=50

angle
  Vertical angle in degrees, -90 to 90. Omit for top-down north-up.
  angle=0 is edge-on, not the default.

orbit
  1 to auto-orbit. Any mouse interaction stops it.

color
  Cinematic star tint: blue, green, purple, red, yellow, white, random,
  realistic. NOT security colouring. If set and coloring= is omitted,
  security colouring turns off. The named tints only render with orbit=1
  (cinematic mode). realistic paints stars by spectral class in any embed
  and implies details=1: the stellar dataset (~21 MB, cached) loads after
  the map, so stars start white and colour in. coloring=off (without
  color=) gives plain white stars.

angle with orbit
  The orbit keeps the elevation it starts from, so angle=20..35 with
  orbit=1 gives a low, 3D-reading orbit instead of a top-down spin.

performance
  1 disables bloom and other heavy visuals. Use on CMS pages or if more
  than one embed might appear.

details
  1 loads the extra solar-system dataset (~21 MB) on a galaxy embed.
  Security colouring does not need it; color=realistic implies it.
  Solar-system embeds always load it.

fit
  1 frames highlighted/linked systems. An explicit zoom wins if both are set.

links
  systemA-systemB:color, comma-separated. Max 50.
  Colors: green, red, blue, yellow, purple, white, orange, cyan.

label_<id> and labelMode
  Optional overlay names. labelMode=hover|always|off.

routing, from, to, jumpRange
  Gate-only route. All four are required to enter routing embed mode.
  jumpRange (alias range) must parse greater than 0. EO routing does not
  use that number as a jump distance; send jumpRange=1.
  from/to: names or numeric ids.
  Example: routing=1&from=Jita&to=Amarr&jumpRange=1
  routeLabels=1 draws names along the route (default off).
  showRoutingCard, routingCardMinimized, routingCardWidth control the card.

mode
  On /solar-system/{id}?embed=1 only: cinematic or icon (aliases solarMode,
  solarVisualMode, icons).

embed
  embed=1 is required on / and /solar-system/{id}. Redundant on /embed.
  panel= is ignored in embed.

Reserved for later (not implemented): layers=, postMessage types
ef-map-layers, ef-map-layout, ef-map-coloring.

## postMessage

Origin-open, public, read-only. No SSO, no secrets, no writes to the host.
Wire names stay ef-map-* on purpose (not eo-map-*). Unknown types are
ignored, so renaming a verb silently does nothing. Target the iframe
contentWindow. Target origin may be https://eo-map.com or '*'.

Keep ONE persistent iframe. Wait for ef-map-ready, then navigate/highlight.
Do not recreate the iframe per update. Several simultaneous WebGL embeds
can fail (about six concurrent frames produced errors in testing).

Outbound, once the universe map is loaded:

{ "type": "ef-map-ready", "systemsLoaded": true }

Outbound after each successful focus (including the initial URL system):

{ "type": "ef-map-selected", "systemId": 30000142, "name": "Jita" }

Inbound:

ef-map-navigate  { systemId: number, zoom?: number }
  Fly to that system. Optional zoom 0.25-300.

ef-map-highlight { systems: number[] }
  Replace accent rings. Works with no initial systems= on the URL.
  Numeric strings are accepted.

ef-map-zoom      { zoom: number }
  Change distance immediately, without changing the selected system.

ef-map-angle     { angle: number }
  Vertical angle in degrees, clamped -90..90.

ef-map-enter-system { systemId: number }
  Enter solar-system view without reloading. Loads ~21 MB if uncached.

ef-map-show-universe
  Return from solar-system view to the galaxy.

ef-map-flash { systemId: number, kind?: string, color?: string, value?: number }
  Flash the map's event burst at a system. The HOST supplies the id from
  its own feed (killboard, intel bot, ESI poller); the embed never opens a
  live socket and has no kill-source integration of its own.
  kind: kill (red, default) | capital (kill bloom plus the capital shock-ring) |
  positive (green) | accent (theme orange) | neutral (white).
  Unknown kinds fall back to kill.
  color: optional '#rrggbb' override of the kind palette.
  value: optional ISK loss on kind=capital (alias isk). Finite, non-negative,
  capped at 1e12. Drives the Battle Replay capital shock-ring size. Omitted
  value uses the default ring; supplied ISK scales it, never past 420px.
  Numeric string ids are accepted. Unknown ids are ignored.
  Example: { type: 'ef-map-flash', systemId: 30000142, kind: 'kill' }
  Example: { type: 'ef-map-flash', systemId: 30000142, kind: 'capital' }
  Example: { type: 'ef-map-flash', systemId: 30000142, kind: 'capital', value: 4790000000 }

Unknown types are ignored so later verbs can be added.

## Complete host example

<iframe
  id="eo-map"
  src="https://eo-map.com/embed?system=30000142&zoom=50"
  width="100%"
  height="450"
  frameborder="0"
></iframe>
<select id="hubs" disabled>
  <option value="30000142">Jita</option>
  <option value="30002187">Amarr</option>
  <option value="30002510">Rens</option>
</select>
<p id="status">Loading…</p>
<script>
const iframe = document.getElementById('eo-map');
const hubs = document.getElementById('hubs');
const status = document.getElementById('status');
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://eo-map.com') return;
  if (event.data?.type === 'ef-map-ready') {
    hubs.disabled = false;
    status.textContent = 'Ready';
  }
  if (event.data?.type === 'ef-map-selected') {
    status.textContent = 'Focused: ' + event.data.name + ' (' + event.data.systemId + ')';
  }
});
hubs.addEventListener('change', () => {
  const systemId = Number(hubs.value);
  const w = iframe.contentWindow;
  w.postMessage({ type: 'ef-map-navigate', systemId, zoom: 50 }, 'https://eo-map.com');
  w.postMessage({ type: 'ef-map-highlight', systems: [systemId] }, 'https://eo-map.com');
});
</script>

## Kill feed example (host-driven flashes)

Your page already has system ids from its own kill feed. Flash them on one
persistent iframe. Nothing in the embed connects to a kill source.

<iframe id="eo-map" src="https://eo-map.com/embed?system=30000142&zoom=120&coloring=security&performance=1"
  width="100%" height="450" frameborder="0"></iframe>
<script>
const map = document.getElementById('eo-map').contentWindow;
let ready = false;
window.addEventListener('message', (e) => {
  if (e.origin !== 'https://eo-map.com') return;
  if (e.data?.type === 'ef-map-ready') ready = true;
});
function onKill(systemId, capital, value) {
  if (!ready) return;
  map.postMessage(
    capital
      ? { type: 'ef-map-flash', systemId, kind: 'capital', value }
      : { type: 'ef-map-flash', systemId, kind: 'kill' },
    'https://eo-map.com'
  );
}
function focusSystem(systemId) {
  map.postMessage({ type: 'ef-map-navigate', systemId, zoom: 50 }, 'https://eo-map.com');
  map.postMessage({ type: 'ef-map-highlight', systems: [systemId] }, 'https://eo-map.com');
}
</script>

## 2D example

<iframe
  src="https://eo-map.com/embed?system=30000142&layout=2d&coloring=security&zoom=25&performance=1"
  width="100%"
  height="450"
  frameborder="0"
></iframe>

## Routing example

A routing embed does not frame the route by itself: add system= (the
start) and zoom= (about 30 for a 2-4 jump route) or the view stays wide.
routingCardMinimized=1 starts the card collapsed so the drawn route is the
picture; routeLabels=1 names the systems on it. Short routes read best.

<iframe
  src="https://eo-map.com/embed?routing=1&from=Jita&to=Sobaseki&jumpRange=1&system=30000142&zoom=30&routingCardMinimized=1&routeLabels=1"
  width="100%"
  height="450"
  frameborder="0"
></iframe>

## Solar-system example

<iframe
  src="https://eo-map.com/solar-system/30000142?embed=1"
  width="100%"
  height="450"
  frameborder="0"
></iframe>

## Well-known system ids

Jita 30000142
Perimeter 30000144
Niyabainen 30000143
Amarr 30002187
Rens 30002510
Dodixie 30002659
Hek 30002053

On eo-map.com: search a name, right-click the star, Copy System ID.

## Limits and honesty

- Public read-only map. No EVE SSO in third-party iframes.
- The EO live-events WebSocket does not connect in embed. Event flashes in an
  embed only happen when the host sends ef-map-flash.
- On production (eo-map.com), Google Analytics 4 records an anonymous page_view
  for embed loads, same as the full app. Preview builds do not inject GA.
- Embed layout= and coloring= do not write the visitor's normal EO-Map prefs.
- Open on EO-Map must remain visible.
- One persistent iframe. Prefer postMessage over replacing src.
- Use performance=1 and loading="lazy" when the embed is below the fold.
- Do not mount many WebGL embeds on one page.
- There is no public REST API for the map. This iframe is one integration.
  A native (non-iframe) JS embed is documented at https://eo-map.com/embed-native.txt.

Feature overview: https://eo-map.com/embed-map/
Human guide: https://eo-map.com/embed-guide
Site index for assistants: https://eo-map.com/llms.txt