> For the complete documentation index, see [llms.txt](https://geotag.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://geotag.gitbook.io/api/geotag-api-documentation.md).

# GeoTag API Documentation

### 🔐 Signature and Common Parameters

#### 📌 Data Encryption Transmission and Signature Mechanism

* Enterprises generate their own public/private key pairs and provide the **public key** to the platform.
* The platform generates a public/private key pair for the enterprise and provides the **public key** to the enterprise.
* When an enterprise requests data, it signs the data using its own **private key** and encrypts the data using the **public key** provided by the system.
* Upon receiving data, the platform verifies the signature using the enterprise's **public key** and decrypts the data using the system's **private key** to retrieve the plaintext.
* When the platform returns data, it signs the data using the platform's **private key** and encrypts it using the enterprise's **public key**.
* When the enterprise receives the returned data, it verifies the signature using the platform's **public key** and decrypts the data using its own **private key**.

#### 🔐 Encryption Rules

* Construct business parameters as JSON.\
  **Example:**

  ```
  {
      "page": 1,
      "pageSize": 10,
      "status": 1
  }
  ```
* Randomly generate an `AesKey`.
* Encrypt the original JSON string of parameters using the generated `AesKey`. If the original parameters are empty, use `{}` (`encryptedData`).
* Encrypt the `AesKey` using the public key (`encryptedAesKey`).
* Finally, compose the `data` field as: `encryptedData + "," + encryptedAesKey`.

#### 🔓 Decryption Rules

* Upon receiving `data`, split it into two parts using the comma `,`.
* The first part is `encryptedData`, and the second part is `encryptedAesKey`.
* First, decrypt `encryptedAesKey` using the private key to obtain the `aesKey`.
* Then, decrypt `encryptedData` using the `aesKey`.
* The final result is the plaintext JSON data.

#### 📌 Signature Rules

* Append the `timestamp` to the processed `data` (i.e., `encryptedData + "," + encryptedAesKey`).
* Sign the resulting string using the private key.

**Encrypted Data Example:**

```
{
    "businessNo": "B197458838294",
    "data": "p/SPhan0ix6ltS7XNjpQKRkU0iMEd5jrBb8m/0FHnmbu8zdU8raGsLxTOhxxjrAT,aX3Ne0ewKW8pdqsExBZMJcPvPTjoS9brFM4HL/TaM+TTGVvOeMO586lEHW+UErzFioEvaAEYp3jw5KU580j34xIgeY1F0z+D3FuNyn/PpoQJu6V6j5vIkATe40Dz3S384dhl61lKpZc94WVDxw33bFaaM23LPL+AfgV7m5PNHUvqVfQ4WlDOQ09LNY+AHwx5/wZfJaTx9kc0z5TNPUYZdYtZArJ/fr0XAJiIPRPfFLNE/ZF+kMuBxEOpoKYkeWpQngKS/oXveM+c+6MJS24Y8ClcX0JIxS3tN054MH+c+sf/DG+4jvk36O6d7UXqMZLMF+NRYStMpESjbXnbOXxEpA==",
    "sign": "SHo/wMcj6cZmGjxa/ZTmSOHk5TGKCNE1A/99ZFCYM3ZheK4O+tg41YIIosQoyAi7s3EH8d71Py7OlMAM4DEJgbFBMOouw0nGsc2tMVQRNbAe2DihFt4ixD/y+eZldZlRotpRSbGHGfBeLnQx/7zGKbdK/v7ouuQJKbSCNPSMjdKNy5w3sMQVNTmWLSanfv91d1EMDn0ynwughZYYqyjEe78Dyn/ZgfN19Lg32xN+1h8owmI/wJvwICo5hT3AcesL2DtRFDtHDVQPvZp0Lw0E5pox9Lj385q9Ohy+v40q4o5iwP3VasAiz2TEywQKW46/raQnelPRUz+AiseDRuYTFg==",
    "timestamp": 1773043271220
}
```

***

### 🔗 API Interface Description

#### 📌 Get Device List

> **Request Method:** POST\
> **Endpoint:** `/device/getList`\
> **Content-Type:** `application/json`

* **Request Parameters:**

| Parameter  | Type | Required | Description                                                          |
| ---------- | ---- | -------- | -------------------------------------------------------------------- |
| `page`     | int  | No       | Current page number, default is 1                                    |
| `pageSize` | int  | No       | Page size, default is 20                                             |
| `sortNum`  | int  | No       | Sorting: 1 = ascending by time, 2 = descending by time, default is 1 |
| `status`   | int  | No       | Enable status: 0 = disabled, 1 = enabled                             |

* **Pre-encryption Request Data:**

```
{
    "page": 1,
    "pageSize": 10,
    "status": 1
}
```

* **Post-encryption Request Data:**

```
{
    "businessNo": "B197458838294",
    "data": "SUIP+9pc+qhEMtXg5FzH/E0AVbjsmg8b6+js/UxMrxpPFCPakFIqdEKUhoCATnsd,MxpweoRlyGz6vaEApcFT46WdhTr7GJH1fRVpAn4k6u1QJ1kkfuDWchE2QTph0ERD5AERMhwGw0jhS+YHwao6GOUYyZTlDUByM2JQXasu5fhhmB0u+4UsPpDePjBe1e22JCbFmHJqVpCHmAZ6/02lrvfpnViufyO2J9Lj2wC5HLtVhKMOessBKtMW3QUprkLrUV/dB05h/IcZb2WW0iGAtFa1FL0B62QNk9EUB7oF1v563FD/y9tW06bB3j/qbiDlFoCf2rGQ6lHWH4ipkmrNCHwWqT0NRhkq65dO7J7PFMEa0c3TIaKjM+x+jJbuu99JOMNu+ISM0srQfWSKdH1PCg==",
    "sign": "7HFEPDf/skNj9xrggF4WrZX12wko6HRa67/WaCWEm5ZxwgvxdQU/P4282CzcGyIXf6UakiuhgF3z4g1HpBtNGam4exO3al08Q8Z6ddyHSQmnlnxaXbKUQSY2i9+8Wu6SEAkfD7dBZyGr6H+BwgNq9eGuO4l4zDlKXpJjklSU2Er3a6YffFTsFTKcHiSLswsir6pW33mxoDWcrwZU8Yg1ZJXSVxeUC5jceTKp8VHrpSBSV0IMFW1vofZHSxBzYSI1Q3FBO5M/jJs+q1YiH4XHEgV5axGdIgbgTltpRgFVmxymJsfLZId/x7Bjco/GKPR6Nrx/uI1wbjY6XckUjd8y5g==",
    "timestamp": 1773056221220
}
```

* **Response `data` Parameters:**

| Parameter  | Type   | Description                              |
| ---------- | ------ | ---------------------------------------- |
| `page`     | int    | Current page number, default is 1        |
| `pageSize` | int    | Page size, default is 20                 |
| `total`    | int    | Total number of records                  |
| `status`   | int    | Enable status: 0 = disabled, 1 = enabled |
| `list`     | array  | List of devices                          |
| `> sn`     | string | Device serial number                     |
| `> mac`    | string | MAC address                              |
| `> status` | int    | Enable status: 0 = disabled, 1 = enabled |
| `> uuid`   | string | Device unique code                       |

* **Encrypted Response:**

```
{
    "msg": "success",
    "code": 200,
    "data": "isfDTIPcLS6dmUorCUk9+bACW6nKa5RbqN6YgVAfqi6Cf8WVnGNCwzZtqFjIDztRDHDgzU/WEVwxLlDuKNYYolQAYW/1YHXoh6tPjBMaHVZl/FTtx3gyvyDRYyyIg5jvo8Ywc32fyOmNZj+J2HZ5Qg==,0tVDo4Gleqnr87AHEzo0YxA3lHzZx852atGiXQgfXFVA+Wc9oKnq3rAPJXcG/o/V9mmbtSjgdSsGBrsLQgXPUqa2ANR5FaDsuIGknGhvdfQxP57f3xltJYqvz8RvZk1KMKLbqC02kyQgg/y/raDyOmQ869rYnImRGYfn2Fs/56km4fn3vUnUV8OXP4M0Pvd6dmWWKrOOEiBI/CPBz8bC+lcEGmhUdPi3nbaF1Wa3Dr0SFeuuENxzafM7Nik4YNNOiYwwyzQ6WQcZ7jGZOOv9swXYcBzx+RkOtnbGFGVarRiJawrEItefRFAAb3H9CqmByv+ii/m8Yu+oumR5UHePEg==",
    "sign": "IpoOmwZtC1OnleL6jbHSNfrtTNecgov8Ql/BMy9+wzkOJuk888w9a0+ASBi8autmrGNMLMKEvYULDXKdakLRRjSACpSAUx91f0mbkHSlwDWDkQ2PXlF3K/RGfdSdNpP+5J3/qMs71SNONGVznACG13PT6dKZk89MmzbQkT8yDD8BwxZNFXcsFB/UsJuZ9/YEv8XOGYVVWlt8/oU3JLttr7c8N/nIxXJ/z6yD7d1djOxAkOy6d6ljLg6mMcBSKS2InpuewgzhF5dR6khL9IVupjfbRiI3krQGm0v86ZoZPEnH5Za6O6uVR2UwQfEp7wgQjzSfltVkzr1bl3o9ZYVh+g==",
    "timestamp": 1773059201220
}
```

* **Decrypted Response:**

```
{
    "list": [
        {
            "mac": "E8:C8:4F:76:C3:38",
            "sn": "GeoTag-EQLRIDQK",
            "uuid": "e03041c82cd7f55ac2c5f76df7ffbe32",
            "status": 0
        }
    ],
    "page": 1,
    "pageSize": 10,
    "total": 1
}
```

***

#### 📌 Get Device Historical Trajectory

> **Request Method:** POST\
> **Endpoint:** `/device/getHistory`\
> **Content-Type:** `application/json`

* **Request Parameters:**

| Parameter  | Type   | Required | Description                                                                                           |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `page`     | int    | No       | Current page number, default is 1                                                                     |
| `pageSize` | int    | No       | Page size, default is 20                                                                              |
| `sn`       | string | No       | Device serial number(s). Use commas (,) to separate multiple device serial numbers. Example: sn1,sn2. |

* **Pre-encryption Request Data:**

```
{
    "page": 1,
    "pageSize": 10,
    "sn": "GeoTag-EQLRIDQK"
}
```

* **Response `data` Parameters:**

| Parameter         | Type   | Description          |
| ----------------- | ------ | -------------------- |
| `page`            | int    | Current page number  |
| `pageSize`        | int    | Page size            |
| `total`           | int    | Total records        |
| `list`            | array  | Trajectory list      |
| `> sn`            | string | Device serial number |
| `> address`       | string | Address              |
| `> lat`           | double | Latitude             |
| `> lng`           | double | Longitude            |
| `> battery`       | long   | Battery level        |
| `> reportedTime`  | long   | Reporting time       |
| `> locationTime`  | long   | Location time        |
| `> accuracy`      | string | Accuracy range       |
| `> confidence`    | string | Confidence level     |
| `> batteryStatus` | string | Battery status       |

* **Decrypted Response:**

```
{
    "list": [
        {
            "sn": "geotag-ioi",
            "address": "....",
            "accuracy": "39",
            "battery": 100,
            "batteryStatus": "ok",
            "confidence": "19",
            "lat": 22.789893,
            "lng": 115.802679,
            "locationTime": 1773060529000,
            "reportedTime": 1773060519000
        }
    ],
    "page": 1,
    "pageSize": 10,
    "total": 1
}
```

***

#### 📌 Get webhook records of failed push notifications (supports up to 7 days of data)

> **Request Method:** POST\
> **Endpoint:** `/device/getWebHookFail`\
> **Content-Type:** `application/json`

* **Request Parameters:**

| Parameter   | Type   | Required | Description                                                                                           |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `page`      | int    | No       | Current page number, default is 1                                                                     |
| `pageSize`  | int    | No       | Page size, default is 20                                                                              |
| `sn`        | string | No       | Device serial number(s). Use commas (,) to separate multiple device serial numbers. Example: sn1,sn2. |
| `beginTime` | long   | No       | Begin time (millisecond timestamp)                                                                    |
| `endTime`   | long   | No       | End time (millisecond timestamp)                                                                      |

* **Pre-encryption Request Data:**

```
{
    "page": 1,
    "pageSize": 10,
    "sn": "GeoTag-EQLRIDQK",
    "beginTime": 1782081060000, 
    "endTime": 1782127860000
}
```

* **Response `data` Parameters:**

| Parameter         | Type   | Description          |
| ----------------- | ------ | -------------------- |
| `page`            | int    | Current page number  |
| `pageSize`        | int    | Page size            |
| `total`           | int    | Total records        |
| `list`            | array  | Trajectory list      |
| `> sn`            | string | Device serial number |
| `> address`       | string | Address              |
| `> lat`           | double | Latitude             |
| `> lng`           | double | Longitude            |
| `> battery`       | long   | Battery level        |
| `> reportedTime`  | long   | Reporting time       |
| `> locationTime`  | long   | Location time        |
| `> accuracy`      | string | Accuracy range       |
| `> confidence`    | string | Confidence level     |
| `> batteryStatus` | string | Battery status       |

* **Decrypted Response:**

```
{
    "list": [
        {
            "sn": "geotag-ioi",
            "address": "....",
            "accuracy": "39",
            "battery": 100,
            "batteryStatus": "ok",
            "confidence": "19",
            "lat": 22.789893,
            "lng": 115.802679,
            "locationTime": 1773060529000,
            "reportedTime": 1773060519000
        }
    ],
    "page": 1,
    "pageSize": 10,
    "total": 1
}
```

#### 📌 Update Device Status

> **Request Method:** POST\
> **Endpoint:** `/device/updateStatus`\
> **Content-Type:** `application/json`

* **Request Parameters:**

| Parameter | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| `status`  | int    | Yes      | Enable status: 0 = disabled, 1 = enabled |
| `sn`      | string | Yes      | Device serial number                     |

* **Pre-encryption Request Data:**

```
{
    "sn": "GeoTag-EQLRIDQK",
    "status": 1
}
```

* **Decrypted Response:**

```
{
    "mac": "E8:C8:4F:76:C3:38",
    "sn": "GeoTag-EQLRIDQK",
    "status": 0
}
```

***

## #webhook

Once a webhook URL is configured, location updates from the company's devices will be pushed to the webhook endpoint in real time.

* **Webhook `data` Parameters:**

| Parameter       | Type   | Description          |
| --------------- | ------ | -------------------- |
| `sn`            | string | Device serial number |
| `lat`           | double | Latitude             |
| `lng`           | double | Longitude            |
| `battery`       | long   | Battery level        |
| `reportedTime`  | long   | Reporting time       |
| `locationTime`  | long   | Location time        |
| `accuracy`      | string | Accuracy range       |
| `confidence`    | string | Confidence level     |
| `batteryStatus` | string | Battery status       |

* **Decrypted Response:**

```
{
    "sn": "geotag-ioi",
    "accuracy": "39",
    "battery": 100,
    "batteryStatus": "ok",
    "confidence": "19",
    "lat": 22.789893,
    "lng": 115.802679,
    "locationTime": 1773060529000,
    "reportedTime": 1773060519000
}
```

***

### SDK

#### ⏬ [JAVA SDK Download](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Frj1oeSOmouAR9NBjdyri%2Fuploads%2Fd3jt1nJk4Ug14GIGEQM4%2Fgentag-sdk.jar.zip?alt=media\&token=aa6f2948-9cfd-4a46-908c-40dfd8b0479b)

{% file src="/files/gwXHRLTOjmQEiAlauJpH" %}