AerialSphere XPGEO REST API

The XPGEO REST API automatically loads images, processes them into an Oriented Imagery (OI) layer, and outputs the OI layer to the Esri Enterprise user's content.

See here for documentation on our reference client, written in Python, that consumes this REST API.

See here for how to set up an API key within your ESRI Enterprise server.

Authentication

The API supports two primary methods for authentication: API Key and Username/Password (Esri ArcGIS Online (AGOL) or Esri Enterprise account credentials).

API Key can be set using the ESRI_API_KEY config option. Set USE_API_KEY_AUTH to true.
Account credentials can be used by setting USERNAME and PASSWORD options in the config.
Accounts will need to be set to either the Creator or above User Type and Publisher or above Role.

If USE_API_KEY_AUTH is true, the username is resolved automatically from the API key. Otherwise, USERNAME and PASSWORD are pulled from the config.

App Health Check

GET /

Description

Basic liveness check. Confirms the Express server is running.

Request Example

GET {REST_URL}/

Response Example

The app is running...

Validate Enterprise Server Credentials

GET /enterprise-server-health-check

Description

Validates that the configured credentials can successfully reach the Esri Enterprise server.

Request Example

GET {REST_URL}/enterprise-server-health-check

Response Example

Validation response: {
  "currentVersion": "CURRENT_VERSION",
  "enterpriseVersion": "ENTERPRISE_VERSION",
  "enterpriseBuild": "BUILD"
}

Create Layer

GET /create-oi-layer

Description

Creates a feature service with an attached OI layer definition, updates the item's OIL keywords, and shares the item with the organization.

Parameters

Parameter	Type	Location	Description

Parameter	Type	Location	Description
`name`	string	query	The name of the feature service. If duplicated, a timestamp will be added.
`imageryType`	string	query	The type of imagery. Defaults to `standard`.

Request Example

GET {REST_URL}/create-oi-layer?name=FEATURE_SERVICE_NAME&imageryType=standard

Response Example

{
  "serviceName": "FEATURE_SERVICE_NAME",
  "serviceItemId": "ITEM_ID",
  "serviceType": "Feature Service",
  "layer": { "name": "FEATURE_SERVICE_NAME", "id": 0 }
}

Append Images

Append a single image

GET /append-image

Description

Adds a single image to an existing Oriented Imagery Layer.

Parameters

Parameter	Type	Location	Description

Parameter	Type	Location	Description
`layerName`	string	query	The name of the feature service that already exists.
`imageUrl`	string	query	URL-encoded path of the image to append.
`itemId`	string	query	The item ID of the feature service. Required if `doUpdateExtent` is set.
`imageryType`	string	query	The type of imagery. Defaults to `standard`.
`doUpdateExtent`	boolean	query	Whether to update the layer extent after appending. Requires `itemId`.

Request Example

GET {REST_URL}/append-image?layerName=FEATURE_SERVICE_NAME&imageUrl=URL_ENCODED_URL_PATH

Response Example

response: true

Error Codes

Code	Description

Code	Description
400	Missing layer name or image URL
400	Item ID is required when updating the extent
422	Malformed image URL string

Append an image list

POST /append-image-list

Description

Adds a list of images to an existing Oriented Imagery Layer.

Parameters

Parameter	Type	Location	Description

Parameter	Type	Location	Description
`layerName`	string	body	The name of the feature service that already exists.
`imageList`	array	body	Array of URL-encoded image paths to append.
`itemId`	string	body	The item ID of the feature service. Required if `doUpdateExtent` is set.
`imageryType`	string	body	The type of imagery. Defaults to `standard`.
`doUpdateExtent`	boolean	body	Whether to update the layer extent after appending. Requires `itemId`.

Request Example

POST {REST_URL}/append-image-list

{
  "layerName": "FEATURE_SERVICE_NAME",
  "imageList": [
    "URL_ENCODED_URL_PATH"
  ],
  "imageryType": "standard",
  "itemId": "ITEM_ID",
  "doUpdateExtent": false
}

Response Example

true

Error Codes

Code	Description

Code	Description
400	Missing JSON body
400	Missing layer name or image list
400	Item ID is required when updating the extent
422	Malformed image URL string in the list
422	Image list is either not an array or exceeds maximum size. Maximum size is set using the `MAX_IMG_LIST_SIZE` config option.

Configuration Options

Option	Description

Option	Description
`PORT`	The port the server listens on (bound to `localhost` only).
`USE_API_KEY_AUTH`	Set to `true` to use API key authentication.
`ESRI_API_KEY`	The Esri API key for authentication.
`USERNAME`	Esri account username (used when `USE_API_KEY_AUTH` is `false`).
`PASSWORD`	Esri account password (used when `USE_API_KEY_AUTH` is `false`).
`MAX_IMG_LIST_SIZE`	Maximum number of images allowed in a single `/append-image-list` request.

XPGEO API (Beta)

AerialSphere XPGEO REST API

Authentication

App Health Check

Validate Enterprise Server Credentials

Create Layer

Append Images

Append a single image

Append an image list

Configuration Options