Data Lens Developer's Guide

Using Dynamic Parameters

Data Lens visualizations based on large datasets can require substantial data processing. You can optimize your app by defining your query to fetch the data dynamically, that is, according to the parameters included in the query's GET request URL. In this way, instead of retrieving all data in one action, you only fetch the data required to render the visualization for the end-user's current viewport.

Using dynamic parameters, the Data Lens REST API filters the dataset server-side with respect to the parameter values included in the request URL, and returns only the data relevant to those parameters.

Note that server-side filtering staggers the data retrieval; it does not create animation. Dynamic parameters are more suitable for larger datasets where animation is not the goal of the visualization.

You can view a code example which describes a heat map that displays mobile network events in the US. In this example, we filter the data using a query with dynamic parameters.

In the following section, we walk through the reasoning of using dynamic parameters and how server-side filtering can be included in queries.


To demonstrate dynamic parameters, we will consider a visualization which includes a slider that sets a magnitude range to filter earthquake events represented on a map. Instead of getting all rows from the server and filtering client-side, we will call a new request for each manipulation of the slider, and only retrieve the immediately required data rows.

The following query uses dynamic parameters to set the ranges of earthquake magnitudes:

   "metrics": ["Lat","Lon","Magnitude","Depth","Region","Datetime"],
   "facets": [],
   "version": 0.3,
   "namespace": {
     "min_mag": {"source": [{"$input": "min"}]},
     "max_mag": {"source": [{"$input": "max"}]}
   "filters": [
         {"Magnitude": {"$gte": {"$reference": "min_mag"}}},
         {"Magnitude": {"$lte": {"$reference": "max_mag"}}}
   "order": [{"Magnitude": "asc"}],
   "dataset": "90af668484394fa782cc103409cafe39"

Note the namespace property:

"namespace": {
  "min_mag": {"source": [{"$input": "min"}]},
  "max_mag": {"source": [{"$input": "max"}]}

This code includes two variables, min_mag and max_mag, which are used like column names from the dataset but are set by way of parameters in the request URL. So, if you GET the following:[query_id]/data?min=0&max=5&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

the Data Lens REST API will set the variables min_mag to 0 and max_max to 5 when evaluating the query.

Note also the filters property. This is a filter mechanism that includes a reference to the variables above:

"filters": [
    {"Magnitude": {"$gte": {"$reference": "min_mag"}}},
    {"Magnitude": {"$lte": {"$reference": "max_mag"}}}

This filter restricts the output data to rows with Magnitude between min_mag and max_max (inclusive). Therefore, using the request URL above, this would restrict the data returned to that where Magnitude is between 0 and 5. (The SQL equivalent to this is "WHERE Magnitude>=0 AND Magnitude <=5".)

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