/
XPGEO REST API - Reference Client

XPGEO REST API - Reference Client

This Document

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.

This document covers our example reference implementation, written in Python, which can be freely copied and modified to meet your particular scenario.

Authentication

The API supports two primary methods for authentication: API Key and Username/Password.

  • API Key can be set using the CLIENT_ESRI_API_KEY config option. This key is passed to the server. We recommend using a key.

  • Account credentials can be used by setting USERNAME and PASSWORD options in the config. When you do this, the client doesn’t handle auth. Instead, the server pulls these values and uses them at runtime. If CLIENT_ESRI_API_KEY is used, then the client passes this to the server, and the server doesn’t attempt its own auth, so these values are ignored.

  • Accounts will need to be set to either the Creator or above User Type and Publisher or above Role.

App Health Check

health-check

Description

Basic liveness check. Confirms the Express server is running.

CLI Example

python xpgeo-client.py health-check

Response Example

XPGEO REST response: The app is running... Health check response: Validation response: {"currentVersion":"2025.1","enterpriseVersion":"11.5.0","enterpriseBuild":"56755"}

Create a new Oriented Imagery (OI) Layer

create-oi-layer --name=<layer_name>

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

Description

Parameter

Type

Description

name

string

The name of the feature service. If duplicated, a timestamp will be added.

CLI Example

python xpgeo-client.py create-oi-layer --name=demo_20260406

Response Example

Starting layer creation for 'demo_20260406'... Create layer response: {"serviceName":"demo_20260406","serviceItemId":"3e17c77a6e97487198b25f8c9697b9c3","serviceType":"Feature Service","layer":{"name":"demo_20260406","id":0}}

Append Images

Append a single image

append-image --name=<layer_name> --image-url=<image_url>

Description

Adds a single image to an existing Oriented Imagery Layer.

Parameters

Parameter

Type

Description

Parameter

Type

Description

layerName

string

The name of the feature service that already exists.

imageUrl

string

URL-encoded path of the image to append.

Request Example

python xpgeo-client.py append-image --name=demo_20260406 --image-url=https://aerialsphere-external-entity-files.s3.us-west-2.amazonaws.com/oic-wizard-testing/IMG_2938.jpg

Response Example

Append image response: 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

append-images --name=<layer_name> --file=<file_path>

Description

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

Parameters

Parameter

Type

Description

Parameter

Type

Description

layerName

string

The name of the feature service that already exists.

file

file(string)

The location of a local file. This file should contain a list of URLs that point to the images you plan to attach to the OI layer.

Request Example

python xpgeo-client.py append-images --name=demo_20260406 --file=../test-files/iphone.txt

Response Example

Appending images from ../test-files/iphone.txt to layer demo_20260406... Reading image URLs from file... File location: ../test-files/iphone.txt Append images response: 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

CLIENT_ESRI_API_KEY

The Esri API key for authentication.

IGNORE_SSL_VALIDATION

If you don’t want to enforce SSL validation between your client and server, then set this to true. The default (and recommended) value is false, but this flag accommodates some ESRI Enterprise Server setups.