.. _api-guide:

========================
VanderSat API User Guide
========================

Authentication
--------------

We support HTTP basic authentication. Your username and password can be
provided in the URL like this:

::

   https://<USERNAME>:<PASSWORD>@maps.vandersat.com/

Username and password can also be applied in the HTTP headers of the request.


.. TODO: Token based authentication
.. TODO: ~~~~~~~~~~~~~~~~~~~~~~~~~~

.. TODO: check this

Testing authentication
~~~~~~~~~~~~~~~~~~~~~~

To test the VanderSat authentication, the available product list can be requested using:

::

   GET https://maps.vandersat.com/api/v2/products

This will return an JSON object with all products available to this user account
if authentication is successful. e.g.:

::

    {
        "products": [
            {
              "name": "Surface Soil Moisture",
              "max_zoom": 15,
              "min_val": 0,
              "abbreviation": "SM-LN_V001_100",
              "max_val": 1,
              "api_name": "SM-LN_V001_100",
              "default_legend_id": "1",
              "area_allowed": null,
              "time_series_type": "default",
              "unit": "m3/m3"
            }
        ]
    }

or in a python script (with ``requests`` installed) like:

.. code-block:: python

    import requests
    import json

    r = requests.get('https://maps.vandersat.com/api/v2/products',
                     auth=('username', 'password')) # change username and password
    r.raise_for_status()
    product_dict = json.loads(r.content)

Interactive API documentation
-----------------------------

All of our ``v2`` API endpoints support `Swagger/OpenAPI
<https://swagger.io/specification/>`_. The API documentation of these API
endpoints can be accessed at https://maps.vandersat.com/api/v2 .

This page allows you to try out API requests and also serves as the main
documentation of the exact specifications of the supported parameters and return
values.

.. figure:: _images/swagger_screenshot.png
   :alt: Screenshot of interactive API documentation

   Interactive API documentation used for trying out the product listing request


Data access
-----------

Checking access to VanderSat products
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Access to the VanderSat API gives access to a number of
different products, depending on your contract with us.

To discover which products your account has access to perform the following
request:

::

    GET https://maps.vandersat.com/api/v2/products/

This will return a JSON list of all products you can access. The most important
field for each product is the `api_name` since this is the string used for
accessing the data.

An extensive description of all the products can be found in the :ref:`data-products` chapter.

Checking data availability for a VanderSat product
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To check the availability of a product get the ``api_name`` as described in the `Checking
access to VanderSat products`_ section.

Then a request like

::

    GET https://maps.vandersat.com/api/v2/products/<api_name>/availability

will return the product availability for this product. The returned value is a
date and a time but at the moment the time component can be ignored. The local
overpass time for each product is specified in the :ref:`data-products` chapter.

Detailed specifiations about this endpoint can be found in the `Interactive API
documentation`_.

Accessing product data
~~~~~~~~~~~~~~~~~~~~~~

Our data is available in several different ways:

1. Spatial maps in GeoTIFF or NetCDF format
2. Time series of single latitude/longitude point in CSV format
3. Time series of regions of interest in CSV format


.. _API-current:


Current API
~~~~~~~~~~~

.. _API-spatialmaps_current:

Requesting spatial maps
^^^^^^^^^^^^^^^^^^^^^^^

Getting spatial data from the API can be accomplished by calling the URL:

::

    GET https://maps.vandersat.com/api/v2/products/<api_name>/gridded-data

The parameters are documented in the `Interactive API documentation`_. Since
this API is asyncronous the return value is a process uuid under which the data
will be available as soon as it is processed. Getting the data once the request
is processed is explained at :ref:`API-get-data_current`

Examples: gridded-data
######################

Get L-band soil moisture for May 2018 in GeoTIFFs:

::

    GET https://maps.vandersat.com/api/v2/products/SM-LN_V001_100/gridded-data?lon_min=3&lon_max=7&lat_min=51&lat_max=53&start_date=2018-05-01&end_date=2018-05-31&format=gtiff&zipped=false


Get Land-surface temperature for 2017 zipped in NetCDF:

