How to use the API interface?

GISBox supports the use of API interfaces. After opening GISBox, we can select the “API” in the left toolbar, and then click the “Create AccessKey” button in the upper right corner to add the API interface. “AccessKey ID” and “AccessKey Secret” are used as Auth parameters to verify the user identity or the legitimacy of the application. Click to view the corresponding tutorial → Auth parameters.

“AccessKey Name” refers to the key name used to transmit specific information. It usually appears in request parameters, HTTP headers or response data. When we add a new key, we need to fill in the corresponding “AccessKey Name”, as shown in the following figure:

In the operation on the right, we can change the “AccessKey Name”, as shown below:

[Tips] The API function of GSIBox requires the Enterprise Plan to use. If you need to use it, please contact GISBox official customer service.

1. Base URL

The base URL for all API requests is:

1	Primary account SaaS access address + /api/v1

The “Primary account SaaS access address” can be viewed in the GISBox software under “Settings” → “Network”, as shown below:

For example, suppose the primary account SaaS access address is:

1	http://192.168.31.122:42225

Then the base URL of the API interface is:

1	http://192.168.31.122:42225/api/v1

2. Auth Parameters

To ensure the security of interface access, each interface request needs to be spliced with the following parameters for verification, including “AccessKey ID” and “AccessKey Secret”:

Name	Type	Required	Description
key	string	Yes	Generated key
timestamp	string	Yes	Current timestamp
sign	string	Yes	Use md5 to encrypt the string concatenated with (key, secret, timestamp) to generate a string

Here is an example:

1	http://192.168.31.122:42225/api/v1/task/list?key=06150cad-131c-4a13-88cf-90b7c4e76056&timestamp=1736835697953&sign=1D1802A6A4BB9C8A603F696E1E0E3644

3. Response Format

The response data of the API interface follows a unified format and contains the following fields:

Name	Type	Required	Description
success	boolean	Yes	Success status
msg	string	Yes	Success prompt or error description
data	object	No	Respond to core data

4. Interface Description

4.1 Query Task Information (GET)

Interface address:

1	GET task/<id>/info

4.1.1 Request Parameters

Name	Type	Required	Description
id	string	Yes	task id

4.1.2 Response Parameter Types

4.1.3 Response Example

Request successful:

{
  "success": true,
  "data": {
    "id": "ngcxb8xzf41x",
    "name": "My osgb model",
    "status": "failed",
    "type": "GeneralModelSlicing",
    "inputPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\6349b52ac052f1100a0099f56ae1360d",
    "outputPath": "C:\\Users\\admin\\Desktop\\rubbish\\scene",
    "settings": {
      "fileRange": [2, 20],
      "sceneTree": true,
      "is3DTiles1_1": true,
      "enableLOD": true,
      "textureCompressionFormat": "webp",
      "vertexCompress": false,
      "vertexCompressionLevel": 5,
      "x": 120.14757537841797,
      "y": 30.274856567382812,
      "z": 0,
      "name": "city model",
      "imageRatio": 0.5
    },
    "startTime": 1736838996442,
    "endTime": 1736841982291
  },
  "msg": "Request successful"
}

Request failed:

{
  "success": false,
  "msg": "Task not found"
}

4.2 Query Task List (GET)

Interface address:

1	GET task/list

4.2.1 Request Parameters

None

4.2.2 Response Parameter Types

An array containing all task information. For specific fields of the task information object, refer to the task information query interface.

4.2.3 Response Example

Request successful:

{
  "success": true,
  "data": [
    {
      "id": "ngcxb8xzf41x",
      "name": "My osgb model",
      "status": "running",
      "type": "GeneralModelSlicing",
      "inputPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\6349b52ac052f1100a0099f56ae1360d",
      "outputPath": "C:\\Users\\admin\\Desktop\\rubbish\\scene",
      "settings": {
        "fileRange": [2, 20],
        "sceneTree": true,
        "is3DTiles1_1": true,
        "enableLOD": true,
        "textureCompressionFormat": "webp",
        "vertexCompress": false,
        "vertexCompressionLevel": 5,
        "x": 120.14757537841797,
        "y": 30.274856567382812,
        "z": 0,
        "name": "City model",
        "imageRatio": 0.5
      },
      "startTime": 1736838996442,
      "progress": 0,
      "spentTime": 0,
      "remainTime": 0
    },
    {
      "id": "xoeqj7jrw9fl",
      "name": "My osgb model",
      "status": "finished",
      "type": "GeneralModelSlicing",
      "inputPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\c8f9e1d5c211b16dc34c5181922dc911",
      "outputPath": "C:\\Users\\admin\\Desktop\\rubbish\\new folfer(2)",
      "settings": {
        "fileRange": [2, 20],
        "sceneTree": true,
        "is3DTiles1_1": true,
        "enableLOD": true,
        "textureCompressionFormat": "webp",
        "vertexCompress": false,
        "vertexCompressionLevel": 5,
        "x": 120.19058749999999,
        "y": 30.280553849999997,
        "z": 0,
        "name": "City model",
        "imageRatio": 0.5
      },
      "startTime": 1736838648314,
      "endTime": 1736838670124
    }
  ],
  "msg": "Request successful"
}

