Audiom Embed Endpoint Documentation

The Audiom Embed Endpoint allows you to integrate the Audiom inclusive map solution into your platform using an iFrame. The service dynamically generates an interactive map based on the URL query parameters provided.

URL Structure

The base URL for the embed endpoint typically follows this pattern: https://[your-audiom-instance-url]/embed/[embedId]

Query parameters are appended to this URL to configure the map.

Path Parameters

embedId (Required in URL Path)

Query Parameters

The following parameters can be passed via the URL query string:

apiKey (Required)

Contact the XR Navigation team if you need an API key.

sources (Optional)

center (Optional)

latitude (Optional)

longitude (Optional)

zoom (Optional)

soundpack (Optional)

visualStyle (Optional)

visualbaselayer (Optional)

visualbaselayerposition (Optional)

demo (Optional)

title (Optional)

showVisualMap (Optional)

heading (Optional)

showHeading (Optional)

stepsize (Optional)

Multi-Source Configuration

For advanced configurations with multiple data sources, you can use namespaced parameters to pass source-specific settings. This works identically to the /map endpoint.

Format: {sourceName}.{parameter}={value}

Source-Specific Parameters

Complete Example:

/embed/dynamic?source=routes,elevation&routes.type=esri&routes.url=https://example.com/service&elevation.mapType=heatmap&apiKey=xyz123

Other Parameters

Parameters NOT Supported in Embed

The following parameters are available in the /map endpoint but NOT supported in the /embed endpoint:

If these parameters are passed to the embed endpoint, they will be ignored.

Error Handling

API Key Not Provided

Rate Limit Exceeded

Data Loading Errors

PostMessage API

The Audiom Embed API provides bidirectional communication between embedded maps and parent windows using the postMessage API. This allows external applications to control the embedded map and receive real-time updates about user interactions.

Enabling the API

The PostMessage API is disabled by default for security. To enable it, you must specify which origins are allowed to communicate with the embedded map using the allowedOrigins URL parameter.

allowedOrigins (Required to enable API)

Complete embed URL example:

/embed/dynamic?source=osm&latitude=47.6495&longitude=-122.1431&apiKey=xyz123&allowedOrigins=https://myapp.com

Message Format

All messages follow a consistent structure with type and payload properties:

interface Message {
  type: string;
  payload: object;
}

Outbound Events (Embed → Parent)

These events are sent from the embedded Audiom map to your parent window.

ready

Sent when the embed is fully initialized and ready to receive commands.

// Payload
{
  apiVersion: "1.0.0"  // Semantic version of the API
}

positionChanged

Sent whenever the avatar’s position changes.

// Payload
{
  position: [longitude, latitude]  // GeoJSON coordinate order
}

featureEntered

Sent when the avatar enters one or more map features (e.g., buildings, parks).

// Payload
{
  features: [
    {
      id: "feature-123",
      name: "Central Park",
      type: "park",
      position: [longitude, latitude],
      properties: { /* original feature properties */ }
    }
  ]
}

featureExited

Sent when the avatar exits one or more map features.

// Payload
{
  features: [
    {
      id: "feature-123",
      name: "",  // May be empty for exited features
      type: "unknown",
      position: [0, 0],
      properties: {}
    }
  ]
}

featureSelected

Sent when the avatar crosses a feature boundary. Contains all features currently enclosing the avatar.

// Payload
{
  features: [/* array of FeaturePayload objects */]
}

stateChanged

Response to a getState query. Contains the current avatar position.

// Payload
{
  position: [longitude, latitude]
}

error

Sent when an error occurs processing an inbound command.

// Payload
{
  code: "INVALID_ORIGIN",  // Error code
  message: "Origin https://evil.com not allowed"  // Human-readable message
}

// Error codes:
// - INVALID_ORIGIN: Message from disallowed origin
// - INVALID_MESSAGE: Message format is invalid
// - UNKNOWN_COMMAND: Unknown command type
// - COMMAND_FAILED: Command execution failed
// - NOT_READY: API not initialized

Inbound Commands (Parent → Embed)