::

    GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/gridded-data?lat_min=51&lat_max=53&lon_min=3&lon_max=7&start_date=2017-01-01&end_date=2017-12-31&format=netcdf4&zipped=true

.. _API-time-series_current:

Requesting time-series
^^^^^^^^^^^^^^^^^^^^^^

Getting time-series from the API can be accomplished by calling one of the following URLs:

::

    GET https://maps.vandersat.com/api/v2/products/<api-name>/point-time-series

for single point time-series or

::

    GET https://maps.vandersat.com/api/v2/products/<api-name>/roi-time-series

for region averaged time-series. For time-series, one can request only one file
per request containing the time-series of a single product.

The parameters are documented in the `Interactive API documentation`_. Since
this API is asyncronous the return value is a process uuid under which the data
will be available as soon as it is processed. Getting the data once the request
is processed is explained at :ref:`API-get-data_current`


Examples: time-series
#####################

Get L-band soil moisture time-series between april 2015 until april 2019 at (lat, lon) = (51.386, 4.647):

::

    GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/point-time-series?start_time=2015-04-01&end_time=2019-03-31&lat=51.386&lon=4.647&format=csv&avg_window_days=0&include_masked_data=false&climatology=false

Same, but also include; `a 15 day moving average`, `masked data` (marked as invalid),
`the climatology` based on the average column, and the `derived root zone` calculation
for a given T=10 days and output as json:

::

    GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/point-time-series?start_time=2015-04-01&end_time=2019-03-31&lat=51.386&lon=4.647&format=json&avg_window_days=20&include_masked_data=true&climatology=true&exp_filter_t=20

Finally, downloading an area-averaged time-series for an uploaded region:

::

    GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/roi-time-series?start_time=2015-04-01&end_time=2019-03-31&roi_id=4325


.. _API-get-data_current:

Retrieving the data
^^^^^^^^^^^^^^^^^^^

A return value of a gridded data request or a <point-/roi->time-series request could be e.g.:

::

    {
      "url": "api/v2/api_requests/83833aae-1376-4288-b7c7-3e99af57e29f/status",
      "message": "Download request received",
      "uuid": "83833aae-1376-4288-b7c7-3e99af57e29f"
    }


The status of the API request can now be queried using:

::

    GET https://maps.vandersat.com/api/v2/api_requests/83833aae-1376-4288-b7c7-3e99af57e29f/status


Which would return either the progress for ``Scheduled`` or ``Processing`` requests such as:

::

    {
      "scheduled_dt": "2019-06-04T11:59:56.409228",
      "percentage": 0,
      "processing_status": "Scheduled"
    }

or something like the following for an API request that is
``Ready``:

::

    {
      "scheduled_dt": "2019-01-24T17:18:45.810523",
      "started_dt": "2019-01-24T17:19:07.409485",
      "processing_status": "Ready",
      "finished_dt": "2019-01-24T17:19:12.698098",
      "data": [
        "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-02T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
        "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-03T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
        "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-04T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
        "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-05T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
        "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-06T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
        "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-07T000000_6.481934_52.669720_8.602295_51.710012_83833.tif"
      ],
      "percentage": 100
    }


The data can then be downloaded by calling ``/download`` on each of the produced
files, e.g.:

::

    GET https://maps.vandersat.com/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-02T000000_6.481934_52.669720_8.602295_51.710012_83833.tif/download



.. _API-download_example:


Scripting example: Python
^^^^^^^^^^^^^^^^^^^^^^^^^

This code example shows a minimal example to download the files contained in one request.
For it to work, one should install the `requests <https://pypi.org/project/requests/>`_ package through pip.
Change the `authentication`, the `request uri` and the `output folder` to make the script work

    ``$ pip install requests``

or through conda

    ``$ conda install -c conda-forge requests``