Request failed:

{
  "success": false,
  "msg": "Invalid signature"
}

4.3 Create a New Task (POST)

Interface address:

1	POST /task/create

4.3.1 Request Parameters

Body Type:

1	application/json

The settings parameters for different conversion types are different. The following are introduced respectively:

(1) Imagery Tiling

Name	Type	Required	Description	Default
tileSize	integer	No	Tile size	256
minZoom	integer	No	Minimum level	0
maxZoom	integer	Yes	Maximum level	-
toSrs	integer	Yes	Projection parameters (3857 or 4326)	-
service	string	Yes	Service type (TMS or WMTS)	-
fromSrs	string	No	Spatial reference system	-
background	string	No	Background transparency (“auto” or “255,255,255”)	“auto”
colorStretching	object	No	Color stretching settings	-
type	string	Yes	Type (“deviationAndZoom”, “theMostValuable”, or “percent”)	-
deviation	number	No	Deviation (only for “deviationAndZoom” type)	-
zoom	number	No	Zoom factor (only for “deviationAndZoom” type)	-
min	number	No	Minimum value (only for ”theMostValuable” type)	-
max	number	No	Maximum value (only for ”theMostValuable” type)	-
minPercent	number	No	Lower threshold (%) (only for “percent” type)	-
maxPercent	number	No	Upper threshold (%) (only for “percent” type)	-

(2) Terrain Tiling

None

(3) OSGB to 3DTiles

(4) 3DTiles to OSGB

| Name | Type | Required | Description |
| :——: | :—–: | :——: | ———————- | ——- |
| srs | string | No | Spatial reference |
| srsOrgin | string | No | Zero point coordinates |
| upAxis | “Z” | “Y” | No | Up axis |

(5) Point Cloud Tiling

4.3.2 Response Parameter Type

Name	Type	Required	Description	Name	Type
id	string	true	none		none

4.3.3 Response Example

Request successful:

{
  "success": true,
  "data": {
    "id": "m2iz285xzzlj"
  },
  "msg": "Request successful"
}

Request failed:

{
  "success": false,
  "msg": "Invalid task type"
}

4.4 Start Task (POST)

Interface address:

1	POST /task/<id>/start

4.4.1 Request Parameters

Name	Type	Required	Description
id	string	Yes	Task id

4.4.2 Response Parameter Types

Name	Type	Required	Description
id	string	true	Task id

4.4.3 Response Example

Request successful:

{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "Request successful"
}

Request failed:

{
  "success": false,
  "msg": "Task is running"
}

4.5 End task (POST)

Interface address:

1	POST /task/<id>/stop

4.5.1 Request Parameters

Name	Type	Required	Description
id	string	Yes	Task id

4.5.2 Response Parameter Types

Name	Type	Required	Restriction	Description
id	string	true	none	none

4.5.3 Response Example

Request successful:

{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "Request successful"
}

Request failed:

{
  "success": false,
  "msg": "Task is not running"
}

4.6 Delete Task (POST)

Interface address:

1	POST /task/<id>/delete

4.6.1 Request Parameters

Name	Type	Required	Description
id	string	Yes	Task id

4.6.2 Response Parameter Types

Name	Type	Required	Restriction	Description
id	string	true	none	none

4.6.3 Response Example

Request successful:

{
  "success": true,
  "data": {
    "id": "4gtfbeg794p7"
  },
  "msg": "Request successful"
}

Request failed:

{
  "success": false,
  "msg": "Task is not running"
}