Geovisualization Developer's Guide

Retrieving Statistics for a Query

The Geovisualization REST API provides a mechanism that allows you to retrieve statistics about column values from the results of your query. For example, to determine the minimum, maximum and average values of certain columns to determine how to distribute the colors in a heat map and change your code accordingly.

To fetch statistical data, you construct a stats JSON object that you send in the request body to the Geovisualization REST API, along with the query ID. The stats object represents a nested list containing column names and dynamic parameters:

  • column_stats: This object contains column names, each of which is a facet or metric defined in the query, followed by a list of statistical functions ($min, $max, $count_distinct, $count, $average or $sum) to be run on them. (See Query Statistics.)
  • dynamic: This object contains dynamic parameters, each of which is defined in the query, or $drop to remove that parameter from the filters. (See Using Dynamic Parameters.)

A complete stats JSON object would be structured as follows:

{
  "stats": [{
    "column_stats": {
      <column_name>: [<stats_function>, <stats_function>],
      <column_name>: [<stats_function>, <stats_function>]
    },
    "dynamic": {
      <dynamic_parameter>: <value> OR "$drop",
      <dynamic_parameter>: <value> OR "$drop",
    }
  }]
}

To get the statistics, include the object above as the request body in an authenticated POST to the following resource:

https://datalens.api.here.com/v1/queries/{QUERY_ID}/stats?app_code={YOUR_APP_CODE}&app_id={YOUR_APP_ID}

You can also use the queries/_ID_ endpoint in the 07. Query CRUD folder of our Postman collection.

You will receive a response body that includes a list of values representing the statistical data for the query.

$drop Example

To retrieve statistics for a query on a dataset containing measurements of earthquake magnitudes, POST the following request:

https://datalens.api.here.com/v1/queries/{QUERY_ID}/stats?app_code={YOUR_APP_CODE}&app_id={YOUR_APP_ID}

{

  "stats": [{
    "column_stats": {"Magnitude": ["$min","$max"]},
    "dynamic": {"min":"$drop", "max":"$drop"}}
]}

You can also use the queries/_ID_ endpoint in the 07. Query CRUD folder of our Postman collection.

This requests the minimum and maximum values of the Magnitude column of the query. Since the query contains dynamic parameters, you need to specify those values. If you set these parameters to constant values, for example, min to 1 and max to 3, the returned statistics would be 1 and 3 because the dynamic parameters are used as filters on the very column for which you want the true range. Clearly, this is not very helpful, and you need to avoid using those parameters.

To do this, pass the value $drop in the request. This eliminates the need for values for the dropped parameters, and every filter action that depends on them will be ignored. In this way, you can get the true maximum and minimum values of the Magnitude column.