Geovisualization Developer's Guide

Upload External Dataset

An upload external dataset request body is a JSON object sent in the body of a Geovisualization REST API request to upload a dataset file by specifying its URL. See Data Format Guidelines for information about Geovisualization data formats and constraints.

Note that the dataset ID of a previously created dataset is required in the request. This call does not automatically create a dataset.

The supported protocols for the URL are HTTP, HTTPS and SFTP. For SFTP, the URL must point to a directory instead of a file. All csv, csv.gz or zip files in that directory are downloaded and added to the dataset. There can only be one type of file in the directory (csv, csv.gz, or zip). The dataset must have a predefined schema and all files in the directory must conform to it.

Zip files can be encrypted with AES, and the encryption key must be passed in the file_password element.

SFTP requires the username and password to be part of the JSON request body. They can either be given in separate attributes or as part of the URL. Optionally a private key can be passed if required by the SFTP server.

Table 1. Upload External Dataset Request Elements
Element Data Type Mandatory Description
url String Yes URL pointing to a server (HTTP, HTTPS) or a directory (SFTP)
username String No Username required to access the SFTP server
password String No Password required to access the SFTP server
private_key String No Private key optionally required by the SFTP server
file_password String No Password for files contained in AES-encrypted zip files

The code example below shows the data structure sent in a request to create a new dataset by specifying an external source for the data.

  "source": {
    "url": "{some_url}"

An example of a request to an SFTP server:

  "source": {
    "url": "s",
      "username": "bob",
      "password": "bobpw",
      "private_key": "...",
      "file_password": "..."


The same request can be formulated as follows:

      "source": {
        "url": "s"

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