API Manual

Terraqt Restful API

Version Information

Version : 1.0
Published: Jan 25th, 2022
Last Updated: Feb 25th, 2022

Interface Introduction

Introduction

TerraQuanta provides a convenient interface calling service, which can help users quickly embed TerraQuanta’s data products into existing map applications, achieving a strong fusion of spatio-temporal data products and user applications.
Our interface meets users’ demand to develop front-end component, allowing further development and implementation.

Why API?

Access methods TerraQuanta provides include SaaS, SDK, and API. User can choose the most appropriate method as needed. The differences are shown in the chart below. If you wish for a more flexible frond-end component development, API is recommended! | | Description | Characteristics | Development Difficulties | Map Display Flexibility | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------- | | SaaS | No need for installation, debugging, or training, TerraQuanta’s standardized spatiotemporal data SaaS service helps spatiotemporal data users to view various data products and use various functions designed by us through a simple login. TerraQuanta SaaS User’s Manual | Simply log in and use through our website, no need for further development. | None | Low | | SDK | TerraQuanta provides users and developers who have limited experience in map application development with a complete front end spatio-temporal data product SDK component. This component is designed based on the low code concept, and it can embed the spatiotemporal data front end display module designed by TerraQuanta into other application interfaces without a trace, and can open or hide various functions freely.[JS-SDK Access Manual](/docs/基础概念/SDK嵌入服务) | Simply copy 7 lines of code to access. An experienced front-end engineer can realize this within 10 minutes. | Low | Medium | | API | TerraQuanta provides standardized map layer tiling services for users and developers with experience in map application development. Our service help users quickly access our layer data and achieve a strong fusion of patio-temporal data products and user applications | Flexible front-end map component development, easy access of WMTS layer, and strong rendering effects | Medium | High |

Basic Standards

Transfer Method: HTTP
Submit: POST or GET
Data Format: Json for both submission and return data
Return data basic structure:
- Structure of interface return data includes 5 parameters | Parameter Name | Data Type | Description | | -------------- | ----------------------------------------- | ----------------------------------------------------------------- | | code | `int` | Return status code | | success | `boolean` | Return result: true = success, false = failed | | msg | `string` | Error messages | | retry | `boolean` | Retry? True/false | | data | object | Business data. Please refer to description of returned paragraphs |

Major Concepts

Service (serviceId)：
- TerraQuanta packages different spatio-temporal data products that users require into one single service
- Each service contains key information such as product types, data time, and data spatial range
- *All service data tied to the TerraQuanta SaaS account can be accessed by users. , Log in to see the list of services.
- As shown above, the service “Land Usage Monitoring - Inner Mongolia Case” displays data products of land usage.
Data Product (tqDsCode)：Data product selector components
- TerraQuanta provides a variety of spatio-temporal data products, including crop identification, forest identification, crop growth monitoring, water quality indices, subsidence monitoring, flood monitoring, etc.
- Data products has three categories: Core (cor), Derivatives (der), and Events (eve)
- Each data product has a unique code (tqDsCode), which can be used to search and acquire data of that product
Spacial Scale (spaceKey)：Space selection module
- Different data products correspond to different spacial scales
- Users can search data products of certain scales with spaceKey.
- TerraQuanta provides two sets of spacial scales, administrative space and customized space。
- Administrative Space (adminSpace):
  - Space divided according to Provinces/States, Cities, Counties based on national regulations
- Customized Space (customSpace):
  - Space divided according to demand, such as the space of a farm or a reservoir.
Data Timeline (timeLine)：Timeline module
- The time attribute of the spatio-temporal data. For example, identifying a forest on the first day of every month results in twelve identification data in a year.
- Data Update Frequency:
  - Different data products has different update frequency, which could be once a month or several times a month
  - In order to obtain the newest data timely, please check the update frequency of the data product before development
WMTS Layer (dataFile)：WMTS Layer Rendering
- WMTS layer is the layer-URL based spatio-temporal data results provided by TerraQuanta. The layers can be displayed in map applications with the WMTS layer link.
- WMTS layer needs to be overlaid on a satellite imagery map or a vector map as demand. As shown above, the base map TerraQuanta chooses is from Tianditu.
- For a detailed introduction of WMTS layer services, please check WMTS Layer Service
- Layer has data types of vector and raster. Read What is Raster and Vector Data for specifications.
Statistics (databox)：Statistical data display module
- Statistics of related data products are returned along with the acquired layer, and users can develop data visualization with ways that they prefer.

