Migrating from AerialSphere API V1.0 to V2.0 [Beta]


Create an Account

You’ll need to create a new account to use API 2.0 [Beta]. Please visit https://app.aerialsphere.com/xp360api/create-account to create and activate your account and access your new API key. If you have an existing API 1.0 account, you will need to use a different email address to create your new account.

Note: If you prefer not to use a different email address, please contact support using the help icon in the bottom right corner of https://app.aerialsphere.com/xp360api/create-account and our team will work with you to adjustment your old account.

Configure API Key

Go to My API Keys (https://app.aerialsphere.com/xp360api/api-keys) and click the settings icon to customize your key. Give your key a meaningful name and make sure that your key is whitelisted for the domain on which you will be using it.

Note: The Trusted URLs defined for your key in API 1.0 do not carry over to API 2.0.

Update Script Tag

Update your script tag to point at the API 2.0 location:

  • Old: <script src="https://aerialspheres.com/map/api/js?key=INSERT_YOUR_KEY_HERE"></script>

  • New: <script src="https://app.aerialsphere.com/api/map/js?key=INSERT_YOUR_KEY_HERE"></script>


The constructor now takes three parameters: the ID of your div element (as opposed to the iframe element itself in 1.0), a CSS class name which will be added to the iframe element created inside your div, and a sphere data object.

  • Old: new AerialSphere(document.getElementById(iframeId), sphereData)

  • New: new AerialSphere(divId, 'iframeClassName', sphereData)


Replace your iframe pointing at API 1.0 with an empty div:

  • Old: <iframe id="as1" src="https://aerialspheres.com/map" style="width: 100%; height: 100%; border: 0px;"></iframe>

  • New: <div id="as1" style="width: 100%; height: 100%;" />


To handle API events in 1.0, you would assign an event handler function to a property of the API object. In 2.0, you pass your event handler function to an API function:

  • Old: aerialSphere.onClick = function () { … };

  • New: aerialSphere.onClick(function () { … });

The onClick event handler used to take no parameters, and you had to use getVar to find the mouse position, and call getPositionInfo to translate that to a latitude and longitude or a pan and tilt. It now takes one parameter, an object with properties which include the latitude, longitude, pan, and tilt.

The onMarkerClick event handler used to take one parameter, the id of the marker clicked. It now takes an object which has an id property.

The onViewChange event handler used to take no parameters. It now takes one parameter, an object with properties describing the new view position.

Note: for more details, please view API 2.0 [Beta] Events documentation.


Functions which take latitude and longitude parameters (such as addMarker and getNearestPano) no longer support string values for those parameters; they must be numbers, or the call will fail. And functions such as lookAt which take pan and tilt parameters require those to be numbers as well.

The setWidgetEnabled function uses different widget names; it also supports being passed an array of widget names instead of just a single one.

The sendData function no longer automatically enables autoRotate when markers are present; you must include it in the data if you want to enable it.

If you are passing the lookAtLat and lookAtLng parameters to the sendData function, you must also pass the lat and lng parameters as well.

The getVar and setVar functions are no longer available.

Note: for more details, please view API 2.0 [Beta] Events documentation.