.. code-block:: python

    import os
    import time

    import json
    import requests


    def _get_content(uri, auth):
        r = requests.get(uri, auth=auth)
        r.raise_for_status()
        response = json.loads(r.content)
        return response


    def submit_job(api_call, auth):
        response = _get_content(api_call, auth)
        uuid = response['uuid']
        return uuid


    def _get_status(uuid, auth):
        status_uri = ('https://maps.vandersat.com/api/v2/'
                     'api-requests/{uuid}/status'.format(uuid=uuid))
        response = _get_content(status_uri, auth)
        return response


    def get_data(uuid, auth):
        status = _get_status(uuid, auth=auth)
        while status['percentage'] < 100:
            print('Percentage = {}'.format(status['percentage']))
            time.sleep(5)  # wait 5 seconds before requesting new status
            status = _get_status(uuid, auth=auth)
        print('Finished')
        data = status['data']
        return data


    def download_files(files, auth, out_folder=''):
        for fn_link in files:
            file_path = os.path.join(out_folder, os.path.split(fn_link)[1])
            file_uri = ('https://maps.vandersat.com/{fn_link}/download'.format(fn_link=fn_link))
            r = requests.get(file_uri, verify=True, stream=True, auth=auth)
            r.raise_for_status()
            with open(file_path, 'wb') as f:
                for chunk in r.iter_content(1024):
                    f.write(chunk)


    if __name__ == '__main__':

        auth = ('username', 'password')  # Change username and password
        api_call = ('https://maps.vandersat.com/api/v2/'
                    'products/SM-C1N_V001_100/gridded-data?'
                    'lat_min=51.5&lat_max=52.5&lon_min=4&lon_max=5&'
                    'start_date=2012-10-01&end_date=2012-10-03&'
                    'format=gtiff&zipped=false')  # Change desired request
        out_folder = ''  # set output folder (has to exist)

        uuid = submit_job(api_call, auth=auth)
        files = get_data(uuid, auth=auth) # waits for processing to finish
        download_files(files, auth=auth, out_folder=out_folder)




.. _API-naming_current:

File naming
~~~~~~~~~~~

gridded data
^^^^^^^^^^^^

The file naming convention of the returned `gridded-data` file(s) is the following:

::

``<product-api-name>_<date:YYYY-MM-DDTHHMMSS>_<lon_min:.6f>_<lat_max:.6f>_<lon_max:.6f>_<lat_min:.6f>_<uuid4_short>.<ext>``

Or for `zipped` files:

::

``<product-api-name>_<start_date:YYYY-MM-DDTHHMMSS>_<end_date:YYYY-MM-DDTHHMMSS>_<lon_min:.6f>_<lat_max:.6f>_<lon_max:.6f>_<lat_min:.6f>_<uuid4_short>.<ext>``


with:

- ``<product-api-name>`` as described in :ref:`product-names`.
- ``<*:YYYY-MM-DDTHHMMSS>`` sensing date of data file in datetime-format e.g. ``2018-12-07T000000``
- ``<lon_min:.6f>`` Minimum longitude rounded to 6 digits after the comma.
- ``<lat_max:.6f>`` Maximum latitude rounded to 6 digits after the comma.
- ``<lon_max:.6f>`` Maximum longitude rounded to 6 digits after the comma.
- ``<lat_min:.6f>`` Minimum latitude rounded to 6 digits after the comma.
- ``<uuid4_short>`` The first 5 characters of the API request UUID.
- ``<ext>`` File extension depending on requested data format (``tif``, ``nc`` or ``zip``)


.. note::

    Although datetime is specified, currently only the sensing date is reflected
    in the sensing-date. By default, the time is always ``T000000``

time-series
^^^^^^^^^^^^

The file naming convention for `point-time-series` is the following :

::

``ts_<product-api-name>_<start_time:YYYY-MM-DDTHHMMSS>_<end_time:YYYY-MM-DDTHHMMSS>_<lon:.6f>_<lat:.6f>_<uuid4_short>.<ext>``

and for `roi-time-series` :

::

``roi-ts_<product-api-name>_<start_time:YYYY-MM-DDTHHMMSS>_<end_time:YYYY-MM-DDTHHMMSS>_<roi-id:d>_<uuid4_short>.<ext>``

with:

- ``<product-api-name>`` as described in :ref:`product-names`.
- ``<*:YYYY-MM-DDTHHMMSS>`` start- and end-datetime e.g. ``2018-12-07T000000``
- ``<lon:.6f>`` Minimum longitude rounded to 6 digits after the comma.
- ``<lat:.6f>`` Maximum latitude rounded to 6 digits after the comma.
- ``<roi-id:d>`` region-id as an integer value.
- ``<uuid4_short>`` The first 5 characters of the API request UUID.
- ``<ext>`` File extension depending on requested data format (``csv``, ``json``)