Send these commands from your parent window to control the embedded map.

moveAvatar

Move the avatar to a specific geographic position.

iframe.contentWindow.postMessage({
  type: 'moveAvatar',
  payload: {
    position: [-122.4194, 37.7749]  // [longitude, latitude]
  }
}, 'https://[your-audiom-instance-url]');

getState

Query the current avatar position. The embed responds with a stateChanged event.

iframe.contentWindow.postMessage({
  type: 'getState'
}, 'https://[your-audiom-instance-url]');

getEnclosingFeatures

Query the features currently enclosing the avatar. The embed responds with a featureSelected event.

iframe.contentWindow.postMessage({
  type: 'getEnclosingFeatures'
}, 'https://[your-audiom-instance-url]');

setFilters

Set feature type filters for global display and/or sonar scanning.

iframe.contentWindow.postMessage({
  type: 'setFilters',
  payload: {
    global: ['building', 'park'],  // Types to show globally
    scan: ['poi', 'transit']       // Types to include in sonar scan
  }
}, 'https://[your-audiom-instance-url]');

executeCommand

Execute an Audiom keyboard command programmatically.

iframe.contentWindow.postMessage({
  type: 'executeCommand',
  payload: {
    command: 'announcePosition'  // Command name
  }
}, 'https://[your-audiom-instance-url]');

// Common commands: 'up', 'down', 'left', 'right', 'toggleSonar', 'announcePosition'

Complete Integration Example

// Get reference to the iframe
const iframe = document.getElementById('audiom-embed');
const audiomOrigin = 'https://your-audiom-instance.com';

// Listen for messages from the embed
window.addEventListener('message', (event) => {
  // Security: verify the message origin
  if (event.origin !== audiomOrigin) return;

  const { type, payload } = event.data;

  switch (type) {
    case 'ready':
      console.log('Audiom ready, API version:', payload.apiVersion);
      break;

    case 'positionChanged':
      console.log('User moved to:', payload.position);
      // Update your UI with the new position
      updateMapMarker(payload.position);
      break;

    case 'featureEntered':
      console.log('User entered features:', payload.features);
      // Show feature info in your sidebar
      showFeatureDetails(payload.features);
      break;

    case 'featureExited':
      console.log('User exited features:', payload.features.map(f => f.id));
      break;

    case 'error':
      console.error('Audiom error:', payload.code, payload.message);
      break;
  }
});

// Send a command to move the avatar
function moveToLocation(lng, lat) {
  iframe.contentWindow.postMessage({
    type: 'moveAvatar',
    payload: { position: [lng, lat] }
  }, audiomOrigin);
}

// Query current state
function getCurrentPosition() {
  iframe.contentWindow.postMessage({
    type: 'getState'
  }, audiomOrigin);
}

Security Best Practices

  1. Always specify explicit origins: Avoid using allowedOrigins=* in production. List only the domains that need to communicate with the embed.

  2. Validate message origins: Always check event.origin in your message handler to ensure messages are from your Audiom instance.

  3. Use HTTPS: Both your application and the Audiom embed should use HTTPS to prevent message interception.

iFrame Permissions

Fullscreen Support

Audiom supports fullscreen mode, which is especially useful during demos and presentations. Users can toggle fullscreen by:

Important: For fullscreen to work within an embedded iframe, you must include the allowfullscreen attribute on your iframe element:

<iframe
	src="https://[your-audiom-instance-url]/embed/12345?apiKey=xyz123"
	allowfullscreen
></iframe>

Or using the modern Permissions Policy syntax:

<iframe
	src="https://[your-audiom-instance-url]/embed/12345?apiKey=xyz123"
	allow="fullscreen"
></iframe>

If the allowfullscreen attribute is not present, users will receive an audio message saying “Fullscreen is not available” when attempting to enter fullscreen mode.

For the best user experience, we recommend the following iframe configuration:

<iframe
	src="https://[your-audiom-instance-url]/embed/12345?apiKey=xyz123"
	title="Audiom Interactive Map"
	allowfullscreen
	style="width: 100%; height: 600px; border: none;"
></iframe>