Interface Manual

Follow the steps below to access our interface！

Preparation Work

Obtain account token and service ID

Steps:

Register and log into TerraQuanta Spatio-temporal SaaS Platform
Switch to access manual by clicking the top left button to check your account token ( token ) and the service ID ( serviceId ）of the selected service. The account token and service id are needed to acquire service data later on.

/img/sdk1.png

/img/sdk2.png

Obtain Identity Verification Information

Interface Description:

Obtain user identification code ( secret ) with account token ( token)
secret is used in identity verification when requesting other interfaces

Request URL:

https://openapi.terraqt.com/terraqt/user/open-api/permanent-secret/generate

Request Method:

POST

Host：<calculated when request is sent>

Parameter:

Parameter Name	Required?	Type	Description
token	Yes	`string`	Account token

Input Example:

{
  "token": "XXXXXXXXXXXXXXXXXXXXXXX"
}

Return Data Body

Parameter	Description
userGuid	User ID, same as token
secret	Identify verification code. Used when requesting other interfaces
description	Description

Return Example

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": {
    "userGuid": "XXXXXXXXXXXXXXXXXXXXXXX",
    "secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "description": null
  }
}

Data Interface

Obtain data product and its spacial scale included in the service

Interface Description

Obtain the data product type, map legends, and spatial range information with serviceId
Through the interface, users can acquire code and spatial scale of data products, and ready up for obtaining corresponding data layers in later steps

Request URL:

https://openapi.terraqt.com/version/v1/service-config/get

Request Method:

Header:

Host：<calculated when request is sent>
user-id: User ID, same as token
secret：Identity verification code

Parameter:

Parameter Name	Required?	Type	Description
serviceId	Yes	`string`	Service ID

Input Example

{
  "serviceId": "fe1c2b38-f447-4290-a6d7-8f9ea677e8d3"
}

Return Data Body

Parameter Name	Embedded Parameter	Description
serviceId		Service ID
customSpace		Information of customized space
	cspace_key	Unique ID of customized space
	parent_cspace_key	ID of parent space of the current customized space
	name	Name of Customized Space
adminSpace		Information of administrative space
	aspace_key	Unique ID of administrative space
	parent_aspace_key	ID of parent administrative space of current administrative space
	name	Name of administrative space
serviceName		Service name
prodList		List of data products
	cor_list	Core data product list
	der_list	Derivative data product list
	eve_list	Event data product list
	code	Code of data product
	name	Name of data product
	parent_code	Code of related data product (For example, related data product of long term monitoring could be wheat or rice. Different related TQDS correspond to different data layers)）
	type	Data product layer type (tms= raster layer，obj= vector layer)
tqDsConfigs		Data product attribute information (legends of data product map layers)
	tqdsCode	Code of data product
	tqdsType	Type of data product (cor=Core, der=Derivative, eve=Event)
	tqdsCustomColor	Data product legend colors
	type	Legend type（palette=single value coloring, interp=interpolated coloring，discrete=discrete coloring. Read WMTS Layer Front End Rendering Example” for more descriptions
	value	List of legend colors
	color	Legend color
	label	Name of legend
	dn_value	Layer value. When legend type is interp, the return value will display dn_value_anchor, same as dn_value; When the legend type is discrete, return value will display dn_value_start and dn_value_end, representing the start and end value of corresponding legend. When legend type is either interp or discrete, different values in layers will display in different colors.
	unit	Legend unit, such as millimeter, meter, etc,. No value means no unit.

