XP360 API [Beta] Reference

Open

The AerialSphere XP360 JavaScript API enables you to embed the XP360 client into your website, and use it to display your data.

Setup

• Create an API key in My API Keys.

• Add a script tag to your page containing your API key: <script src="https://app.aerialsphere.com/api/map/js?key=YOUR-API-KEY-HERE"></script>

• Add a div to your page where our maps and imagery will display in a new iframe.

• Optional: set the styling on that iframe in your CSS, using a unique class name.

• Pass the div id and optional class name to a call to new AerialSphere()

• For a more complete setup guide, see Embedding AerialSphere's XP360 API into Your Website

Code Sample

Constructor

new AerialSphere()

Creates a new AerialSphere object, which is used for all the other functions documented here.

Parameters:

• displayElementId (string) - The id of your div. This div will end up with a child iframe element where our imagery will display.

• mapClass (object) - The css class that will be added to the generated iframe.

• sphereData (object) - Sphere data with which to initialize the iframe. sphereData can have these properties:

  • title (string): A title for the sphere

  • sphereLat (number): The latitude of the sphere to display

  • sphereLng (number): The longitude of the sphere to display

  • lookatLat (number): The latitude the camera should look at

  • lookatLng (number): The longitude the camera should look at

  • cameraFov (number): Camera field of view angle

  • cameraFovMin (number): Minimum field of view angle. Note: Cannot be less than 5.

  • cameraFovMax (number): Maximum field of view angle. Note: Cannot be greater than 120.

  • panoMarkerDistance (number): The distance, in meters, for which panorama markers are displayed

  • panoMarkerList (Array<number>): The list of specific panorama markers to display, by panorama id

  • customMarkerDistance(number): The distance, in meters, for which custom markers are displayed

  • customMarkerList(Array<number>): The list of specific custom markers to display, by custom marker id

  • 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. Each layer name should be unique.

    • visible (bool): Set this to true for the layer to show (defaults false).

    • 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. Any HTML will be sanitized.

      • id (number | string): An id for the marker. Each marker id must be unique. If this value is falsy, a uuid will be assigned as the id for this marker.

      • lat (number): The latitude at which to display the marker. Note: Cannot be a string.

      • lng (number): The longitude at which to display the marker. Note: Cannot be a string.

      • icon (string): The name of the icon to display for the marker. If the name is one of the default icon names, the marker icon will change as indicated. See list of all available icons here.

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

      • Marker pop-ups can also be customized, for more information visit here.

  • fontFamilies (string): The string pulled from google fonts in order to allow custom fonts. Note: Only works when done during API initialization.

    • Example(highlighted text):

      • <link href="https://fonts.googleapis.com/css2?family=Comic+Neue:wght@300&family=DotGothic16&family=Stick&family=Syne+Mono&display=swap" rel="stylesheet">

  • apiUIOptions (string): The UI widgets that are displayed in the viewer.

    • Each option can be set to true or false. All are optional and assumed to be true if they are not specified.

      • fullScreen: Set this to false to hide the widget.

      • snapshot: Set this to false to hide the widget.

      • help: Set this to false to hide the widget.

      • info: Set this to false to hide the widget.

      • view_toggle: Set this to false to hide the widget.

      • navigation: Set this to false to hide the widget.

  • showFlyHere (boolean): Toggle if the Fly Here portion of marker Pop-ups is shown.

Note: The normal behavior is to call the constructor passing the 3 basic parameters (as shown in the example below), when there is no data provided the API will result in loading the map by default, also make sure to use the proper variable names to pass such as sphereLat, sphereLng, lookAtLng, cameraFov, etc.

Note: The set functions will be overridden by already defined parameters while viewer is being initialized. for example: If cameraZoomMin is already defined to 5.0 like in the example below,
setting setZoomto 1.0 won’t work.

Custom Fonts

Functions

addMarker

Adds a marker to the sphere, either at a specified latitude and longitude, or at the specified address.

Parameters:

• *lat (number): The latitude at which to place this marker (required unless address is passed).

• *lng (number): The longitude at which to place this marker (required unless address is passed).

• address (string): The street address at which to place this marker. When using this, lat and lng can be empty.

• title (string): The title for this marker, which will be displayed within the marker popup.

• description (string): A description for the marker, which will be displayed within the marker popup. This can contain HTML. When both title and description are passed, the description shows up below the title, and the title stands out more.

