Geovisualization Developer's Guide

Datasets

Use this resource to upload, retrieve, update and delete datasets.

A dataset represents the raw data you upload into your Geovisualization account. The import process consists of three steps: create an empty dataset, upload the actual content, and provide a specification or schema for the dataset. You can query the progress of uploading data.

For more information on valid data formats, see Data Format Guidelines.

The table below summarizes the available endpoints supported by the datasets resource along with their HTTP methods and responses.

Table 1. Datasets Endpoints
Resource Functions Method Response
/datasets List available datasets GET 200 OK with a response object containing a list of datasets
Create an empty dataset with a request body POST 201 Created and a response object with the dataset ID
/datasets?with_column... List all datasets that match the column names and / or types that you specify in the URL. See the examples. GET 200 OK with a response object containing a list of datasets reflecting the filter criteria
/datasets/{DATASET_ID} Fetch dataset metadata GET 200 OK if successful and a response object for the dataset
Upload data to a dataset using a form field of type file/text indicating the file to upload POST 200 OK if successful and a response object with the dataset ID
Populate data to a dataset with a request body specifying a URL indicating the external source of the data POST 202 Accepted if successful and a response object with the dataset ID
Delete the dataset with the specified dataset ID DELETE 200 OK if successful and a response object with the dataset ID
/datasets/{DATASET_ID}/data Reset dataset to clear any entries from the dataset and reset it to empty (no files, no schema) DELETE 200 OK if successful and a response object for the dataset
/datasets/{DATASET_ID}/geocode Create geocoordinates based on an address element in an existing dataset. The request body contains instructions for the geocoding job. You can create a geocode from elements such as:
  • streets
  • postcodes
  • city names
  • countries

Geocoding jobs can take considerable time to complete.

POST 202 Accepted if successful and a response body containing the job status
/datasets/{DATASET_ID}/georeference Create a georeference job with a request body containing instructions on how to translate lat-lon coordinates to a geographical location POST 202 Accepted if the job has been created and is pending; and 200 OK if the job is identical to one that has already been run on the dataset (the columns will already exist and can be used in queries immediately); with a response body containing the job status
/datasets/{DATASET_ID}/permissions Fetch the permissions for a dataset. GET 200 OK if successful and a response body for the permissions.
/datasets/{DATASET_ID}/permissions Create the permissions for a dataset with a request body specifying a role and an array of user IDs. See Datasets Permissions for more details. POST 200 OK if successful and a response body of each role and the users with that role.
/datasets/{DATASET_ID}/permissions Delete the permissions for a dataset with a request body specifying a role and an array of user IDs. See Datasets Permissions for more details. DELETE 200 OK if successful and a response body of each role and the remaining users with that role.
/datasets/{DATASET_ID}/progress Fetch the progress of a dataset loading (applies only for datasets populated from an external source) GET 200 OK if successful and a response body for the job status if the job is still running. If the job is complete the following is reported in the response body: "There are no downloads in progress for this dataset"
/datasets/{DATASET_ID}/projections Reproject the coordinates in a dataset with a request body specifying the projection specifications for the source and target columns POST 200 OK if successful and a response body for the job status
/datasets/{DATASET_ID}/sample Fetch sample data GET 200 OK if successful and a response object containing a subset of the data (the first 30 rows)
/datasets/{DATASET_ID}/schema Fetch the schema of the dataset GET 200 OK if successful and a response object for the content schema
Modify the dataset schema by column with a request body specifying the schema. You can change but not delete columns in a dataset. POST 200 OK if successful and a response body for the new schema
Rewrite the dataset schema. This can only be done on a dataset that is empty, and it replaces the entire schema. The request body format depends on the dataset. PUT 200 OK if successful and a response object for the new schema

Examples

Examples of filtering datasets by column names and types:

GET https://datalens.api.here.com/v1/datasets?with_column={col1:coltyp1}&with_column={col2:coltyp2}&...
GET https://datalens.api.here.com/v1/datasets?with_column_only={col1:coltyp1}&with_column_only={col2:coltyp2}&...

Examples of filtering datasets by column names only:

GET https://datalens.api.here.com/v1/datasets?with_column={col1}&with_column={col2}&...
GET https://datalens.api.here.com/v1/datasets?with_column_only={col1}&with_column_only={col2}&...

Request Parameters

The table below documents the mandatory request parameters required by this resource.

Note: All the parameters below are required for authentication. For more information about authentication and authorization in general, see the authentication related topics under Getting Started.
Table 2. Request Parameters
Parameter Datatype Description
app_id String A 20-byte Base64 URL-safe encoded string used for the authentication of the client application
app_code String A 20-byte Base64 URL-safe encoded string used for the authentication of the client application
access_token String A temporary string used for authentication. Tokens are valid for one hour.

We recommend that the token be included in the HTTP Header when sending requests. For more information on setting up the access_token in the HTTP Header, see Authentication with Postman.

The table below documents the optional request parameters that can be used by this resource.

Table 3. Optional Request Parameters
Parameter Datatype Description
with_column String Specfies to search for datasets including at least the columns listed, by name or by type, but the datasets can have additional columns that are not specified in the filter. The supported columns types are date, number, and string.

Examples:

Return all datasets that have at least two numerical columns called lat and lon:

GET https://datalens.api.here.com/v1/datasets?&with_column=lat:number&with_column=lon:number

Return all datasets that have at least two columns lat and lon:

GET https://datalens.api.here.com/v1/datasets?&with_column=lat&with_column=lon
with_column_only String Specifies to search for datasets that contain only the columns specified in the filter, by name or by type. The supported columns types are date, number, and string.

Example:

Return all datasets that have only the four columns lat, lon, Src and region:

GET https://datalens.api.here.com/v1/datasets?&with_column_only=lat&with_column_only=lon&with_column_only=Src&with_column_only=region

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.