GeoFeatures documentation - Request data structure

Request data structure

The service request is a GET HTTP call, such as in https://service-url?param&param=value&...&param=value&key=SERVICE_ACCESS_KEY,
where some parameters require an associated value, while others not.

These parameters can be divided into six categories:

Operation: The requested operation or command.
This kind of parameter does not need to have a value, only one of the accepted tags should be provided and the parameter is required.
Shapes: The geometric shape used for selecting the grid tiles.
All operations, except ping and help, require this parameter.
Modifiers: Optional operation modifiers or options.
This set of parameters can be used to alter the result or request optional results. This kind of parameter does not need to have a value and several of them may be combined as a set of flags.
Filters: This set of parameters can be used to provide a filter based on variables other than the geometry.
This can be useful to retrieve data for a location where the coordinates are not precise, but where the elevation range is known. The other function of this set of parameters is to reduce the number of properties returned in the service data response.
Paging: This set of parameters can be used to limit the number of returned records. This can be useful and is enforced in cases where the service might return a large number of records.

Operations

This set of parameters determines what the service is going to do, only one of the following tags must be provided and it does not require any value:

Key [key]: The key is necessary to use the service and it must be included in all requests as parameter. In order to request a key please contact the system administrator.

Ping [ping]: This operation can be used to check if the service is running, it does not require any other parameter and simply returns the status and the string pong in the response section.

Help [help]: This operation can be used to get help in using this service, it does not require any other parameter and simply returns the help pages in HTML.

Tiles [tiles]: This operation can be used to retrieve a list of tiles by identifier. The operation requires the tile shape parameter holding the list of requested tile identifiers.

Contains [contains]: This operation can be used to retrieve the tile that contains the provided point, or all tiles whose center point is contained by the provided rectangle or polygon. The operation requires the shape parameter and will enforce paging if the provided geometry is not a point.

Intersects [intersects]: This operation can be used to retrieve the tiles that intersect with the provided point, rectangle or polygon. The operation requires the shape parameter and will enforce paging if the provided geometry is not a point.

Near [near]: This operation can be used to retrieve the tiles closest to the provided point, the service will return a list of tile records, 100 at most, sorted by distance, the closest first. The operation requires the shape parameter in the form of a point. This is the only operation that will add the distance value to the results. The operatrion also accepts the maximum distance parameter to limit the selection to a maximum distance from the provided point in meters.

Shapes

This set of parameters indicates the shape used to select the grid tiles, only one of the following should be provided:

Tiles [tile]: This shape represents a comma-delimited list of tile identifiers, this geometry is only used by the tiles operation.

Point [point]: This shape represents a point, the value represents a pair of decimal degrees comma delimited coordinates indicating respectively the longitude and latitude of the point.

Rectangle [rect]: This shape represents a rectangle, the value represents the two vertices of the shape in decimal degrees. The parameter is expressed as two blocks separated by a semicolon, each block represents a vertex composed of the longitude and latitude separated by a comma.
When requesting a copy of the request, an item will be added to the shape structure holding the area of the geometry.

Polygon [polygon]: This shape represents a polygon in decimal degrees. The shape is provided as a string using three divider tokens: the outer and inner rings are divided by a colon, the ring vertices are divided by a semicolon and the vertex coordinates by a comma.
When requesting a copy of the request, an item will be added to the shape structure holding the area of the geometry.

Modifiers

This set of parameters modify the result of the service and are used to activate cusstom options. The parameters do not need a value and some may be concurrent:

Count [count]: This option will disable the results pane and only return the affected count in the status section.
This option is incompatible with the range modifier, if both are provided, this one will be chosen. This options can be useful when a large set of results may be returned: by calling the service with this modifier, one may organise paged results retrieval.

Range [range]: This option will aggregate the results of the service into a single record, where continuous values will be expanded into an set of three elements in which l will hold the minimum value, m the average value and h the maximum value; categorical variables will be expanded into an array containing all distinct values. Only the elevation and the climate section will be included in the result (including the distance when requesting the near operation).
This option is incompatible with the count modifier, if both are provided, the latter will be chosen. This modifier is not active if you provide a point to the contains or intersects operations.
This option can be useful to explore the variation and range of a set of results.

Copy request [cpy-request]: This option will return the request provided to the service in the request section of the response. This option can be useful to debug service requests and can be cumulated with all other modifiers.

Copy connection [cpy-connection]: This option will return the database connection parameters used by the service in the connection section of the response. This option can be useful to debug service requests and can be cumulated with all other modifiers.
In the production environment this option is disabled.

Filters

This set of parameters can be used to refine the results matching the provided shape using a set of variables other than the geometry:

Elevation [elevation]: The value of this parameter is a comma delimited set of two values that represent the elevation range in meters. Results of the operation will only include tiles belonging to that range.

Distance [distance]: This parameter can be used for two purposes: when provided along with a point, it indicates that you are providing a circle shape as the geometry selection; when provided with the near operation, it reduces the results to those tiles within that distance. The value is expressed in meters.

Property [select]: This parameter can be used to include or exclude individual elements of the service response. The parameter is a list of blocks separated by a semicolon where each block represents a key/value pair separated by a comma: the key part identifies the property, if the value part is 1 the property should be included in the result, if the value is 0 the property should be excluded. The property is represented by the label used in the response data section. To select properties that are part of a subsection, separate each level by a period: for instance, to select the average minimum temperature in February, you would provide the following block: clim.2000.temp.l.2

Paging

This set of parameters can be used to control the maximum number of elements returned by the service and implement paging:

Start [start]: The value of this parameter is an integer that indicates from what record to start returning results; in other words, it indicates the number of records to skip before returning data.

Limit [limit]: The value of this parameter is an integer that indicates the maximum count of records that the service should return. The actual number of records that the service will actually return will be smaller or equal to this value.