• icon (string): The name of the icon for this marker (see the list of icon names in the constructor above).

• layer (string): When passed, the marker will be added to the named layer.

• id (number | string): An id for this marker. This value must be unique. If this value is falsy, a uuid will be assigned as the id for this marker.

• hoverText (string): The string that should be displayed on hovering the marker. This is only meant to contain a string of text.

• popup (boolean): When passed, it can be used to enable or disable marker popups by setting popup to true or false. popup is set to true by default if not passed.

• metaData (object)

• callback (function): A function to execute after adding the marker. Takes a single parameter, result, which contains the added marker object.

• showFlyHere (object): Toggle if the Fly Here portion of marker Pop-up is shown, will overwrite AerialSphere object settings.

  • enabled(boolean): Key/value pair for setting fly here on specific marker.

    • ex: showFlyHere: { enabled: false } disables this specific markers pop-up

• Marker pop-ups can also be customized. For more information visit here.

Code Sample

getActivePano

Gets the active sphere, passes it to the optional callback function (if provided), and returns it.

Parameter:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed an object with the following attributes automatically:

  • id (number): The id of the sphere

  • lat (number): The latitude of the sphere

  • lng (number): The longitude of the sphere

  • dateTimeAcquired (string | null): A string representing the date that the sphere imagery was captured

Returns: A promise that resolves to the same object that is passed to the optional callback.

Code Sample

getData

Gets the data specified below about the active sphere, passes it to the optional callback function (if provided), and returns it.

Parameter:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed an object with the following attributes automatically. Each of these attributes will be undefined if there is no active sphere:

  • sphereLat (number): The latitude of the active sphere

  • sphereLng (number): The longitude of the active sphere

  • title (string): The title of the active sphere

  • lookAtLat (number): The latitude of the pixel the user is looking at. See sendData.

  • lookAtLng (number): The longitude of the pixel the user is looking at. See sendData.

  • cameraFov (number): A number representing the current field of view

  • cameraFovMin (number): The minimum valid field of view for the current sphere

  • cameraFovMax (number): The maximum valid field of view for the current sphere

  • cameraZoom (number): A number representing the current zoom level

  • cameraZoomMin (number): The minimum valid zoom level for the current sphere

  • cameraZoomMax (number): The maximum valid zoom level for the current sphere

  • panoMarkerDistance (number): The distance, in meters, for which panorama markers are displayed

  • panoMarkerList (Array<number>): The list of specific panorama markers to display, by panorama id

  • customMarkerDistance(number): The distance, in meters, for which custom markers are displayed

  • customMarkerList(Array<number>): The list of specific custom markers to display, by custom marker id

  • autoRotate (object): The autorotate object for the current sphere. It has the following properties. See sendData for how to update this object.

    • on (boolean): Whether or not the camera should be automatically rotating (ie, panning around the sphere)

    • speed (number): The speed of auto-rotation

    • right (boolean): If true, then rotate right. If false, then rotate left.

    • tilt (number): The tilt for the camera to rotate towards and then hold

    • fov (number): The field of view for the camera to rotate towards and then hold

  • layers (array): An array of the layers for the active sphere

  • showFlyHere (boolean): Toggle if the Fly Here portion of marker Pop-ups is shown.

Returns: A promise that resolves to the same object that is passed to the optional callback.

Code Sample

getFov

Gets the current field of view for the active sphere, passes it to the optional callback function (if provided), and returns it. See sendData for how to set this value.

Parameter:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed the following automatically:

  • cameraFov (number): A number representing the current field of view

Returns: A promise that resolves to cameraFov: A number representing the current field of view

Code Sample

getFovRange

Gets the range for the field of view for the active sphere, passes it to the optional callback function (if provided), and returns it. See sendData for how to set these values.

Parameter:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed an object with the following attributes automatically:

  • cameraFovMin (number): The minimum valid field of view for the current sphere

  • cameraFovMax (number): The maximum valid field of view for the current sphere

Returns: A promise that resolves to the same object that is passed to the optional callback.

Code Sample

getLayer

Searches for a layer with the given name, passes it to the optional callback function (if provided), and returns it.

Parameters:

• name (string): the name of the layer to search for

• callback (function): (OPTIONAL) A callback function to execute. It will be passed the layer found, which may be null if no layer matches name.

