GeoFeatures documentation - Response data structure

Response data structure

The response of the service is a JSON object divided into four sections:

Status: This section provides information regarding the outcome of the service call, the number of elements processed by the operation and paging information in case the service call returns more than one result record.
Request: This section returns the request received by the service.
This section is useful for debugging purposes and it is optional: it is disabled in production.
Connection: This section returns the database connection details.
This section is useful for debugging purposes and it is optional: it is disabled in production.
Response: This section contains the data requested from the service.

The service will always return the status section, while the response section will be returned only if the service found results and there were no errors.

Status section [`status`]

This section is comprised of elements that provide information on the operation status, errors or warnings, on the affected count of elements processed by the operation and on current paging limits.

Operation state [state]

The state indicates the outcome of the operation, this item is always present.

OK: Successful operation.
ERROR: The operation failed.
IDLE: This should never be returned: if that happens it means that there was an uncaught error before the service was done parsing the request.

Affected count [total]: This element contains the total count of objects affected by the operation. Suppose you request all tiles contained in the provided square, this element will contain the total count of the tiles selected by the service, altough you might only request the first 10.

Starting record [start]: This paging variable contains the 0-based index of the first returned element. If you were requesting the second 10 records, this element would be 1.

Page limit [limit]: This paging variable contains the maximum number of elements to be returned by the current request. If you were requesting at most 10 records, this element would be 10.
Note that this element does not hold the actual number of returned elements.

Actual count [count]: This paging variable contains the actual number of elements returned by the service.
Note that this number may be smaller than the maximum number of requested elements .

Status message [message]: This element holds eventual error messages or notices. This element will always be returned in case the service fails because of an error; it may be returned if the service has enforced settings, such as a page limit for operations that could return a large number of results.

Error code [code]: This element holds the eventual error code, this will only occur if there was an error.
Note that this is for debugging purposes and it is disabled in production.

Error file [file]: This element holds the eventual error file path, this will only occur if there was an error.
Note that this is for debugging purposes and it is disabled in production.

Error file line [line]: This element holds the eventual error file line, this will only occur if there was an error.
Note that this is for debugging purposes and it is disabled in production.

Error trace [trace]: This element holds the eventual error trace, this will only occur if there was an error.
Note that this is for debugging purposes and it is disabled in production.

Request section [`request`]

This section will return the request as interpreted by the service. This means that you will only see the parameters that the service recognised or handled, in the format used by the service.
Note that this is generally used for debugging purposes and is only available if requested to the service.

Connection section [`connection`]

This section will return the database connection information.
Note that this is generally used for debugging purposes and is only available if requested to the service.
This option is disabled in production.

Database server [server]: The server DSN.

Database name [database]: The server database.

Collection name [collection]: The server database collection.

Response section [`data`]

This section will return the service data, in case the operation was successful and results were found.

The data is structured as a single or an array of records that contain the following information:

Tile index [_id]: The tile index or id [int]. The grid is divided into 43200 horizontal and 18000 vertical tiles, this element represents the unique identifier of the tile and is calculated by the formula (Y * 43200) - (X + 1), where both X and Y are 0-based.

Tile center point [pt]

The tile center coordinates, in decimal degrees. This element is an object formatted as a GeoJSON point:

type: The constant Point.
coordinates: An array of two elements corresponding respectively to the longitude and latitude of the point in decimal degrees.

Tile center point [dms]: The tile center coordinates, in degrees, minutes and seconds notation. This element is an array of two elements corresponding respectively to the longitude and latitude of the point, formatted as a DDD°MM'SS"H string in which DDD corresponds to the degrees, MM to the minutes, SS to the seconds and H to the hemisphere (N or S for latitude and E or W for longitude).

Tile X and Y [tile]: The tile X and Y indices as an array of two integers.

Tile vertices [bdec]: The tile vertices in decimal degrees. The element is structured as an array of two items representing respectively the top-left and bottom-right coordinates of the tile. Both items are an array of two elements, longitude and latitude, representing the coordinates of the vertex.

Tile vertices [bdms]: The tile vertices in degrees, minutes and seconds. The element is structured as an array of two items representing respectively the top-left and bottom-right coordinates of the tile. Both items are an array of two elements, longitude and latitude, representing the coordinates of the vertex and formatted as a DDD°MM'SS"H string in which DDD corresponds to the degrees, MM to the minutes, SS to the seconds and H to the hemisphere (N or S for latitude and E or W for longitude).

Tile elevation [elev]: The tile elevation in meters.

Distance [dist]: The distance of the tile center from the provided point in meters. This element is only returned for operations requesting tiles by proximity.

Tile climate [clim]: The tile climate variables. This section holds a series of sub-sections representing the period to which the climatic variables refer to, each section is structured in the same way.; Currently, the service only provides current climate conditions, this sub-section is tagged by 2000.

Global Environment Stratification [gens] NEW: This element represents the global environment stratification for the current tile, it is an array of three elements representing:

Harmonized World Soil [hwsd] NEW: This element represents the the harmonized world soil database, this attribute provides soil information in the 30 seconds grid, reference information can be found here. This information is coded as follows:

Global Human Footprint [ghf] NEW: This element provides an updated map of anthropogenic impacts on the environment in geographic projection which can be used in wildlife conservation planning, natural resource management, and research on human-environment interactions. More information can be found here. The provided value is a value ranging from 0 to 100 where 0 indicates no human impact.

Global Land Cover [gcov] NEW: This element provides a land cover map, reference information can be found here. This information is coded as follows:

Bioclimatic variables [bio]: This element is an array of 19 bioclimatic variables tagged by 1 to 19:

Monthly precipitation [prec]: This element collects the monthly precipitation, it is an array of 12 elements, one per month (mm.)

Monthly temperature [temp]

This element collects the monthly temperatures, it is an array of 3 elements:

l: Average monthly minimum temperature [C° * 10].
This element is an array of 12 items, tagged 1 to 12, one per month.
m: Average monthly mean temperature [C° * 10].
This element is an array of 12 items, tagged 1 to 12, one per month.
h: Average monthly maximum temperature [C° * 10].
This element is an array of 12 items, tagged 1 to 12, one per month.

GeoFeaturesweb-service documentation

Response data structure

Status section [status]

Request section [request]

Connection section [connection]

Response section [data]

GeoFeatures
web-service documentation

Status section [`status`]

Request section [`request`]

Connection section [`connection`]

Response section [`data`]