XERRA URL API
Developer documentation for integrating external applications with XERRA via URL parameters.
Overview
The XERRA URL API allows external applications to open XERRA at a specific geographic location or profile by constructing a URL with query parameters. Any external map, asset database, or web application can link directly into XERRA.
The URL can be:
- Used as a direct hyperlink or bookmark
- Set via
window.location.href to navigate the current page - Opened in a new tab or reusable named window via
window.open()
Base URL
| Environment | URL |
|---|
| Production | https://xerra.agonics.com/api |
| Processing | https://xerra-processing.agonics.com/api |
All parameters are passed as query string values appended to the base URL.
Authentication
Users can be authenticated with XERRA via named users with username and password, or via Single Sign-On from your organisation's identity provider. The XERRA URL API operates authentication through the XERRA frontend when it opens in the browser, before continuing with the desired API action below.
Local login requires an existing XERRA username and password for the individual user. Single Sign-On requires an existing SSO Domain setup with XERRA for the organisation and for the individual user to be a member of the organisation's identity provider. Once a user is already logged in to XERRA, these parameters can be omitted.
| Parameter | Type | Required | Description |
|---|
mode | 'sso' | 'local' | No | sso — Single Sign-On via Microsoft Entra ID. local — username and password login. |
ssoDomain | string | When mode=sso | The SSO domain for the organisation. Contact Agonics to set up single sign-on with XERRA. |
Actions
The action parameter determines what XERRA does when the URL is loaded.
Navigate XERRA to a geographic location specified by latitude and longitude coordinates in WGS84 decimal degrees.
| Parameter | Type | Description |
|---|
action | "flyToLidarLocation" | Action identifier. |
lat | string | Latitude in decimal degrees (WGS84). |
lon | string | Longitude in decimal degrees (WGS84). |
Behaviour
- If the location is within 100 m of XERRA data, the closest panoramic image is loaded.
- If no data is within 100 m, XERRA opens the map view centred on the given coordinates.
Example
https://xerra.agonics.com/api?action=flyToLidarLocation&lat=-37.820413&lon=145.131141
With SSO authentication
https://xerra.agonics.com/api?mode=sso&ssoDomain=example.com.au&action=flyToLidarLocation&lat=-37.820413&lon=145.131141
Navigate XERRA to a specific profile. Profile IDs are typically obtained from exported XERRA reports.
| Parameter | Type | Description |
|---|
action | "flyToProfile" | Action identifier. |
profileId | string | The profile database key (DbKey<Profile>). |
Example
https://xerra.agonics.com/api?action=flyToProfile&profileId=abc123
Integration Examples
HTML link
<a href="https://xerra.agonics.com/api?action=flyToLidarLocation&lat=-37.820413&lon=145.131141">
Open in XERRA
</a>
Navigate current page
const lat = "-37.820413";
const lon = "145.131141";
window.location.href =
"https://xerra.agonics.com/api"
+ "?action=flyToLidarLocation"
+ "&lat=" + lat
+ "&lon=" + lon;
Open in new tab
window.open(
"https://xerra.agonics.com/api"
+ "?action=flyToLidarLocation"
+ "&lat=" + lat
+ "&lon=" + lon,
"_blank"
);
Reusable window
If the XERRA window is left open, using the same window name will reuse it for subsequent calls rather than opening a new tab each time.
// Using a named window reuses the same tab
window.open(
"https://xerra.agonics.com/api"
+ "?action=flyToLidarLocation"
+ "&lat=" + lat
+ "&lon=" + lon,
"xerra-viewer"
);
URL Builder
Construct a XERRA API URL interactively.
Generated URL