Returns: A promise that resolves to layer (object): The layer matching name, or null if no layer matches name.

Code Sample

getLookAt

Gets data about where the user is looking, passes it to the optional callback function (if provided), and returns it.

Parameter:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed an object with the following attributes automatically:

  • pan (number): The pan (ie, left or right shift) of where the user is facing in the current sphere

  • tilt (number): The tilt (ie, up or down shift) of where the user is facing in the current sphere

Returns: A promise that resolves to the same object that is passed to the callback.

Code Sample

getMarker

Searches for a marker with the given id, passes it to the optional callback function (if provided), and returns it.

Parameters:

• id (string): The assigned id of the marker to search for. See addMarker for details on how this id is assigned.

• callback (function): (OPTIONAL) A callback function to execute. It will be passed the following:

  • marker (object): The marker found. It has the following properties:

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

    • id (number | string): 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

    • style (object)

    • metaData (object)

Returns: A promise that resolves to the marker object that is passed to the callback.

Code Sample

getNearestPano

Searches for the sphere nearest to a specified latitude and longitude, passes it to the optional callback function (if provided), and returns it.

Parameters:

• lat (number): Latitude for search

• lng (number): Longitude for search

• callback (function): (OPTIONAL) A callback function to execute after finding the nearest sphere. It will be passed an object with the the following attributes automatically:

  • distance (number): The distance (in meters) between the location specified by lat and lng and the sphere found, or undefined if no sphere was found

  • panoId: (number): The id of the sphere found, or undefined if no sphere was found

  • panoMarker: An object with one value:

    • marker: An embedded object with one value:

      • position: An object with 2 values representing the position of the sphere, or undefined if no sphere was found

        • lat: The latitude of the sphere

        • lng: The longitude of the sphere

Returns: A promise that resolves to the same object that is passed to the callback.

Code Sample

getPanoramas

Finds and returns all spheres, passes them to the optional callback function (if provided), and returns them.

Parameters:

• callback (function): (OPTIONAL) A callback function to execute after finding the nearest sphere. It will be passed the following automatically:

  • response (array): An array of all spheres. Each sphere is an object with the following properties:

    • id (number): The sphere id

    • latitude (number): The latitude of the sphere

    • longitude (number): The longitude of the sphere

    • dateTimeAcquired (string | null): A string representing the date that the sphere imagery was captured

Returns: A promise that resolves to response (array): An array of all spheres.

Code Sample

getPositionInfo

Gets the latitude/longitude and pan/tilt position for a pixel on the screen within the active sphere, passes that info to the optional callback function (if provided), and returns the info.

Parameters:

• x (number): The x-position of the chosen pixel on the map, where 0 is the left-most pixel

• y (number): The y-position of the chosen pixel on the map, where 0 is the top-most pixel

• callback (function): (OPTIONAL) A callback function to execute. It will be passed the following:

  • posLat (number): The latitude associated with the chosen pixel on the screen

  • posLng (number): The longitude associated with the chosen pixel on the screen

  • posPan (number): The pan (ie, left or right shift) associated with the chosen pixel on the screen

  • posTilt (number): The tilt (ie, up or down shift) associated with the chosen pixel on the screen

Returns: A promise that resolves to the 4 attributes that are passed to the callback.

Code Sample

getZoom

Gets the current zoom level for the active sphere, passes it to the optional callback function (if provided), and returns it. See sendData for how to set this value.

Parameters:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed an object with the following attribute automatically:

  • cameraZoom (number): A number representing the current zoom level

Returns: A promise that resolves to the same object that is passed to the callback.

Code Sample

getZoomRange

Gets the zoom level range for the active sphere, passes it to the optional callback function (if provided), and returns it. See sendData for how to set these values.

Parameters:

• callback (function): (OPTIONAL) A callback function to execute. It will be passed an object with the following attributes automatically:

  • cameraZoomMin (number): The minimum valid field of view for the current sphere

  • cameraZoomMax (number): The maximum valid field of view for the current sphere

Returns: A promise that resolves to the same object that is passed to the callback.

Code Sample

lookAt

Sets the pan and tilt.

Parameters:

• pan (number): The pan (ie, left or right shift) of where to face in the current sphere

• tilt (number): The tilt (ie, up or down shift) of where to face in the current sphere

Returns: Nothing

Code Sample

openMap

