Table of Contents

Introduction to Sparse Spatial Map management APIs

API overview

REST API protocol and authentication mechanism

Spatial Map API follows the standard HTTP REST transport specification.

Http Header

    Authorization:

HTTP request parameters are divided into two types:

  • Public parameters (all of these are included; they are used differently depending on the authentication method):

    • appId
    • timestamp (Long integer: milliseconds elapsed since 00:00:00 UTC on January 1, 1970)
    • apiKey
    • signature (request signature, choose one of token authentication or signature authentication)

  • Spatial Map API parameters: the API's own parameters

    The API documentation no longer describes the public parameters used for authentication

API Key authentication

There are two authentication methods.

Token-based authentication

The Http header Authorization contains the Token, and the public parameters include:

  • appId

Signature authentication

Do not use the Http header Authorization.

The request parameters contain signature information. All parameters are included in the signature calculation (except the image).

  • appId
  • timestamp
  • apiKey
  • signature

For the detailed algorithm of signature calculation, please refer to API Key signature method.

Usage examples and property interpretation

API usage example

The following example uses an API call to query Spatial Map data to help developers understand the Spatial Map API and the spatial map structure.

Request example

  GET /maps HTTP/1.1
  Host:
  Date: Mon, 1 Jan 2018 00:00:00 GMT
  Content-Type: application/json
  {
      "timestamp": 1769406019000,
      "apiKey": "8b485c648c3056e79c2a85ee9b...",
      "appId": "C:NA1:6fc8fe27af4a4d6cb02f4b494d2a9..",
      "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
  }

Response example

 {
  "result": {
    "armaps": [
      {
        "mapId": "62d4f765-cc54-4dff-9c48-b7c8b4adbde9",
        "gps": "[0.0, 0.0]",
        "name": "Map_2020-09-28_1302",
        "size": 124140,
        "status": "active",
        "auxiliaryId": "62d4f765-cc54-4dff-9c48-b7c8b4adbde9",
        "created": 1601245841687,
        "modified": 1601245841687,
        "mapVersion": "esm1",
        "mapUrl": "https://prod-armap-1348728941.cos.na-siliconvalley...",
        "previewUrl": "https://prod-armap-1348728941.cos.na-siliconvalley...",
        "appKey": "C:NA1:6fc8fe27af4a4d6cb02f4b494d2a9f.."
      },
      {
        "mapId": "5ccdf1fb-0cd3-4580-80aa-42bd2289...",
        "gps": "[0.0, 0.0]",
        "name": "test",
        "size": 2419184,
        "status": "active",
        "auxiliaryId": "5ccdf1fb-0cd3-4580-80aa-42bd22897b...",
        "floor": "1",
        "tag": "cat",
        "created": 1601244090670,
        "modified": 1601244090670,
        "mapVersion": "esm1",
        "mapUrl": "https://prod-armap-1348728941.cos.na-siliconvalley....",
        "previewUrl": "https://prod-armap-1348728941.cos.na-siliconvalley...."
      }
    ],
    "page": {
      "total": 2,
      "pageNum": 1,
      "pageSize": 10,
      "pages": 1
    }
  },
  "statusCode": 0,
  "msg": "Success",
  "timestamp": 1769406021019
}

Sparse map properties

As shown in the example above, this is the normal returned Spatial Map structure

Property Description
mapId Unique map Id
name Map name
size Map file size
meta User-associated data, which can be a file, text, or url, and needs to be base64 encoded
status Whether it is disabled, values are [active inactive]
tag Custom tag for easy retrieval
floor Floor for easy retrieval
gps Geographical location of the space, wgs84 coordinate system, or a self-defined coordinate system
previewUrl Preview image download

Error codes