.. _services_onlinedata:

Online Data Service
===================

Within windPRO you can download a vast amount of online data ranging from mesoscale wind data to terrain information.
The OnlineDataService gives access to downloading online data in windPRO.
You need to have an internet connection to use these service as data is accessed from EMD's servers.
The example code below activates the online data service and prints all DataTypes that are available from this service.
A data type refers to the type of data, e.g. "ODSClimate" for mesoscale climate data, "ODSRoughnessGridToLine" for roughness maps derived from gridded data, translated to roughness lines.

.. code-block:: python

    import os
    from windproapi.utils import get_windpro_sample_path
    from windproapi import WindProApi

    _windproapi = WindProApi()
    _windproapi.start_windpro_random_port()
    online_data_service = _windproapi.get_service('OnlineDataService')
    print(online_data_service.GetDataTypes())

A full list of data types with their description is given below, including the method used for downloading the data.

.. list-table:: Data types available from online
    :widths: 25 25 100
    :header-rows: 1

    * - Name of data type
      - Download method
      - Description
    * - ODSRoughnessArea
      - ``DownloadRoughnessData``
      - Roughness data
    * - ODSRoughnessGridToLine
      - ``DownloadRoughnessData``
      - Roughness data generated from gridded data.
    * - ODSHeightsLine
      - ``DownloadHeightData``
      - Elevation data as lines
    * - ODSTerrainGrid
      - ``DownloadHeightData``
      - Digital Terrain Model data as grids
    * - ODSSurfaceGrid
      - ``DownloadHeightData``
      - Digital Surface Model data as grids
    * - ODSObjHeightsGrid
      - ``DownloadHeightData``
      - Forest data
    * - ODSDepthsGrid
      - ``DownloadHeightData``
      - Bathymetry data
    * - ODSMaps
      - ``DownloadMapsData``
      - Background maps
    * - ODSWTG
      - ``DownloadTurbineData``
      - Catalogue of existing wind turbines
    * - ODSClimate
      - ``DownloadMeteoData``
      - Meteorological data e.g. from meteorological models or publically available weather stations.
    * - ODSGasp
      - ``DownloadGaspData``
      - Global Atlas for Siting Parameter data

Note that unlike in windPRO data needs to be downloaded as it is on the server.
This is most important if you want elevations as a line object.
You need to download gridded data and do the conversion to lines yourself afterwads (see :ref:`objects_elevationgrid`)
Be also aware that there is a difference between digital terrain (ODSTerrainGrid) and digitial surface (ODSSurfaceGrid) models.

This service needs a location to be prepared, i.e. the data service needs to know which data type to look for and where that is.
You need to prepare the service with ``PrepareService``.
This tells windPRO to file all data at that location.
For getting a list of all available data use ``OnlineDataService.GetServices``.
The output is a list of dictionary-like objects that contain information about the available data.
The *ServiceId* is the unique identifier to download the data.

.. code-block:: python

    import os
    project_service = _windproapi.get_service('ProjectService')
    working_dir = os.path.join(get_windpro_sample_path("4.0"), "Online_Service")
    os.makedirs(working_dir, exist_ok=True)
    project_service.NewProject(11., 55., os.path.join(working_dir, 'test.w40p'))

    dataType = 'ODSClimate'
    online_data_service.PrepareService(dataType, 55., 11.)
    meteoServices = online_data_service.GetServices(dataType)

From the list of all available data sets we can select one by its "ServiceId" and download data into a new object.
If not done already for using ``GetServices``, ``PrepareService`` needs to be run before dowloading data.

.. code-block:: python

    online_data_service.PrepareService('ODSClimate', 55., 11.)
    meteoHandles = online_data_service.DownloadMeteoData("siERABasic", 55., 11., 30000, 1, 2014, 2020)

``DownloadMeteoData`` returns a list of handles, as in principle there could be multiple objects created from downloading online data.

Find below an example how to use the OnlineDataService

.. literalinclude:: ../../python/examples/fromDocs/onlinedata_service.py