Version 1 API
~~~~~~~~~~~~~

.. attention::

    This API version is deprecated in will be removed in the future.
    Please use the asynchronous :ref:`API-current` endpoints.


.. _API-spatialmaps_v1:

Requesting spatial maps
^^^^^^^^^^^^^^^^^^^^^^^

Getting spatial data from the API can be accomplished by calling the URL:

::

   GET https://maps.vandersat.com/api/v1/dam/get-area

with the following parameters given in the URL string

.. table:: Parameters supported by ``get-area`` request

    ============ =================================================== =============
    parameter    meaning                                             required
    ============ =================================================== =============
    product      product ``api_name`` as given in the product list   True
    lat_max      maximum latitude of the requested area (-90, +90)   True
    lat_min      minimum latitude of the requested area (-90, +90)   True
    lon_max      maximum longitude of the requested area (-180,      True
                 +180)
    lon_min      minimum longitude of the requested area (-180,      True
                 +180)
    date         date of the requested product (YYYY-MM-DD)          True
    file_format  ``geotiff`` (default) or ``netcdf``                 False
    metadata     | Boolean value if downloaded data should           False
                 | include a metadata XML file. If set to ``true``
                 | (default) the returned file will be a zip file
                 | containing both the data file and the XML file.
    ============ =================================================== =============

.. note::

    Since this is an synchronous API request it can time out if the requested
    area is too large (should not happen for areas smaller than 10x10 degrees).
    Please request a smaller area if that happens to you.
    Please use the :ref:`API-spatialmaps_current` endpoint to prevent such a time-out.


Returned dataset specifications
###############################

The syntax used for the filenames follows the below explained pattern:

``<PRODUCTNAME>_<YYYY-MM-DD>_<TOPLEFT>_<BOTTOMRIGHT>.<EXT>`` with:

-  ``<PRODUCTNAME>`` being then ``api_name`` of the product
-  ``<YYYY-MM-DD>`` being the date of the requested product
-  ``<TOPLEFT>`` being the coordinate of the top-left latitude longitude
   corner for the area in format NXXXEXXX (with N for north and S for
   south, E for East and W for west)
-  ``<BOTTOMRIGHT>`` being the coordinate of the bottom-right latitude
   longitude corner for the area in format NXXXEXXX (with N for north
   and S for south, E for East and W for west)
-  ``<EXT>`` being ``.tif``, ``.nc``, ``.zip`` or ``.xml``.

.. note::

   The coordinates in the returned filenames are rounded to the nearest full
   degrees equal to or overlapping the requested box.
   Please be aware of this limitation when requesting different small
   areas in the same 1x1 degree bounding box

The Soil Moisture file with ``api_name`` ``SM-SHORT-100`` corresponding to the
area between latitude 56.0 North, longitude 2.0 East and latitude 52.0 North,
longitude 6.0 East for the date of the 20th March 2017 will have the filename:
``SM-SHORT-100_2017-03-20_N056E002_N052E006.tif``.

If the metadata is requested the returned file will be named
``SM-SHORT-100_2017-03-20_N056E002_N052E006.zip`` which will contain the
aforementioned ``.tif`` or ``.nc`` file and an ``.xml`` file with the same
filename.

The contents of the ``.xml`` file follow this structure:

