Geovisualization Developer's Guide

Define Query

The define query request body is a JSON object sent in the body of a Geovisualization REST API request to create a new query. See Query Language API Reference for a guide to using the Geovisualization query language.

Table 1. Define Query Request Elements
Element Data Type Mandatory Description
description String No Description of the query
tags Array No Labels used for searching for groups of queries with requests to the endpoint /queries.

For example, the following adds two tags to the query:

"tags": [
query Object Yes The query definition using the Geovisualization query language. The structure includes the following elements:
  • version – (required) Always 0.3
  • dataset – (required) The ID of the dataset to be used with this query
  • namespace – (optional) The query rules for aggregation and transformation are defined here, including any alias elements required. Aliases extend column names by adding "variables" that can be used to construct filters and data transformations. Aliases must be unique and differ from column names.

    For example, the following creates a total for column_a:

    "namespace": {
      "total": {
          "source": ["column_a"],
          "apply": [{
            "fn": "sum",
            "type": "aggregate"
  • filters - (optional) Filters can be applied to the data or to elements defined in the namespace. They support all the standard operators and data types, such as strings, dates and numbers.

    For example, the following filters will return only rows with column_a greater than or equal to 3, OR, column_b less than or equal to 10:

    "filters": [{
            "or": [
            {"column_a": {"$gte": 3}},
            {"column_b": {"$lte": 10}}
  • metrics - (required element if facets are not used) Metrics define what data the response contains and is equivalent to a SELECT statement in SQL.

    For example, with the following metrics, the response body will contain the countryname and population columns:

    "metrics": ["countryname", "population"],
  • facets - (required element if metrics are not used) Facets define how to group the data and are equivalent to a GROUP_BY statement in SQL.

    For example, with the following facets, the response body will contain data grouped by city:

    "facets": ["city"],
  • order - (optional) Specifies ascending or descending order of rows.

    For example, the following will order the response body largest to smallest by sales:

    "order": [{"sales": "desc"}],
  • limit - (optional) Limits the number of rows in the response.

    For example, the following will limit the response to 50 rows:

    "limit": 50,
  • offset - (optional) Derives the response starting from row n.

    For example, the following will take only the rows starting from row 10:

    "offset": 10,

For further examples of the Geovisualization query language, see the Query Language API Reference.

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