Return example:

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": [
    {
      "serviceId": "fe1c2b38-f447-4290-a6d7-8f9ea677e8d3",
      "customSpace": [
        {
          "cspace_key": "227b3482-ea64-49b2-9d69-e343a51f43e7",
          "parent_cspace_key": null,
          "name": "Hail Affected Area"
        }
      ],
      "adminSpace": [],
      "serviceName": "Hail Damage Assessment - Corps Case",
      "prodList": {
        "cor_list": [
          {
            "code": "cor101",
            "name": "Farmland",
            "type": "obj"
          }
        ],
        "der_list": [],
        "eve_list": [
          {
            "code": "eve1.d",
            "name": "Hailstorm",
            "parent_code": ["cor101"],
            "type": "obj"
          }
        ]
      },
      "tqDsConfigs": [
        {
          "tqdsCode": "cor101",
          "tqdsType": "cor",
          "tqdsCustomColor": {
            "type": "palette",
            "value": [
              {
                "color": "#f8d072",
                "label": "Farmland",
                "dn_value": "1",
                "dn_value_anchor": null,
                "dn_value_start": null,
                "dn_value_end": null
              }
            ],
            "meta": null
          }
        },
        {
          "tqdsCode": "eve1.d",
          "tqdsType": "eve",
          "tqdsCustomColor": {
            "type": "interp",
            "value": [
              {
                "color": "#f0f5ff",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#fff59d",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.1",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#e8f30e",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.2",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#ebe210",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.3",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#e8a813",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.4",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#e97711",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.5",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#eb2710",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.6",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#c00413",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.7",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#880517",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.8",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#7f0855",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "0.9",
                "dn_value_start": null,
                "dn_value_end": null
              },
              {
                "color": "#200258",
                "label": null,
                "dn_value": null,
                "dn_value_anchor": "1",
                "dn_value_start": null,
                "dn_value_end": null
              }
            ],
            "meta": {
              "unit": ""
            }
          }
        }
      ]
    }
  ]
}

Obtain spacial scale data of data product

Interface Description：

Obtain spacial scale of data product with serviceId and tqDsCode
The obtained space range can be made into a spacial scale selector component, so that users can freely switch space scales in the front end

Request URL：

https://openapi.terraqt.com/version/v1/space-selector/query

Request Method：

POST

Header：

Host：<calculated when request is sent>
user-id：User-ID, same astoken
secret：Identity verification code

Parameter：

Parameter Name	Required?	Type	Description
serviceId	Yes	`string`	Service ID
tqDsVOS	Yes	`array`	TerraQuanta Standard Object Code VO List (View Object, used in the front-end) including: Data Product Code List（tqDsCodes）
tqDsCodes	Yes	`string`	Data product code (if multiple code is input, a set of data of those spacial scales will be returned)
tqDsParentCodes	No	`string`	Code of related data product (If a data product contains an related data product code, user needs to fill in the related data product code to obtain the corresponding data)

Input Example 1（This example obtains information of a customized space）

{
  "serviceId": "b3affb00-0289-4960-8aa3-e2323e93dccb",
  "tqDsVOS": [
    {
      "tqDsCodes": ["cor999"]
    }
  ]
}

Return Data Body 1

Parameter Name	Description
adminSpaces	Administrative Spacial data list
customSpaces	Customized Spacial data list
spaceKey	ID of space
spaceName	Name of space
parentSpaceKey	ID of parent space

Return Example 1

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": {
    "adminSpaces": null,
    "customSpaces": [
      {
        "spaceKey": "58c4b935-b8e0-474c-aa50-ceaafbf4d007",
        "spaceName": "Heishui County Xier Landslide Monitoring Area",
        "parentSpaceKey": null
      }
    ]
  }
}

Input Example 2（This example obtains information of an administrative space）

{
  "serviceId": "7ffcdbe9-5042-40b4-bcbb-8c5905431b29",
  "tqDsVOS": [
    {
      "tqDsCodes": ["cor101", "cor102", "cor103"]
    }
  ]
}

Return Data Body 2

Parameter Name	Description
adminSpaces	Administrative Spacial data list
customSpaces	Customized Spacial data list
spaceKey	ID of space
spaceName	Name of space
parentSpaceKey	ID of parent space

Return Example 2

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": {
    "success": true,
    "processMsg": "finished",
    "adminSpaces": [
      {
        "spaceKey": "CN-152221",
        "spaceName": "Khorchin Right Wing Front Flag",
        "parentSpaceKey": null
      },
      {
        "spaceKey": "CN-152221100",
        "spaceName": "Khorchin",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221101",
        "spaceName": "Sauron",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221102",
        "spaceName": "Debosi",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221103",
        "spaceName": "Dashizai",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221104",
        "spaceName": "Guiliu River TOwn",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221105",
        "spaceName": "Julihen",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221106",
        "spaceName": "Chaersen",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221107",
        "spaceName": "Elgto",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221108",
        "spaceName": "Eti",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221200",
        "spaceName": "Manchu Tun/Township",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221201",
        "spaceName": "Wulan Maudu sumu",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221202",
        "spaceName": "Alidel sumu",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221203",
        "spaceName": "Barijastai",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221204",
        "spaceName": "Rosewood",
        "parentSpaceKey": "CN-152221"
      },
      {
        "spaceKey": "CN-152221405",
        "spaceName": "Lushui Breeding Farm",
        "parentSpaceKey": "CN-152221"
      }
    ],
    "customSpaces": null
  }
}