Opens the map view. Closes the sphere view if it is open.

Parameters: None

Returns: Nothing

Code Sample

openPanorama

Opens the sphere view. Closes the map view if it is open. This has no effect if there is no active sphere.

Parameters: None

Returns: Nothing

Code Sample

openPanoramaById

Opens the sphere view for the given sphere. Closes the map view if it is open.

Parameter:

• panoId (number): The id of the sphere to open

Returns: Nothing

Code Sample

closePanorama

Opens the map view and closes the sphere view. This has no effect if it is already in the map view.

Parameters: None

Returns: Nothing

Code Sample

removeAllMarkers

Deletes all markers by setting sphereData to an object with only an empty layers array.

Parameters: None

Returns: Nothing

Code Sample

sendData

The behavior of this function depends on what is passed in, if no new sphere lat/lng is passed sent data will impact current sphere. See below.

Parameter:

• sphereData (object): An object with many optional properties. This function may take actions using one or more of these properties, as indicated:

  • sphereLat and sphereLng (numbers): If both of these properties are passed, then the nearest sphere to the specified coordinates will be found and acted upon as follows:

    • The sphere found will be set as the active sphere and loaded

    • If lookAtLat and lookAtLng are also passed in the sphereData object, then they will be used to set the pan and tilt. The specified coordinates will be used to calculate a pixel viewable from the newly loaded sphere, and the sphere will be rotated such that that pixel will be in the center of the screen. See getData.

    • If lookAtLat and/or lookAtLng are not passed, then the default orientation will be used for the loaded sphere

  • cameraFov (number): The field of view will be set to the given value. See getFov.

  • cameraFovMin (number): If the specified value is greater than 5, then this function sets the minimum allowed field of view to the given value. See getFovRange.

  • cameraFovMax (number): If the specified value is less than 120, then this function sets the maximum allowed field of view to the given value. See getFovRange.

  • cameraZoom (number): The zoom level will be set to the given value. See getZoom.

  • cameraZoomMin (number): If the specified value is greater than 0, then this function sets the minimum allowed zoom level to the given value. See getZoomRange.

  • cameraZoomMax (number): If the specified value is greater than 0, then this function sets the maximum allowed zoom level to the given value. See getZoomRange.

  • title (string): The title of the active sphere will be updated to this value.

  • panoMarkerDistance (number): The distance, in meters, for which panorama markers are displayed. The default is 4000. See setPanoMarkerDistance.

  • panoMarkerList (Array<number>): The list of specific panorama markers to display, by panorama id. Ignores the distance defined by panoMarkerDistance. See setPanoMarkerList.

  • customMarkerDistance(number): The distance, in meters, for which custom markers are displayed. See setCustomMarkerDistance.

  • customMarkerList(Array<number>): The list of specific custom markers to display, by custom marker id. Ignores the distance defined by customMarkerDistance. See setCustomMarkerList.

  • layers (array of objects): Each item in the array will be treated as a layer object. For each layer, the following will happen (see also getLayer):

    • Each of the layer’s markers that is missing an id will be assigned a uuid

    • The layer will be validated

    • The layer will be sanitized

  • autoRotate (object): If any of the following propertied are specified in the object, then they will be updated for the current sphere. See getData.

    • on (boolean): Whether or not the camera should be automatically rotating (ie, panning around the sphere)

    • speed (number): The speed of auto-rotation

    • right (boolean): If true, then rotate right. If false, then rotate left.

    • tilt (number): The tilt for the camera to rotate towards and then hold

    • fov (number): The field of view for the camera to rotate towards and then hold

Returns: Nothing

Note: The field of view and zoom settings are complimentary. You should either set cameraFov, cameraFovMin, and cameraFov; or cameraZoom, cameraZoomMin, and cameraZoomMax; but not both sets of values.

Code Sample

setFov

Sets the current field of view for the active sphere.

Parameter:

• cameraFov(number): A number representing the current field of view

Returns: Nothing

Code Sample

setFovRange

Sets the range for the field of view for the active sphere.

Parameter:

• cameraFovMin (number): The minimum valid field of view for the current sphere

• cameraFovMax (number): The maximum valid field of view for the current sphere

Returns: Nothing

Code Sample

setLayerVisibility

Sets the visibility for the specified layer.

Parameters:

• layerName (string): The name of the layer to update

