Geovisualization Developer's Guide

Querying your Data

In this step you will define a query on the earthquake dataset using the Geovisualization REST API query language. You will send your query to the Geovisualization backend and receive a query ID in return. Then, if you want others to be able to view your visualization, you can publish the query to make it publicly accessible.

A Note about Queries

In Geovisualization, queries on datasets fetch, aggregate, transform and filter the data to prepare it for visualizations. Geovisualization provides a specially designed query language, which uses JSON syntax to define the actions to perform on the data. The Geovisualization query language operates on your data in a similar way to SQL.

A query is associated with a specified dataset in the query definition. The query receives its own ID after it has been sent to the backend with the Geovisualization REST API and stored in your account.

A query typically includes the following information:

  • The ID of the dataset associated with the query, whose data the query will process
  • Instructions on how the columns of the dataset will be selected
  • Instructions on how the selected data will be filtered, transformed and sorted, where required
  • Geospacial transformations that project the data from map coordinates to screen coordinates
Note: For information about the Geovisualization REST API query language, see Query Language API Reference.

A Note about Map Tiling

For the query on the earthquake dataset, you need to select the data you want to visualize on the map. In this example, you will select the location, magnitude and depth for each earthquake event.

You could define the query to select the data for all earthquakes in the dataset. However, to optimize performance, Geovisualization provides a way to select only the data required for the currently visible area on the map, referred to as the "current viewport". Geovisualization does this by a process called "tiling", which subdivides the whole map into a grid of tiles. A tile is identified by a column (x) and a row (y) and a zoom level (z). The query you define will call only the data that falls on the tiles visible in the current viewport.

In the browser, the visualization app is aware of which tiles comprise the current viewport. The Geovisualization JavaScript API executes the query for each tile, requesting all the data points per tile. The query takes each tile's x, y and z as parameters in the request to the backend, which reprojects each geographical point into pixel space to determine which data points fall into each tile. Finally, it returns the data point including the original geographical coordinates (not the pixel coordinates). Then, the JavaScript renders the data point on the map at the correct location.

Define the Query Code

You will now define the query (you can find the full code here):

Start with creating a query array:
{
  "query": {
  …
  }
}
And then inside the array, metrics is a list of strings representing the names of the columns in the dataset that you want to include in the query result:
...
  "metrics": [
    "Lat",
    "Lon",
    "Magnitude",
    "Depth",
    "Region"
  ],
...
namespace is a list of variables that you use to define the parameters required in the transformation of data points returned during tiling:
...  
  "namespace": {
    "tx": {
    "source": [{
      "$input": "x"
    }]
    },
    "ty": {
    "source": [{
      "$input": "y"
    }]
    },
    "tz": {
    "source": [{
      "$input": "z"
    }]
    },
    "buffer": {
    "source": [{
      "default": 0,
      "$input": "buffer"
    }]
    },
    "px": {
    "source": [
      "Lon",
      "tz"
    ],
    "apply": [{
      "type": "transform",
      "fn": "lon_to_x"
    }]
    },
    "py": {
    "source": [
      "Lat",
      "tz"
    ],
    "apply": [{
      "type": "transform",
      "fn": "lat_to_y"
    }]
    },
    "pixels": {
    "source": [
      "px",
      "py"
    ]
    }
  },
...
filters contains a single filter that restricts the query to return only the data points that are visible within each tile:
...
  "filters": [{
    "pixels": {
    "$pixel_within_tile": [
      "tx",
      "ty",
      "buffer"
    ]
    }
  }],
...
dataset indicates the ID of the dataset the query is executed on:
...
  "dataset": "{DATASET_ID}"
...

Store the Query and Get the Query ID

Now that you have defined a query, you need to post it to the Geovisualization backend to store it in your account. Geovisualization registers the query and assigns it a query ID which you use to identify it in visualization apps.

To store a new query and get its ID, send a POST to the Geovisualization backend including the code of the query to store in the request body with a description and tags to help you find and classify your queries (Read more in the defining a query guide):

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

{
  "description": "Tutorial Earthquake Query",
  "tags": [
  "depths",
  "magnitudes",
  "earthquakes"
  ],
  "query": {
  "metrics": […],
  "namespace": {…},
  "filters": […],
    "dataset": "{DATASET_ID}"
  }
  }

Be sure to include your token in the Authorization field of the request header.

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

The JSON response body provides some information about the query, such as its creation date and the number of rows in its dataset. It also includes a string called id, which represents the unique query ID:

"id": "4a91cf4a8cfe4e27956b2ea52259308e",

You need to reference this query ID in your JavaScript code that styles the visualization, for example:

queryId: '4a91cf4a8cfe4e27956b2ea52259308e';

You will also now see the query ID associated with the dataset in the Data Manager.

Publish the query

By default, queries are private and can only be executed using the authentication credentials of the user who created them. To make a visualization accessible to anyone, without requiring its creator's credentials, you need to publish the query.

To publish a query, send a POST to the Geovisualization backend including in the request body the ID of the query to publish, and set the "visibility" property to "public" and you will receive a response body that confirms that the query has been published:

https://datalens.api.here.com/v1/publishing?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}
    
{
  "queries": {
    "visibility": "public",
    "ids": [
    "{SPECIFY_QUERY_ID}"
    ]
  }
}

Be sure to include your token in the Authorization field of the request header.

You can also use the publishing endpoint in the 12. Publish Queries folder of our Postman collection.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.