Obtain the geological data of a certain spacial scale

Interface Description：

Obtain spatial geographic information, including the name, area, and boundary range of the space with spaceKey
Users can overlay the obtained vector boundaries of the spacial scale onto maps to display the boundary identification of data layers

Request URL：

https://openapi.terraqt.com/version/v1/space-info/get

Request Method：

Header：

Host：<calculated when request is sent>
user-id：User ID, same astoken
secret：Identity verification code

Parameter：

Parameter Name	Required?	Type	Description
spaceKey	Yes	`string`	ID of spacial scale

Input Example

{
  "spaceKey": "227b3482-ea64-49b2-9d69-e343a51f43e7"
}

Return Data Body

Parameter Name	Description
spaceKey	ID of spacial scale
parentSpaceKey	ID of parent spacial scale
objPolygon	Boundary scale (vector polygon)
spaceName	Name of spacial scale
area	Area of spacial scale (unit: square meter）
level	Level of administrative space (10 = national, 20 = provincial/state, 30 = city, 40 = county, 50 = township)
spaceType	Type of space ( ADMIN = administrative space, CUSTOM = customized space)

Return Example

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": {
    "spaceKey": "227b3482-ea64-49b2-9d69-e343a51f43e7",
    "parentSpaceKey": null,
    "objPolygon": "{ \"type\": \"Polygon\", \"coordinates\": [ [ [ 80.822656875331049, 40.54439307524207 ], [ 80.954700446963017, 40.53942450299138 ], [ 80.954248758576583, 40.504343371645604 ], [ 80.822054624149146, 40.510365883464623 ], [ 80.822656875331049, 40.54439307524207 ] ] ] }",
    "spaceName": "Hail Affected Area",
    "area": "43029791",
    "level": null,
    "spaceType": "CUSTOM"
  }
}

Obtain list of data timelines of the data product

Interface Description：

Obtain data timeline with the corresponding spacial scale of the data product, with tqDsCode and spaceKey
The obtained timestamp list can be made into a timeline component, which the user can use to freely view the data layer of different time in the front end

Request URL：

https://openapi.terraqt.com/version/v1/timeline/query

Request Method：

POST

Header：

Host：<calculated when request is sent>
user-id：User-ID, same as token
secret：Identity verification code

Parameter：

Parameter Name	Required?	Type	Description
serviceId	Yes	`string`	Service ID
spaceKey	Yes	`string`	ID of spacial scale
timeLineRequestVO	Yes	`string`	Valid data time query request VO (View Object, used in front-end) of space within service
tqDsCodes	Yes	`string`	Code of data product (can be more than one)
tqDsParentCodes	No	`string`	Code of Related data product (If a data product contains an related data product code, user needs to fill in the related data product code to obtain the corresponding data)

Input Example

{
  "serviceId": "e2434265-e297-46b0-a2a6-70e6a2d721fa",
  "spaceKey": "CN-441704",
  "timeLineRequestVO": {
    "tqDsCodes": ["der108.b", "der108.c", "der108.d"],
    "tqDsParentCodes": [""]
  }
}

Return Data Body

Parameter Name	Description
timeLines	Data timestamp List
timeLine	Data timestamp
tqDsCode	Code of data product
parentTqDsCode	Code of related data product

Return Example

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": {
    "success": true,
    "processMsg": "finished",
    "timeLines": [
      {
        "parentTqDsCode": "cor1010205",
        "timeLine": [
          "20210114",
          "20210213",
          "20210223",
          "20210129",
          "20210404",
          "20210315",
          "20210218",
          "20210119",
          "20210509",
          "20210618"
        ],
        "tqDsCode": "der108.b"
      },
      {
        "parentTqDsCode": "cor1010205",
        "timeLine": [
          "20210213",
          "20210114",
          "20210223",
          "20210129",
          "20210404",
          "20210315",
          "20210218",
          "20210119",
          "20210509"
        ],
        "tqDsCode": "der108.c"
      },
      {
        "parentTqDsCode": "cor1010205",
        "timeLine": [
          "20210213",
          "20210114",
          "20210223",
          "20210129",
          "20210404",
          "20210315",
          "20210119",
          "20210218",
          "20210509"
        ],
        "tqDsCode": "der108.d"
      }
    ]
  }
}

Obtain Specific Layers and Statistics of the Data Product

Interface Description：