• visible (boolean): If true, then show the layer; if false, then hide the layer

Returns: Nothing

Throws: Error in the console if a layer is not found with a name that matches layerName.

Code Sample

setPanoMarkerDistance

Sets the distance, in meters, for which panorama markers are displayed. Set to zero to not display any panorama markers. Ignored if there is a panorama marker list (see setPanoMarkerList).

Parameters:

• panoMarkerDistance (number): The distance, in meters.

Returns: Nothing

Throws: Never

Code Sample

setPanoMarkerList

Set a list of specific panorama markers to display, regardless of the distance defined by panoMarkerDistance. The list contains panorama ids. Set to [] to clear the list.

Parameters:

• list (Array<number>): The list of panorama ids, identifying the panorama markers to display.

Returns: Nothing

Throws: Never

Code Sample

setCustomMarkerList

Set a list of specific custom markers to display, regardless of the distance defined by customMarkerDistance. The list contains custom marker ids. Set to [] to clear the list.

Parameters:

• list (Array<number>): The list of custom marker ids, identifying the custom markers to display.

Returns: Nothing

Throws: Never

Code Sample

setCustomMarkerDistance

Sets the distance, in meters, for which custom markers are displayed. Set to zero to not display any custom markers. Ignored if there is a custom marker list (see setCustomMarkerList).

Parameters:

• customMarkerDistance(number): The distance, in meters.

Returns: Nothing

Throws: Never

Code Sample

setWidgetEnabled

Hides or shows UI widgets.

Parameters:

• widgetName (string | array of strings): The name or list of names of widgets to enable/disable. The following strings are supported. If any other strings are passed, then the whole operation will fail.

  • fullScreen: the button to switch to full-screen mode

  • help: the button to bring up on-screen help for using the viewer

  • info: the button to show info about the current sphere

  • snapshot: the button to display the SnapshotHD feature functionality

  • navigation: the zoom and compass buttons

  • view_toggle: the button to toggle between sphere and map view

• enabled (boolean): If true, then show the given widget(s); if false, then hide them. (By default, all are visible.)

Returns: A promise that resolves to an object with boolean properties corresponding to each possible widget name above, set to true if that widget is visible.

Code Sample

setZoom

Sets the current zoom level for the active sphere.

Parameters:

• cameraZoom (number): A number representing the current zoom level

Returns: Nothing

Code Sample

setZoomRange

Sets the zoom level range for the active sphere.

Parameters:

• cameraZoomMin (number): The minimum valid field of view for the current sphere

• cameraZoomMax (number): The maximum valid field of view for the current sphere

Returns: Nothing

Code Sample

Events

onClick

The callback function passed here becomes the onclick handler for clicks within the AerialSphere frame.

Parameter:

• callback (function): A callback function to execute. It will be passed an object with the following properties:

  • pan (number): The pan of the click event

  • tilt (number): The tilt of the click event

  • lat (number): The calculated latitude at the click event

  • lon (number): The calculated longitude at the click event

  • lng (number): The calculated longitude at the click event

  • ele (number): The calculated altitude at the click event, measured in meters above sea level

Returns: Nothing

Code Sample

onMarkerClick

The callback function passed here handles clicks on user-defined markers. See addMarker for documentation on creating markers.

Parameter:

• callback (function): A callback function to execute. It will be passed an object with the following property:

  • id (number): The id of the marker clicked. It’s up to the user to use the id to act on the associated marker.

Returns: Nothing

Code Sample

onViewChange

The callback function passed here is called whenever the view is changed by the user within the sphere view. User-changed views happen when the user adjusts pan or tilt with their mouse, or when they zoom in or out.

Parameter:

• callback (function): A callback function to execute. It will be passed an object with the following properties:

  • azimuthAngle (number): The pan after the view change

  • polarAngle (number): The tilt after the view change

  • zoom (number): The new zoom level after the view change. See sendData for how to set the zoom programmatically, and getData for reading the current zoom level outside of events.

  • eventName (string): The name of the view change event. The possibilities are:

    • "controlstart": When the user starts to control the camera via mouse / touches

    • "control": When the user controls the camera (dragging)

    • "controlend": When the user ends to control the camera

    • "update": When the camera position is updated

    • "wake": When the camera start moving

    • "sleep": When the camera end moving

  • zoom (number): The zoom after the view change

Returns: Nothing

Code Sample