...
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 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
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 spheresphere_lat
(number) - The latitude of the sphere to displaysphere_lng
(number) - The longitude of the sphere to displaylookat_lat
(number) - The latitude the camera should look atlookat_lng
(number) - The longitude the camera should look atcamera_fov
(number) - Camera field of view anglecamera_fovmin
(number) - Minimum field of view anglecamera_fovmax
(number) - Maximum field of view anglelayers
(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 layermarkers
(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 markerlat
(number) - The latitude at which to display the markerlng
(number) - The longitude at which to display the markericon
(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 changeddisableAutoRotate
(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 spheresphereLon
(number) - longitude near the spherelookAtLat
(number) - latitude of position to look atlookAtLon
(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 forlng
(number) - longitude to search forcallback
(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 longitudepanoMarker
(object)marker
(object)position
(object)lat
(number) - the latitude of the nearest spherelng
(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 markerlng
(number) - the longitude at which to place the new markeraddress
(string) - the address at which to place the new marker (instead of lat and lng)title
(string) - the title of the new markericon
(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 markerdiv_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 layervisible
(boolean) - whether the layer should be visible
lookAt
lookAt
changes the camera angle. It takes two parameters:
pan
(number) - the pan angletilt
(number) - the tilt angle
setVar
setVar
sets a sphere variable’s value. It takes two parameters:
variableName
(string) - the name of the variablevalue
(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 variablecallback
(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-coordinatey
(number) - the y-coordinatecallback
(function) - a callback function to receive the position info
The callback
function takes four parameters:
lat
(number) - the latitude corresponding to the specified coordinateslon
(number) - the longitude corresponding to the specified coordinatespan
(number) - the pan angle corresponding to the specified coordinatestilt
(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 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
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