.. code-block:: xml

    <metadata>
      <product name="SM-SHORT-100 2017-03-20 00:00:00">
        <stats>
          <minimum>
            <min_value>27.0</min_value>
          </minimum>
          <maximum>
            <max_value>99.0</max_value>
          </maximum>
          <mean_value>37.132845066</mean_value>
          <standard_deviation>3.76820974112</standard_deviation>
        </stats>
        <lon_min>2.0</lon_min>
        <lat_max>6.0</lat_max>
        <projection>GEOGCS[&#34;WGS 84&#34;,DATUM[&#34;WGS_1984&#34;,SPHEROID[&#34;WGS 84&#34;,6378137,298.257223563,AUTHORITY[&#34;EPSG&#34;,&#34;7030&#34;]],AUTHORITY[&#34;EPSG&#34;,&#34;6326&#34;]],PRIMEM[&#34;Greenwich&#34;,0],UNIT[&#34;degree&#34;,0.0174532925199433],AUTHORITY[&#34;EPSG&#34;,&#34;4326&#34;]]</projection>
        <level>3</level>
        <lon_max>6.0</lon_max>
        <lat_min>52.0</lat_min>
      </product>
      <legal>
        <legal_notice>Contains modified ESA Copernicus Sentinel data 2015-2018</legal_notice>
        <legal_notice>Contains modified NASA AQUA/AMSRE data 2002-2011</legal_notice>
        <legal_notice>Contains modified JAXA GCOM-W1/AMSR2 data 2012-2018</legal_notice>
        <legal_notice>Contains modified NASA SMAP data 2015-2018</legal_notice>
      </legal>
      <copyright>
        <copyright_notice>All rights reserved - VanderSat 2018</copyright_notice>
      </copyright>
    </metadata>

Example requests
################

An example of a full URL to request a GeoTIFF file of the Soil Moisture product
with ``api_name`` ``SM-SHORT-100`` for the area inside the bounding box
``[52,2,56,6]`` at the date of 20 March 2017 including metadata would be:

::

   https://maps.vandersat.com/api/v1/dam/get-area?lat_max=56&lon_min=2&lat_min=52&lon_max=6&date=2017-03-20&product=SM-SHORT-100&metadata=true

An example to have the VanderSat API return a NetCDF file:

::

   https://maps.vandersat.com/api/v1/dam/get-area?lat_max=56&lon_min=2&lat_min=52&lon_max=6&date=2017-03-20&product=SM-SHORT-100&metadata=false&file_format=netcdf


.. _API-time-series_v1:

Requesting time series
^^^^^^^^^^^^^^^^^^^^^^

Getting time series for a point from the API can be accomplished by calling the
URL:

::

   GET https://maps.vandersat.com/api/v1/dam/get-time-series

with the following parameters given in the URL string


.. table:: Parameters supported by ``get-time-series`` request

    ============ =============================================================== =============
    parameter    meaning                                                         required
    ============ =============================================================== =============
    products     | product ``api_name`` as given in the product list             True
                 | in the format ``["api_name"]``. Needs to be url
                 | encoded: e.g. ``[“SM-SHORT-100”]->%5B%22SM-SHORT-100%22%5D``
                 | multiple products should be separated by a comma: e.g.
                 | ``["api_name1", "api_name2]->
                 | %5B%22api-name1%22%2C%22api-name2%22%5D``
    lat          latitude of the requested point (-90, +90)                      True
    lon          longitude of the requested point (-180, +180)                   True
    date_init    date of the start of the requested time series                  True
                 (YYYY-MM-DD)
    date_end     date of the end of the requested time series                    True
                 (YYYY-MM-DD)
    T            | T value (in days) for derived root zone soil                  False
                 | moisture derivation. When this parameters is
                 | provided an extra column will be added to the
                 | CSV file with the root zone soil moisture.
    metadata     | boolean value if downloaded data should                       False
                 | include a metadata XML file. If set to ``true``
                 | the returned file will be a zip file containing
                 | both the data file and the XML file. (default = ``false``)
    ============ =============================================================== =============

.. note::

    Since this is an synchronous API request it can time out if the requested
    time series is too long. Please request a shorter time series or use the
    :ref:`API-time-series_current` endpoint which cannot time-out since it is
    asynchonous.

Returned dataset specifications
###############################

Returned time series data follows the following naming conventions:

``series_<LAT>_<LON>_<DATE_INIT>_<DATE_END>.<EXT>`` with:

-  ``<LAT>`` is the latitude as specified in the API request
-  ``<LON>`` is the latitude as specified in the API request
-  ``<DATE_INIT>`` requested start date of the time series in format ``YYYY-MM-DD``.
-  ``<DATE_END>`` requested end date of the time series in format ``YYYY-MM-DD``.
-  ``<EXT>`` being ``.csv``, ``.zip`` or ``.xml``.

If metadata is ``False`` the only a ``.csv`` file is returned. If the metadata
is requested then a ``.zip`` file containing both the ``.csv`` and the ``.xml``
file is returned.

Columns in this csv file are separated by a comma. First column contains the
date, second column value of the requested product and third column the running
average signal using a centered +/- 20 days window function. See
:ref:`example-request-time-series` for an example of the format.

.. _example-request-time-series:

Example requests
################

An example of a full url to request a csv file for the time series of the Soil
Moisture product with ``api_name`` ``SM-LN_V001_100`` for the location of
``latitude=52.11``, ``longitude=4.823`` from the date of 1st January 2016 to the
30th June of 2016 including metadata would be:

::

   https://maps.vandersat.com/api/v1/dam/get-time-series?lat=52.11&lon=4.823&date_init=2016-01-01&date_end=2016-04-30&products=%5B%22SM--LN_V001_100%22%5D&metadata=true

The returned CSV file will have the following format:

.. code::

   date,SM-SHORT-100,SM-SHORT-100_AVG
   2016-01-01,0.47,0.4800000000000001
   2016-01-02,,0.47090909090909094
   2016-01-03,0.44,0.4625000000000001
   2016-01-04,,0.4625000000000001
   2016-01-05,0.48,0.4630769230769231
   2016-01-06,0.48,0.4642857142857143

The XML file would be the following:

.. code-block:: xml

    <metadata>
      <product name="SM-SHORT-100 time series at latitude: 52.11 longitude: 4.823">
        <stats>
          <minimum>
            <min_value>0.31</min_value>
            <min_value_date>2016-04-21 00:00:00</min_value_date>
          </minimum>
          <maximum>
            <max_value>0.59</max_value>
            <max_value_date>2016-01-30 00:00:00</max_value_date>
          </maximum>
          <mean_value>0.44231884057971016</mean_value>
          <standard_deviation>0.06354605604784183</standard_deviation>
        </stats>
        <date_init>2016-01-01 00:00:00</date_init>
        <date_end>2016-04-30 00:00:00</date_end>
        <latitude>52.11</latitude>
        <longitude>4.823</longitude>
      </product>
      <legal>
        <legal_notice>Contains modified ESA Copernicus Sentinel data 2015-2018</legal_notice>
        <legal_notice>Contains modified NASA AQUA/AMSRE data 2002-2011</legal_notice>
        <legal_notice>Contains modified JAXA GCOM-W1/AMSR2 data 2012-2018</legal_notice>
        <legal_notice>Contains modified NASA SMAP data 2015-2018</legal_notice>
      </legal>
      <copyright>
        <copyright_notice>All rights reserved - VanderSat 2018</copyright_notice>
      </copyright>
    </metadata>


Region of interests
-------------------

.. TODO: where to we explain the basic assumptions that our Viewer/API has about data access, area allowed, Roi's etc?

Regions of Interest (ROI) are regions that are of particular interest. It is possible
to define these regions of interest by drawing or uploading a shapefile in the
Viewer (:ref:`ROI`). It is also possible to define an ROI using the API.

The management of ROIs via the api can be performed via the https://maps.vandersat.com/api/v2/rois endpoint.
Please see the `Interactive API documentation`_ for more information.

Time series for a region of interest
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If an ROI is defined and you know the ``roi_id`` you can request the area
representative time series for the ROI. This is the area mean for most products.

The base url for a ROI time series request is:

::

   GET https://maps.vandersat.com/api/v1/dam/get-roi-time-series

with the following parameters given in the URL string

.. table:: Parameters supported by ``get-roi-time-series`` request

    ============ =================================================== =============
    parameter    meaning                                             required
    ============ =================================================== =============
    roi          ROI id as returned by the roi listing or as seen    True
                 in the viewer.
    products     | product ``api_name`` as given in the product list True
                 | in the format ``["api_name"]``. Needs to be url
                 | encoded: e.g.
                   ``[“SM-SHORT-100”]->%5B%22SM-SHORT-100%22%5D``
    date_init    date of the start of the requested time series      True
                 (YYYY-MM-DD)
    date_end     date of the end of the requested time series        True
                 (YYYY-MM-DD)
    T            | T value (in days) for derived root zone soil      False
                 | moisture derivation. When this parameters is
                 | provided an extra column will be added to the
                 | CSV file with the root zone soil moisture.
    metadata     | boolean value if downloaded data should           False
                 | include a metadata XML file. If set to ``true``
                 | the returned file will be a zip file containing
                 | both the data file and the XML file.
    ============ =================================================== =============


Returned dataset specifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Returned time series data follows the following naming conventions:

``series_<ROI-NAME>_<DATE_INIT>_<DATE_END>.<EXT>`` with:

-  ``<ROI-NAME>`` The name of the region of interest.
-  ``<DATE_INIT>`` requested start date of the time series in format ``YYYY-MM-DD``.
-  ``<DATE_END>`` requested end date of the time series in format ``YYYY-MM-DD``.
-  ``<EXT>`` being ``.csv``, ``.zip`` or ``.xml``.

If metadata is ``False`` the only a ``.csv`` file is returned. If the metadata
is requested then a ``.zip`` file containing both the ``.csv`` and the ``.xml``
file is returned.

Columns in this csv file are separated by a comma. First column contains the
date, second column value of the requested product and third column the running
average signal using a centered +/- 20 days window function. See
:ref:`example-roi-time-series` for an example of the format.

.. _example-roi-time-series:

Example requests
^^^^^^^^^^^^^^^^

An example of a full url to request a csv file for the time series of the Soil
Moisture product with ``api_name`` ``SM-SHORT-100`` for the region of interest with
``id 18`` from the date 1 January 2016 to 30 June 2016 including metadata would
be:

::

   https://maps.vandersat.com/api/v1/dam/get-roi-time-series?roi=18&date_init=2016-01-01&date_end=2016-04-30&products=%5B%22SM-SHORT-100%22%5D&metadata=true

The returned CSV file will have the following format:

.. code::

   date,SM-SHORT-100,SM-SHORT-100_AVG
   2016-01-01,0.4184,0.42847272727272734
   2016-01-02,,0.42847272727272734
   2016-01-03,0.3457,0.41830833333333334
   2016-01-04,,0.41830833333333334
   2016-01-05,0.3706,0.4160615384615385

The XML file would be the following:

.. code-block:: xml

    <metadata>
    	<product name="SM-SHORT-100 time series for Region of Interest 18 : Kennemer duinen">
    		<stats>
    			<minimum>
    				<min_value>0.2084</min_value>
    				<min_value_date>2016-04-21 00:00:00</min_value_date>
    			</minimum>
    			<maximum>
    				<max_value>0.6257</max_value>
    				<max_value_date>2016-01-14 00:00:00</max_value_date>
    			</maximum>
    			<mean_value>0.37532714285714297</mean_value>
    			<standard_deviation>0.0733885411869661</standard_deviation>
    		</stats>
    		<date_init>2016-01-01 00:00:00</date_init>
    		<date_end>2016-04-30 00:00:00</date_end>
    		<roi_name>Kennemer duinen</roi_name>
    		<roi_id>18</roi_id>
    	</product>
    	<legal>
    		<legal_notice>Contains modified ESA Copernicus Sentinel data 2015-2018</legal_notice>
    		<legal_notice>Contains modified NASA AQUA/AMSRE data 2002-2011</legal_notice>
    		<legal_notice>Contains modified JAXA GCOM-W1/AMSR2 data 2012-2018</legal_notice>
    		<legal_notice>Contains modified NASA SMAP data 2015-2018</legal_notice>
    	</legal>
    	<copyright>
    		<copyright_notice>All rights reserved - VanderSat 2018</copyright_notice>
    	</copyright>
    </metadata>

Account management
------------------

:Changing username and password: Username and password are supplied to you
    via separate channels. These credentials can most easily be changed in the VanderSat Viewer under `User settings`
    in the top right corner


Contact
-------

:Address: VanderSat Data Service Wilhelminastraat 43a, 2011 VK, Haarlem, The
    Netherlands
:E-mail: support@vandersat.com
:Standard office hours: 9:00 - 17:00 (CET)
    }

or in a python script like: