Data Export API

With the Data Export API, you can download your channel data directly by simply typing a URL into the address bar of your browser. The Data Export API allows you to customize which data you want to download as well as how your data is saved. It provides flexible options for specifying channels, start and end dates, formats and data types, making it ideal for exporting large amounts of data all at once.

How it works: The URL

The Data export API provides direct access to your data via a URL in the following format:

https://live.zednet.co.za/index.php/export_bulk_data/get_data/[api-key]/[channel-id]/[start-date]/[end-date]/[format]/[data-type]

For example, if you wanted to get all the data for channel 222 and channel 223 starting from 19 October 2012 and ending 20 October 2012, and save the data in CSV format you would use the following URL:

https://live.zednet.co.za/index.php/export_bulk_data/get_data/lpGpBx-rf/222-223/2012-10-19/2012-10-20/csv/0

The URL can be divided into six chunks, each chunk is easy to understand and using the example above we will explain each of these chunks in detail.

The Base Address

The base address makes up the first part of the URL, namely:

https://live.zednet.co.za/index.php/export_bulk_data/get_data/

The base address will always be the same. There is nothing you need to change or insert into the base address as it is just used to access the Data Export API.

API Key

In order to gain permission to use the Data Export API, you must provide an API key.
The API key comes directly after the base address. In our working example our API key is lpGpBx-rf.

Each client that uses the Data Export API will need to create a new user, with permission level of 'client-user', and allocate that user a random API key. See Admin Interface->Users for instructions on how to create users and assign them an API key.

Note: When you use the Data Export URL you are automatically logged in to Zednet as the user who owns that API key, even if you were already logged in as a different user.

Channel ID

The Channel ID chunk of the Data Export URL determines which subset of the client's channels are exported.
There are three easy ways to specify which channel(s) you would like to export.

1. Provide a list of Zednet channel ID's separated by the "-" character, for example: /123-345-14-16/.
2. Provide single Zednet channel ID, for example: /123/.
3. Simply use 0 (zero) instead of providing channel ID's to export ALL the client's channels: /0/.

In our working example, we have used the first option to request channel IDs 222 and 223, separated by "-" characters: /222-223/.

Start and End Date

After the Channel ID chunk the start date is specified, followed by the end date.
This is simply a date formatted as year-month-day for both the start date and the end date.

In our working example we are only interested in channel data starting from the 19th October 2012 and ending on the 20th October 2012, specified as: /2012-10-19/2012-10-20/.

Format

This chunk of the URL allows you to specify the format in which you would like to export your data.
Currently, we offer data exports in the following 4 formats: CSV, Excel, SHEF and Hydstra.

You can choose which format you want your data to be exported in by simply specifying the name of one of the supported formats. In our working example we wanted our data to be saved in CSV format, specified by the /csv/ chunk of the URL. If you would prefer your data in SHEF format, you would simply replace /csv/ with /shef/.

Note: Channels that are exported in CSV or Hydstra format are identified by their 'reference' provided by the client. If there is no 'reference' for the channel, Zednet's channel ID is used.
Channels that are exported in SHEF format are identified by a combination of Site Name and SHEF code.

Data Type

The last chunk of the URL allows you to export limited types of data, using Zednet's data type ID's.
There are three easy ways to specify different data types:

1. Provide a list of type ID's separated by the "-" character, for example: /7-8-12/
2. Provide single type ID: /7/
3. To export ALL types use /0/ or just leave it blank

Visit our Data Type IDs page for a full list of available data types and their corresponding IDs.

Note: The SHEF export does not export all types of data - only those that have been allocated a SHEF code.
In brief, these data type IDs are:
7: river level (up and downstream)
8: dam or reservoir level
11: precipitation accumulator
12: precipitation
16: ph value
22: dissolved oxygen in ppm
24: water conductance
28: turbidity

Custom Cases

There are two "custom" cases that need to be accommodated.

1. Backup channels
Channels are SHEF exported on site ID and SHEF code. However, there are also backup channels, meaning in some cases we would have two channels with same shef code, and same site name. For these, the export appends a "B" to the end of the site name. To indicate a backup channel, add [backup] anywhere in the notes field for the channel.

2. Derived/disabled channels
Since not all data types are exported for SHEF, all derived formats are skipped.
A user may however still want to disable a particualr channel for bulk export.
To do this, add [noexport] anywhere in the notes field of the channel.

Use Case

This all sounds very complicated, but in practice it's actually very simple.
A user would simply have a saved URL for each regional client - and would only change the dates each time new data is exported.

So, in our working example, if you wanted to export the data from the 10th of December to 13th of December (instead of for October) you would simply change the URL to:

https://live.zednet.co.za/index.php/export_bulk_data/get_data/lpGpBx-rf/222-223/2012-12-10/2012-12-13/csv/0

Or if you decided you wanted to export all the channels instead of just two channels, you would change the url to:

https://live.zednet.co.za/index.php/export_bulk_data/get_data/lpGpBx-rf/0/2012-12-10/2012-12-13/csv/0