aureality.cloud

Developers · Globe API v1

Put your places on the Aureality globe

Send people to a place, a set of places or your own GeoJSON on the Aureality globe, or embed the globe in your page and talk to it. You only need a link or an iframe.

• No key, no sign-up
• Links: ?pin ?fly ?geojson ?layers ?pick
• Embeds: postMessage, 6 commands, 3 events
• Status: v1, stable
• Coordinates: WGS 84, lat,lon

Links

Add query parameters to https://aureality.cloud/. The globe reads them once, after the Earth has loaded.

Encode labels and URLs with encodeURIComponent. Pins are added only for valid coordinates (latitude −90 to 90, longitude −180 to 180).

Build a link in code

const u = new URL('https://aureality.cloud/');
u.searchParams.set('pin', '50.0875,14.4214|Old Town Square');
u.searchParams.set('text', 'Meet by the astronomical clock at 18:00.');
u.searchParams.set('from', 'Our club');
u.searchParams.set('color', '5FD3A8');
u.toString();
// https://aureality.cloud/?pin=50.0875%2C14.4214%7COld+Town+Square&text=…

Camera position

To open the globe at an exact camera, use the hash instead of a query. It is the same format the globe uses for its own place links.

Embed the globe

Put the globe in an iframe. Every link parameter above also works in the iframe’s src.

<iframe
  id="aureality"
  src="https://aureality.cloud/?pin=50.0875,14.4214|Old%20Town%20Square"
  title="Map: Aureality globe"
  style="width:100%;aspect-ratio:16/10;border:0;border-radius:12px"
  loading="lazy"
  allow="fullscreen">
</iframe>
<p style="font-size:12px">Map: <a href="https://aureality.cloud/">Aureality</a>,
data credits on the map and in <a href="https://aureality.cloud/legal/#credits">Legal</a></p>

Talk to an embedded globe

Your page and the globe exchange postMessage messages. Every message is an object whose type starts with aureality:. Wait for aureality:ready before you send: the globe ignores commands that arrive before the Earth has loaded.

const globe = document.getElementById('aureality');
const ORIGIN = 'https://aureality.cloud';
const send = (msg) => globe.contentWindow.postMessage(msg, ORIGIN);

addEventListener('message', (e) => {
  if (e.origin !== ORIGIN) return;          // accept events only from the globe
  const m = e.data;
  if (m.type === 'aureality:ready') {
    send({ type: 'aureality:pin', pins: [
      { lat: 50.0875, lon: 14.4214, label: 'Prague', text: 'Office' },
      { lat: 48.2082, lon: 16.3738, label: 'Vienna', color: '#5FD3A8' }
    ]});
  }
  if (m.type === 'aureality:selected') console.log('Tapped', m.label, m.lat, m.lon);
  if (m.type === 'aureality:picked')   console.log('Chosen', m.lat, m.lon, 'zoom', m.zoom);
});

Commands you send

Events you receive

The globe accepts commands from any page that embeds it and posts its events to the parent page. Events carry only coordinates and labels, so never put private data in pins you send. Check e.origin in your own listener, as in the example.

GeoJSON

Send a Feature or FeatureCollection (RFC 7946, coordinates as [lon, lat]). The globe draws:

• Polygons with a light fill (25 %) and a 2 px outline.
• Lines as a 2 px line.
• Points as pins, the first 500 of them. Each pin takes its label from properties.name, title or label, its card text from description or text, a source link from url and its own colour from color.

{
  "type": "FeatureCollection",
  "features": [
    { "type": "Feature",
      "properties": { "name": "Brno", "description": "Second stop", "url": "https://www.brno.cz/" },
      "geometry": { "type": "Point", "coordinates": [16.6068, 49.1951] } },
    { "type": "Feature",
      "properties": {},
      "geometry": { "type": "LineString",
        "coordinates": [[14.4214, 50.0875], [16.6068, 49.1951], [17.1077, 48.1486]] } }
  ]
}

For ?geojson=, the file must be served over https and allow cross-origin reads (Access-Control-Allow-Origin: *, or at least https://aureality.cloud). The visitor’s browser fetches it straight from your server; Aureality does not copy or store it. If the file cannot be loaded, the globe opens without it.

Layer ids

Use these with ?layers= or aureality:layers. Each layer keeps the credits and limits it has on the globe.

• These ids only switch layers on. Ids that are unknown, planned or need sign-in are ignored, and at most 40 ids are read.
• On aureality.cloud itself, layers switched on by a link are added to the visitor’s saved choices. Inside an iframe they are on for that visit only and are never saved.
• Several country-colour layers share one map fill, so switching on one of them replaces another.

Live demo

The buttons send real messages to the embedded globe below. The log shows what goes out and what comes back.

Data and licences

Your data

Pins, GeoJSON and coordinates you send stay in the visitor’s browser for that visit. Aureality does not receive, store or publish them. You are responsible for having the right to show what you send.

Credits you must keep

The globe shows its credits on the map, and the full list is on the Legal page. When you link to or embed the globe, keep those credits visible. When you show a screenshot or video of the globe, credit at least the base map:

Aureality (aureality.cloud) · © OpenStreetMap contributors (ODbL) · OpenMapTiles / OpenFreeMap
· Sentinel-2 cloudless 2016 by EOX IT Services GmbH (CC BY 4.0), contains modified Copernicus Sentinel data 2016 & 2017
· NASA Black Marble · Terrain: Mapterhorn, Copernicus DEM

The API lets you show these layers on the globe. It does not give you a licence to download or reuse the layer data elsewhere; for that, go to each source and follow its licence. Several live feeds are fetched through small aureality.cloud proxies with short caches. Those proxies serve the globe only and are not part of this API.

Fair use

• The API is free and needs no key. There is no uptime guarantee, and live layers depend on their sources.
• This is version 1. If a name on this page changes, the change will be announced in News first.
• Do not present your page as made by or endorsed by Aureality. Use the Aureality name only to say where the map comes from.
• Do not use the globe to show unlawful content or to collect visitors’ locations without their consent.
• Questions and ideas: [email protected]