Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The AerialSphere XP360 JavaScript API enables you to embed the XP360 client into your website, and use it to display your data. The following documentation applies only to users on our legacy API 1.0. For updated documentation on XP360 API Beta (2.0) please visit XP360 API [Beta] Reference


Table of Contents

Setup

First, create an iframe pointing to https://aerialspheres.com/map, and give it an id:

...


Expand
titleClick to expand live example code


Iframe
src//jsfiddle.net/bhank/35o7fz8d/embedded/dark/
width100%
frameborderhide
height500px




Functions


new AerialSphere()

The AerialSphere API object constructor takes 3 parameters:

  • displayElementId (string) - The id attribute which you used for your iframe.

  • mapClass (object) - The css class of the map DOM element.
  • sphereData (object) - Sphere data with which to initialize the iframe. sphereData can have these properties:

    • title (string) - A title for the sphere
    • sphere_lat (number) - The latitude of the sphere to display
    • sphere_lng (number) - The longitude of the sphere to display
    • lookat_lat (number) - The latitude the camera should look at
    • lookat_lng (number) - The longitude the camera should look at
    • camera_fov (number) - Camera field of view angle
    • camera_fovmin (number) - Minimum field of view angle
    • camera_fovmax (number) - Maximum field of view angle
    • layers (array) - An array of layer objects, one for each layer you want to display

Each layer object can have these properties:

  • name (string) - A name for the layer

  • markers (array) - An array of marker objects to display on the layer

Each marker object can have these properties:

  • name (string) - A name for the marker which will be displayed on the sphere. This can contain HTML.

  • id (number) - An id for the marker

  • lat (number) - The latitude at which to display the marker

  • lng (number) - The longitude at which to display the marker

  • icon (string) - The name of the icon to display for the marker. If the name is one of the following, then the marker icon will change as indicated here:

    • poi (default) <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#003868" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • food <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#003868" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • school <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#003868" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • search

    • shopping <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#003868" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • whats_here

    • apartment_sale <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#6BA53A" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • home_for_sale <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#6BA53A" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • home_for_sale_green <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#6BA53A" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • home_for_sale_blue <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#003868" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • home_for_sale_yellow <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#F0B323" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • home_for_sale_red <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#FF4B34" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

    • home_for_sale_purple <svg width="42" height="56" viewBox="0 0 42 56" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M18.1732 53.6838L18.174 53.6848C19.6592 55.4384 22.368 55.4384 23.8531 53.6848L23.8557 53.6817C26.3271 50.7394 30.5912 45.3935 34.2425 39.3683C37.8685 33.3851 41 26.5581 41 20.6954C41 9.79207 32.0413 1 21 1C9.95873 1 1 9.79207 1 20.6954C1 26.5582 4.13158 33.3852 7.76107 39.3687C11.416 45.394 15.6871 50.7402 18.1732 53.6838Z" fill="#A66894" stroke="#E9E9ED" stroke-width="2"/>
      </svg>

If more than one marker exists, the sphere will automatically rotate its point of view to accommodate.

sendData

sendData updates the sphere data for an existing sphere. It takes three parameters:

  • data (object) - The new sphere data; this supports the same properties as the data parameter of the new AerialSphere() constructor above.

  • force (boolean) - Specifies whether the sphere data will be updated even if the latitude and longitude parameters have not changed

  • disableAutoRotate (boolean) - If true, the sphere will not rotate its point of view even if more than one marker exists

setWidgetEnabled

setWidgetEnabled specifies whether various widgets are displayed on the sphere. It takes two parameters:

  • widgetName (string) |  (string[]) - The name or array of names of the widget(s) to enable or disable.

  • enabled (boolean) - true to enable the widget, false to disable

Available widget names are:

  • buttonsbar

  • compass

  • geoinfo

  • googlemaps

  • gyro

  • introimage

  • logo

  • markerdetails

  • messagebox

  • placebuttons


removeAllMarkers

removeAllMarkers removes all markers from the sphere. It takes no parameters.

openPanorama

openPanorama opens the sphere view. 

  • sphereLat (number) - latitude near the sphere
  • sphereLon (number) - longitude near the sphere
  • lookAtLat (number) - latitude of position to look at
  • lookAtLon (number) - longitude of position to look at

openMap

openMap opens a map instead of a sphere. It takes no parameters.

getNearestPano

getNearestPano searches for the sphere nearest to a specified latitude and longitude. It takes three parameters:

  • lat (number) - latitude to search for

  • lng (number) - longitude to search for

  • callback (function) - a callback function to receive the results of the search

The callback function takes a single parameter, result, which has the following properties:

  • distance (number) - the number of meters the nearest sphere is from the specified latitude and longitude

  • panoMarker (object)

    • marker (object)

      • position (object)

        • lat (number) - the latitude of the nearest sphere

        • lng (number) - the longitude of the nearest sphere

addMarker

addMarker adds a marker to the sphere at a specified latitude and longitude. It takes nine parameters:

  • lat (number) - the latitude at which to place the new marker

  • lng (number) - the longitude at which to place the new marker

  • address (string) - the address at which to place the new marker (instead of lat and lng)

  • title (string) - the title of the new marker

  • icon (string) - the name of the icon for the new marker (see the list of icon names in the constructor above)

  • layer (string) - the name of the layer to which to add the new marker

  • div_id (string)

  • meta_data (object)

  • callback (function)

The callback function takes a single parameter, result, which contains the added marker object.

setLayerVisibility

setLayerVisibility makes a layer visible or invisible. It takes two parameters:

  • layerName (string) - the name of the layer

  • visible (boolean) - whether the layer should be visible

lookAt

lookAt changes the camera angle. It takes two parameters:

  • pan (number) - the pan angle

  • tilt (number) - the tilt angle

setVar

setVar sets a sphere variable’s value. It takes two parameters:

  • variableName (string) - the name of the variable

  • value (any) - the value to which to set the variable

getVar

getVar gets a sphere variable’s value. It takes two parameters:

  • variableName (string) - the name of the variable

  • callback (function) - a callback function to receive the variable’s value

The callback function takes a single parameter, value, which contains the variable’s value

getPositionInfo

getPositionInfo gets the latitude, longitude, pan, and tilt corresponding to x and y coordinates on the sphere’s DOM element. It can be used with the onClick event to get the map location of a user’s click. It takes three parameters:

  • x (number) - the x-coordinate

  • y (number) - the y-coordinate

  • callback (function) - a callback function to receive the position info

The callback function takes four parameters:

  • lat (number) - the latitude corresponding to the specified coordinates

  • lon (number) - the longitude corresponding to the specified coordinates

  • pan (number) - the pan angle corresponding to the specified coordinates

  • tilt (number) - the tilt angle corresponding to the specified coordinates

Events

onClick

onClick is fired when a user clicks on the sphere. It receives no parameters.

In an onClick handler, you can get the x and y coordinates of the click by calling getVar twice, with the variable names mouse.x and mouse.y. You can then pass those x and y coordinates to getPositionInfo to get the corresponding map location.


Expand
titleClick to expand live example code


Iframe
src//jsfiddle.net/bhank/evhnfyr4/embedded/dark/
width100%
frameborderhide
height600px


onViewChange

onViewChange is fired when the view position of the sphere changes, either due to autorotation or the user moving the view. It receives no parameters.

It is called very frequently when moving around, so you should debounce any heavy tasks you are running in its handler.

onMarkerClick

onMarkerClick is fired when a user clicks on a marker. It receives one parameter:

  • id (any) - the id of the marker clicked