Upload (new)

The sync tasks upload service allows you to upload files directly to an uploadable data source via its sync task ID. This is the recommended way to upload files programmatically.

Finding the sync task ID

Before uploading, find the sync task ID for the data source you want to upload to. Use the ?uploadable=true filter to narrow the results:

HTTP GET /sync_tasks/?uploadable=true

Example

Request: HTTP curl "https://nexus.stellaspark.com/api/v1/sync_tasks/?uploadable=true&token={web_api_token}"

Response: JSON { "count": 1, "next": null, "previous": null, "results": [ { "id": 123, "name": "Dataset export", "owner": "Organization Y", "task_type": "data_source", "uploadable": true, ... } ] }

The id field is the sync task ID used in the upload URL.

Uploading a file

HTTP POST /sync_tasks/{id}/upload/

Upload a new version of the data source. The request must be a multipart form upload with the file in the upload_file field. In case of timeseries measurements, rasters or files (such as photos, documents or videos) the data will be appended to the currently stored data. Any overlapping data will be overwritten with the newest version (this upload). Non-timestamped data (regular spatial datasets) will replace the data currently in Nexus. As such, the upload is considered to contain the 'latest version' of the data source.

Example

Request: HTTP curl -F "upload_file=@C:/path/to/new/dataset.csv" "https://nexus.stellaspark.com/api/v1/sync_tasks/123/upload/?token={web_api_token}"

Response: JSON { "uploader": "Data supplier X", "filename": "dataset.csv", "upload_date": "2021-01-18T11:55:11Z", "download_link": "{temp_download_link}" }

Check the tutorial Uploading data with Python for a full Python example.

Response codes

Code	Meaning
201	File uploaded successfully and processing has started
400	The sync task has no associated data source, or the data source is not marked as uploadable
403	Authentication is missing or the user does not have the Data Supplier role
404	The sync task does not exist
409	The data source is currently being processed; retry once the previous upload has finished

Warning

After uploading your file, Nexus sanitizes the filename for security reasons. Only alphanumeric characters (A-Z, a-z and 0-9), hyphens (-), dots (.) and underscores (_) are retained; any other character will be removed. For example; a filename like evaporation#2020-1-1.tif will become evaporation2020-1-1.tif after upload.

This is generally not a problem, as only the file contents matter. However, if the filename itself carries special meaning that is to be interpreted by Nexus, then this might get lost in the upload process.

If you have files with special characters in the filename and you want to retain them, consider zipping the file before uploading to ensure that the filename stays the same, or rename the files before uploading.

Info

Nexus accepts uploads up to a maximum size of 500 MB. Uploads may be submitted in a compressed archive (such as zip), containing multiple files of the same format. Nexus can process individual JSON files up to a maximum size of 100 MB.