Obtain the specific layers (dataFile) and statistics (databox) with tqDsCode, spaceKey and timeLine
The displayed data layer can be dynamically obtained according to the data product selector component, spatial range selector component and timeline component of the front end

Request URL：

https://openapi.terraqt.com/version/v1/product-tile/query

Request Method：

POST

Request Header：

Host：<calculated when request is sent>
user-id：User-ID, same as token
secret：Identity verification code

Request Parameter:

Parameter Name	Required?	Data Type	Description
productTileRequestVO	Yes	`object`	Data product request Parameter list
tqDsCodes	Yes	`array`	Code of data product (Can be more than one)
tqDsParentCodes	No	`array`	Code of related data product (If a data product contains an related data product code, user needs to fill in the related data product code to obtain the corresponding data)
serviceId	Yes	`string`	Service ID
spaceKey	Yes	`string`	ID of spacial scale
timestamp	Yes	`long`	Timestamp of data user wants to search (if multiple tqDsCode is input, the most recent layer data of all data product searched will be returned.

Input Example 1：（This example obtains a vector layer）

{
  "productTileRequestVO": {
    "tqDsCodes": ["der101.d"],
    "tqDsParentCodes": ["cor1010210"]
  },
  "serviceId": "8a151451-fcb8-4eb1-b4a8-b814c1c448aa",
  "spaceKey": "22c2b0a9-30d4-4f8b-8ea6-1206b79759da",
  "timestamp": "1591027199"
}

Return Data Body 1：

Parameter Name	Description
tqDsCode	Code of data product
tqDsName	Name of data product
databox	Statistical data of data products
area	Area of data product (unit: square meter)
cor_area	Area of data product (unit: square meter, same as area for now)
der_max	Maximum value of data product attributes
der_meanv	Mean value of data product attributes
der_min	Minimum value of data product attributes
feature_count	Number of vectors included in the data product
percent	Percentage of area of data product compared to the current spacial scale
percentage	Percentage of area of data product compared to the current spacial scale (Same as percent for now)
tileData	Related data of layer
originalFile	This is the original vector layer link of the data product, is only valid for the vector data type
batchType	Batch Type (vector = vector layers, raster = raster layers)
serviceId	Service ID
spaceKey	ID of spacial scale
parentTqDsCode	Code of related data product (For example, related data product of long term monitoring could be wheat or rice. Different related TQDS correspond to different data layers)
dataFile	Layer link of the data product (For layer rendering examples, please check “ WMTS Layer Front End Rendering Example" below)
timestamp	Data Timestamp
maxZoom	Maximum zoom level of layer (Tile data will not be displayed pass the maximum zoom level)
batchId	Unique ID of data layers

Return Example 1：

{
    "success": true,
    "code": "200",
    "msg": "success",
    "retry": false,
    "data": [
        {
            "success": true,
            "processMsg": "finished",
            "tqDsCode": "der101.d",
            "tqDsName": "Drought Monitoring",
            "databox": {
                "area": "19317545.705",
                "percentage": "0.014",
                "feature_count": 433,
                "der_min": "0.0",
                "der_max": "0.973",
                "der_meanv": "0.466",
                "cor_area": null,
                "percent": null
            },
            "tileData": {
                "batchId": "356c2b38-f447-4260-c6d7-8f9ea6774er3",
                "batchType": "vector",
                "serviceId": "8a151451-fcb8-4eb1-b4a8-b814c1c448aa",
                "spaceKey": "22c2b0a9-30d4-4f8b-8ea6-1206b79759da",
                "parentTqDsCode": "cor1010210",
                "dataFile": "https://dev-tile.terraqt.com/tile/xyz/{z}/{x}/{y}.pbf?path=8a151451-fcb8-4eb1-b4a8-b814c1c448aa/cor1010210/der101.d/202006/22c2b0a9-30d4-4f8b-8ea6-1206b79759da/vectortiles",
                "originalFile": "https://dev-tile.terraqt.com/tile/geojson?path=8a151451-fcb8-4eb1-b4a8-b814c1c448aa/cor1010210/der101.d/202006/22c2b0a9-30d4-4f8b-8ea6-1206b79759da/vectortiles",
                "timestamp": "202006",
                "maxZoom": 14
            }
        }
    ]
}

Input Example 2：（This example obtains a raster layer）

{
  "productTileRequestVO": {
    "tqDsCodes": ["der108.b", "der108.c"],
    "tqDsParentCodes": ["cor1010210"]
  },
  "serviceId": "e2434265-e297-46b0-a2a6-70e6a2d721fa",
  "spaceKey": "CN-441704",
  "timestamp": "1620489600"
}

Return Data Body 2：

Parameter Name	Description
tqDsCode	Code of data product
tqDsName	Name of data product
databox	Statistical data of data products
area	Area of data product (unit: square meter)
cor_area	Area of data product (unit: square meter, same as area for now)
der_max	Maximum value of data product attributes
der_meanv	Mean value of data product attributes
der_min	Minimum value of data product attributes
feature_count	Number of vectors included in the data product
percent	Percentage of area of data product compared to the current spacial scale
percentage	Percentage of area of data product compared to the current spacial scale (Same as percent for now)
tileData	Related data of layer
originalFile	This is the original vector layer link of the data product, is only valid for the vector data type
batchType	Batch Type (vector = vector layers, raster = raster layers)
serviceId	Service ID
spaceKey	ID of spacial scale
parentTqDsCode	Code of related data product (For example, related data product of long term monitoring could be wheat or rice. Different related TQDS correspond to different data layers)
dataFile	Layer link of the data product (For layer rendering examples, please check “ WMTS Layer Front End Rendering Example" below)
timestamp	Data Timestamp
maxZoom	Maximum zoom level of layer (Tile data will not be displayed pass the maximum zoom level)
batchId	Unique ID of data layers

Return Example 2：

{
    "success": true,
    "code": "200",
    "msg": "success",
    "retry": false,
    "data": [
        {
            "success": true,
            "processMsg": "finished",
            "tqDsCode": "der108.b",
            "tqDsName": "Water Transparency",
            "databox": {
                "area": null,
                "percentage": null,
                "feature_count": null,
                "der_min": "0.0",
                "der_max": "4.98",
                "der_meanv": "1.24",
                "cor_area": null,
                "percent": null
            },
            "tileData": {
                "batchId": "356c2b38-f447-4260-c6d7-8f9ea6774er3",
                "batchType": "raster",
                "serviceId": "e2434265-e297-46b0-a2a6-70e6a2d721fa",
                "spaceKey": "CN-441704",
                "parentTqDsCode": null,
                "dataFile": "e2434265-e297-46b0-a2a6-70e6a2d721fa/der108.b/20210509/CN-441704/rastertiles",
                "originalFile": null,
                "timestamp": "20210509",
                "maxZoom": 14
            }
        },
        {
            "success": true,
            "processMsg": "finished",
            "tqDsCode": "der108.c",
            "tqDsName": "Suspended Matter Concentration",
            "databox": {
                "area": null,
                "percentage": null,
                "feature_count": null,
                "der_min": "0.314",
                "der_max": "80.0",
                "der_meanv": "12.807",
                "cor_area": null,
                "percent": null
            },
            "tileData": {
                "batchId": "356c2b38-f447-4260-c6d7-8f9ea6774er3",
                "batchType": "raster",
                "serviceId": "e2434265-e297-46b0-a2a6-70e6a2d721fa",
                "spaceKey": "CN-441704",
                "parentTqDsCode": null,
                "dataFile": "e2434265-e297-46b0-a2a6-70e6a2d721fa/der108.c/20210509/CN-441704/rastertiles",
                "originalFile": null,
                "timestamp": "20210509",
                "maxZoom": 14
            }
        }
    ]
}

Obtain all layer data of data products included in the service

Interface Description:

Obtain all WMTS layers and statistical data of data products included in the service through serviceId
Through this interface, users can access the acquired WMTS layer and statistics in their map applications.

Request URL:

https://openapi.terraqt.com/version/v1/product-tile/all

Request Method

Header:

Host：<calculated when request is sent>
user-id: User ID, same as token
secret：Identity verification code

Parameter:

Parameter Name	Required?	Type	Description
serviceId	Yes	`string`	Service ID

Input Example

{
  "serviceId": "fe1c2b38-f447-4290-a6d7-8f9ea677e8d3"
}

Return Data Body

Parameter Name	Description
tqDsCode	Code of Data product
tqDsName	Name of Data product
databox	Statistical Data of data product
area	Area of data product (unit: square meter)
cor_area	Area of data product (unit: square meter, same as area for now)
der_max	Maximum value of data product attributes
der_meanv	Mean value of data product attributes
der_min	Minimum value of data product attributes
feature_count	Number of vectors included in the data product
percent	Percentage of area of data product compared to the current spacial scale
percentage	Percentage of area of data product compared to the current spacial scale (Same as percent for now)
tileData	Related Data of layer
originalFile	This is the original vector layer link of the data product, is only valid for the vector data type
batchType	Batch Type (vector = vector layers, raster = raster layers)
serviceId	ID of spacial scale
parentTqDsCode	Code of related data product (For example, related data product of long term monitoring could be wheat or rice. Different related TQDS correspond to different data layers)
dataFile	Layer Link of the data product (For layer rendering examples, please check "WMTS layer Front End Rendering Example" below)
timestamp	Data timestamp of layer
maxZoom	Maximum zoom level of layer (Tile data will not be displayed pass the maximum zoom level)
batchId	Unique ID of data layers

Return Example ：

{
  "success": true,
  "code": "200",
  "msg": "success",
  "retry": false,
  "data": [
    {
      "success": true,
      "processMsg": "finished",
      "tqDsCode": "eve1.d",
      "tqDsName": "Hailstorm",
      "databox": {
        "area": "31714245.308",
        "percentage": "0.737",
        "feature_count": 418,
        "der_min": null,
        "der_max": null,
        "der_meanv": null,
        "cor_area": null,
        "percent": null
      },
      "tileData": {
        "batchId": "356c2b38-f447-4260-c6d7-8f9ea6774er3",
        "batchType": "vector",
        "serviceId": "fe1c2b38-f447-4290-a6d7-8f9ea677e8d3",
        "spaceKey": "227b3482-ea64-49b2-9d69-e343a51f43e7",
        "parentTqDsCode": null,
        "dataFile": "https://dev-tile.terraqt.com/tile/xyz/{z}/{x}/{y}.pbf?path=fe1c2b38-f447-4290-a6d7-8f9ea677e8d3/cor101/eve1.d/20210817/227b3482-ea64-49b2-9d69-e343a51f43e7/vectortiles",
        "originalFile": "https://dev-tile.terraqt.com/tile/geojson?path=fe1c2b38-f447-4290-a6d7-8f9ea677e8d3/cor101/eve1.d/20210817/227b3482-ea64-49b2-9d69-e343a51f43e7/vectortiles",
        "timestamp": "20210817",
        "maxZoom": 14
      }
    },
    {
      "success": true,
      "processMsg": "finished",
      "tqDsCode": "cor101",
      "tqDsName": "Farmland",
      "databox": {
        "area": "31838411.418",
        "percentage": "0.7399",
        "feature_count": 449,
        "der_min": null,
        "der_max": null,
        "der_meanv": null,
        "cor_area": null,
        "percent": null
      },
      "tileData": {
        "batchId": "356c2b38-f447-4260-c6d7-8f9ea6774er3",
        "batchType": "vector",
        "serviceId": "fe1c2b38-f447-4290-a6d7-8f9ea677e8d3",
        "spaceKey": "227b3482-ea64-49b2-9d69-e343a51f43e7",
        "parentTqDsCode": null,
        "dataFile": "https://dev-tile.terraqt.com/tile/xyz/{z}/{x}/{y}.pbf?path=fe1c2b38-f447-4290-a6d7-8f9ea677e8d3/cor101/202108/227b3482-ea64-49b2-9d69-e343a51f43e7/vectortiles",
        "originalFile": "https://dev-tile.terraqt.com/tile/geojson?path=fe1c2b38-f447-4290-a6d7-8f9ea677e8d3/cor101/202108/227b3482-ea64-49b2-9d69-e343a51f43e7/geojsontiles",
        "timestamp": "202108",
        "maxZoom": 14
      }
    }
  ]
}

WMTS Layer Front End Rendering Example

Users should choose an appropriate map application framework before WMTS layer front-end rendering. Suggested map application framework include openlayers, mapboxGL, Leaflet, Gaode API, etc.
Data Layers (dataFile）are divided into Raster Layer and Vector Layer.
- Raster Layer:
  - Layers are displayed in PNG files with colors pre-rendered. Colors of the layer can not be changed in real time.
  - To display the corresponding layers on the front end map application, load the following layer service URL (test link) as a map XYZ Tiles. https://dev-tile.terraqt.com/tile/xyz/{z}/{x}/{y}.png?path=7ffcdbe9-5042-40b4-bcbb-8c5905431b29/cor103/202005/CN-152221/rastertiles
  - The layer loading effect is shown below (base map from Tianditu）
- Vector Layer:
  - This layer displays vector polygons or vector points, and the colors need to be rendered in real time by the front end according to the configuration
  - The vector layer may contain multiple vector polygons, and each vector will contain its corresponding attributes, which can be displayed in the map application as required
  - To display the corresponding layers on the front end map application, load the following layer service URL (test link) as a map Vector Tiles. https://dev-tile.terraqt.com/tile/xyz/{z}/{x}/{y}.pbf?path=8a151451-fcb8-4eb1-b4a8-b814c1c448aa/cor1010201/202006/22c2b0a9-30d4-4f8b-8ea6-1206b79759da/vectortiles
  - The layer loading effect is shown below (base map from Tianditu）
If you have questions, please check TerraQuanta’s layer rendering access example on GitHub — Github Page
- As of now, only layer rendering example with openlayer map framework is provided. If user is using different frameworks, one can contact TerraQuanta business personals for access examples of corresponding map framework
- If the map framework user uses does not support WMTS layer access, please contact TerraQuanta business personals for other types of layer data
Rendering method of data layers contain single value rendering, interpolated rendering, and discrete rendering. Rendering example codes are provided in the examples
- Single value rendering (palette): In data layers, each value corresponds to some color
  - Example:
- Interpolated Rendering (interp): In the data layer, a certain value corresponds to a certain color, and the value between the two values is automatically selected as the intermediate color. For example, if the value is 0, the color is yellow, and if the value is 1, the color is red. If the value is 0.5, the difference between yellow and red will automatically generate orange to show the value 0.5.
  - Example:
- Discrete Rendering (discrete): In the data layer, one color is used to represent a numeric range of data. For example, green represents the data of crop growth from 0.800 to 1.000, and red represents the data of crop growth from 0.000 to 0.300
  - Example:

API Manual

Terraqt Restful API​

Version Information​

Interface Introduction​

Introduction​

Why API?​

Basic Standards​

Major Concepts​

Interface Manual​

Preparation Work​

Steps:​

Interface Description:​

Request URL:​

Request Method:​

Header:​

Parameter:​

Input Example:​

Return Data Body​

Return Example​

Data Interface​

Interface Description​

Request URL:​

Request Method:​

Header:​

Parameter:​

Input Example​

Return Data Body​

Return example:​

Interface Description：​

Request URL：​

Request Method：​

Header：​

Parameter：​

Input Example 1（This example obtains information of a customized space）​

Return Data Body 1​

Return Example 1​

Input Example 2（This example obtains information of an administrative space）​

Return Data Body 2​

Return Example 2​

Interface Description：​

Request URL：​

Request Method：​

Header：​

Parameter：​

Input Example​

Return Data Body​

Return Example​

Interface Description：​

Request URL：​

Request Method：​

Header：​

Parameter：​

Input Example​

Return Data Body​

Return Example​

Interface Description：​

Request URL：​

Request Method：​

Request Header：​

Request Parameter:​

Input Example 1：（This example obtains a vector layer）​

Return Data Body 1：​

Return Example 1：​

Input Example 2：（This example obtains a raster layer）​

Return Data Body 2：​

Return Example 2：​

Interface Description:​

Request URL:​

Request Method​

Header:​

Parameter:​

Input Example​

Return Data Body​

Return Example ：​

WMTS Layer Front End Rendering Example​

Terraqt Restful API

Version Information

Interface Introduction

Introduction

Why API?

Basic Standards

Major Concepts

Interface Manual

Preparation Work

Steps:

Interface Description:

Request URL:

Request Method:

Header:

Parameter:

Input Example:

Return Data Body

Return Example

Data Interface

Interface Description

Request URL:

Request Method:

Header:

Parameter:

Input Example

Return Data Body

Return example:

Interface Description：

Request URL：

Request Method：

Header：

Parameter：

Input Example 1（This example obtains information of a customized space）

Return Data Body 1

Return Example 1

Input Example 2（This example obtains information of an administrative space）

Return Data Body 2

Return Example 2

Interface Description：

Request URL：

Request Method：

Header：

Parameter：

Input Example

Return Data Body

Return Example

Interface Description：

Request URL：

Request Method：

Header：

Parameter：

Input Example

Return Data Body

Return Example

Interface Description：

Request URL：

Request Method：

Request Header：

Request Parameter:

Input Example 1：（This example obtains a vector layer）

Return Data Body 1：

Return Example 1：

Input Example 2：（This example obtains a raster layer）

Return Data Body 2：

Return Example 2：

Interface Description:

Request URL:

Request Method

Header:

Parameter:

Input Example

Return Data Body

Return Example ：

WMTS Layer Front End Rendering Example