diff --git a/source/a_user_interfaces.rst b/source/a_user_interfaces.rst index a4996d9..4c8c800 100644 --- a/source/a_user_interfaces.rst +++ b/source/a_user_interfaces.rst @@ -17,6 +17,8 @@ Feel free to move through every section in sequence by using the next functional Tutorials in regards to the Lizard API usage can be found in the `API Tutorials section ` +.. _lizard_homepage: + Homepage =============== @@ -33,21 +35,9 @@ https://demo.lizard.net/ From the Homepage, you can link to the Lizard functionality you are interested in. -* `**Catalogue** `_: Search for your data. -* `**Viewer** `_: Explore your data. -* `**Management** `_: Manage your data, users, alarms and GeoBlocks. -* `**API** `_: Query your data. +* `Catalogue `_: Search for your data. +* `Viewer `_: Explore your data. +* `Management `_: Manage your data, users, alarms and GeoBlocks. +* `API `_: Query your data. From the homepage you have easy access to the support team and the documentation. - - -Catalogue -============= - - -Viewer -========== - - -Management -========== \ No newline at end of file diff --git a/source/b_catalogue.rst b/source/b_catalogue.rst index a17c948..9966d85 100644 --- a/source/b_catalogue.rst +++ b/source/b_catalogue.rst @@ -1,95 +1,140 @@ + + ========= Catalogue ========= +- :ref:`filters_reference_label` +- :ref:`rasters_reference_label` +- :ref:`wms_reference_label` +- :ref:`timeseries_reference_label` +- :ref:`scenarios_reference_label` + + General ======== -The Lizard Catalogue offers insight in the data that are available for your organisation. +The Lizard Catalogue offers insight in all data available to your organisation. You can reach the Catalogue via the following url: -https://demo.lizard.net/catalogue/ or {yourorganisation}.lizard.net/catalogue/ -.. image:: /images/e_catalog_00.png +`https://demo.lizard.net/catalogue/` or `[yourorganisation].lizard.net/catalogue/` + -For now, the Catalogue covers these three datatypes: +.. figure:: /images/b_catalogue_00.png -* **Raster** Raster layers in Lizard (not included are rasters from 3Di scenarios) -* **WMS layer** Wms layers in Lizard -* **Time series** Time series and monitoring networks + Complete overview of the Lizard catalogue landing page. -There is an extensive search option to make the data easily accesible. -Every data layer will show available metadata. -From the Catalogue you have the option of opening the data layers via the API or via the Lizard Viewer. +For now, the Catalogue covers these four datatypes: -Filter +* **Raster**: Raster layers in Lizard (not included are rasters from 3Di scenarios). +* **WMS layer**: Wms layers in Lizard. +* **Time series**: Time series and monitoring networks. +* **Scenarios**: Scenario information from 3Di. + +Because of the extensive amount of data available, it is important to be able to search and filter properly. +Lizard has a variety of methods to find and group data. + +.. _filters_reference_label: + + +Filters -------- -On the left side of the Catalogue app you can find several ways of filtering the data layers you have access to. -There are three different ways to filter, Organisation, Layer Collection or Observation type. -Per filter there is a list of all possible options. +On the left side of the Catalogue interface you can find several ways of filtering the data layers you have access to. +There are three different options: + +1. **Organisation**: the organisation that owns the data. +2. **Layer Collection**: the layer grouping, which can be created and assigned in the `management screens `_. +3. **Observation type**: speaks for itself, but the type of data found within the datasource. -.. image:: /images/e_catalog_03.png +Per filter there is a list of all possible options. +Only one selection can be made: if you want to filter on `Observation type = 'Waterheight'` you are unable to also include `Observation type = 'Rain'` -You can also use the search bar per filter to directly enter what you want to filter on. +You can also use the search bar to directly find your data. It is important to select the correct data type. -.. image:: /images/e_catalog_04.png +.. figure:: /images/b_catalogue_01.png -Export, Basket and login -------------------------- + Red, the filtering options on the left panel; Orange, the searchbar; Green, the search datatype. -In the top right you see the following buttons: -.. image:: /images/e_catalog_07.png +Export, selection and login +--------------------------- + +In the top-right corner you will find five different pressable buttons: + +1. **Home**: return to the homepage of the lizard portal. +2. **Exports**: interface of all exports within the session. +3. **Selection**: allows you to collect a selection of data within your "cart" to display in the viewer. +4. **Login**: log in to the application. +5. **Info**: information pop-up with a link to the docs. + +.. image:: /images/b_catalogue_02.png + **Export** -Available and running exports will appear here + +Within the export interface you are able to see all current and previous exports within this session. +You are able to download the rasters whenever the export is completed. +Once you have downloaded your raster of interest, you can clear the task. + +.. figure:: /images/b_catalogue_03.png + + Export tasks, when no exports have yet been completed. + **Basket** -Using the Basket makes it easy to make different combinations of data layers to show in Lizard. -To the left of the data layers are selection boxes. -Click these boxes to make a selection from one or several data layers. -After making the selection click the 'Add to basket' button in the lower right corner of the data layers overview. -At the top right corner of the Catalogue you will see that the Basket button now shows the number of selected data layers. + +The Lizard catalogue can be used to quickly access your rasters of interest. +One quick way to collect these rasters is through the basket - easily recognized by by the basket icon named `Selection`. +By clicking the checkbox on the left side of a raster you unlock the option to add the raster to your basket. +To add multiple layers add once, simply select multiple layers before pressing `ADD TO SELECTION`. +Once you added the rasters to your selection, you will see that the Basket icon now shows the number of selected data layers. Opening the basket gives an overview of all selected layers, and a button to 'Open all data in Lizard'. -This will open a new window for Lizard, with all the selected data layers opened. +This will open a new window for Lizard, with all the collected data layers visible. + **Login** -If you are logged in, you will have access to data that is common, or private and shared with your organisation. -Also, you have to be logged in to be able to export. -Rasters -========= +Some information is publicly accessible in Lizard. All users which are logged in will have access to 'common' data. Depending on the rights of an user a selection of private information will be available. +Furthermore, you have to be logged in to be able to export raster data. -When you open the Catalogue and choose 'Raster' in the top left, you will see an overview of all the layers you have access to. -It will show a list of 10 items, with the option to click through to other pages. -At the top of the screen there is a search bar. -Using search terms that are in the Name or the Description of the data layer you can more easily find specific data layers that you might be interested in. +.. _rasters_reference_label: -The following information is visible in this overview. +Rasters +======= -* **Type** The type of data. A normal raster, or a temporal raster. -* **Name** Name of the data layer. -* **Organisation** To which organisation the data layer belongs. -* **Description** A short description of the data contained within the data layer. -* **Latest update** When the data layer was last updated. -* **Access modifier** Divided into Public, Common and Private. +The default view of the catalogue will display a selection of 10 rasters, with the option to click through to other pages. +The following information is visible in this overview, for rasters. + +* **Type:** The type of data. A normal raster, or a temporal raster. +* **Name:** Name of the data layer. +* **Organisation:** To which organisation the data layer belongs. +* **Description:** A short description of the data contained within the data layer. +* **Latest update:** When the data layer was last updated. +* **Access modifier:** Divided into Public, Common and Private. .. note:: Information about the different access modifiers can be found under `organisation modifiers `_. .. note:: - Not included are rasters from 3Di scenarios + Not included are rasters from 3Di scenarios, these are covered under the "Scenarios" date-type. + + +Raster Information +------------------ + +Once you have selected a raster, the details become available in the right panel. +This panel offers a map of the region of interest (base map) and projects the data on top. +Underneath some general details are displayed, namely the discription, organisation and the WMS GetCapabilities URL. +In the bottom of the right-panel the `DETAILS` and `ACTIONS` can be found. -Details --------- -Once you have selected a data layer, you will find detailed information about the layer in the panel on the right. -Here it will show a map of the area and a visualisation of the data. -Below the map there is a table with detailed meta information about the data layer. If you want to visualise the layer in your Viewer or if you want to use it for data science purposes you can either choose to open it in the Viewer or the API. -.. image:: /images/e_catalog_05.png +.. figure:: /images/e_catalog_05.png + + The complete right-panel in the Lizard Catalogue. Presenting a map, description and various details regarding the selected raster (or other data-type). Lizard WMS Service for rasters -------------------------------- @@ -97,15 +142,26 @@ Lizard WMS Service for rasters When you filtered on “Layer Collection” a Lizard WMS GetCapabilities link appears in the list of meta data of the raster. You can use this link to visualise the raster in external applications such as QGIS or ESRI applications. -For more infomation, please consult the WMS Services. +.. tip:: + We now also have a `Lizard Plugin `_ for QGIS and the 3Di Modellers Interface that allows you to display WMS-Layers within these applications more easily. You only have to generate an API key to be able to use this plugin. Don't know how to generate an API key? No problem, go to: `API Key `_. + +.. note:: + For more infomation, please consult the WMS Services. + Exporting ---------- -Select the raster you would like to export. -Click on the Export button in the action menu. +Files can be exported from the catalogue. The steps you have to take to download related files depends on the date-type. +It is possible to download: rasters, timeseries or files related to scenario's. +To download a **raster**: (1) select your raster of interest, (2) go to the actions menu in the bottom-right, (3) press `Export raster` to open the raster export modal. + +The raster export modal allows you to select cells for your download. +Cell settings can be defined on the right-side of the modal. -.. image:: /images/e_catalog_06a.png +.. figure:: /images/b_catalogue_04.png + + An overview of the export modal. The Export Selection window will pop up. Follow the steps: @@ -113,25 +169,34 @@ Follow the steps: - Choose the pixel size (resolution) of the output GeoTIFF. - Choose a preferred tile size. -You can export 3 tiles at a time. -Click on Download selected cells. -A task will be started in the background. -Once your GeoTIFF's are ready you will receive a notification in the Export dropdown menu in the green bar. +.. tip:: + Do not use a really small pixel-size when you have a wide-zoom. This will require many grid-cells to be loaded, which comes at a high computational load. + +You can export multiple tiles at once, resulting in a series of download tasks. +Once your GeoTIFF's are ready you will receive a notification in the Exports button in the green topbar. If any export tasks have been started a small circle on top op the export-icon will show the number of tiffs that are being (or have been) exported. -.. image:: /images/e_catalog_06b.png +.. figure:: /images/b_catalogue_05.png + + Currently 3 tiffs have been, or are being, downloaded. + + +.. _wms_reference_label: WMS layers ============= -When you open the Catalogue and choose 'WMS layer' in the top left, you will see an overview of all the wms layers you have access to. -It will show a list of 10 items, with the option to click through to other pages. -At the top of the screen there is a search bar. -Using search terms that are in the Name or the Description of the data layer you can more easily find specific data layers that you might be interested in. +The Catalogue allows you to easily filter and visualize WMS-Layers. +To start, select WMS as data-type within the search-bar. -The following information is visible in this overview. +.. figure:: /images/b_catalogue_06.png +It will show a list of 10 items, with the option to click through to other pages. +You are only able to search based on the name in the search bar, however, it is possible to filter based on organisation (left-panel). + +The following information is visible in this overview: + * **Name** Name of the wms layer. * **Organisation** To which organisation the data layer belongs. * **Description** A short description of the data contained within the data layer. @@ -140,87 +205,92 @@ The following information is visible in this overview. .. note:: Information about the different access modifiers can be found under `organisation modifiers `_. + Details -------- -Once you have selected a wms layer, you will find detailed information about the layer in the panel on the right. -Here it will show a map of the area and a visualisation of the data. -Below the map there is a table with detailed meta information about the data layer. -If you want to use the layer in your Viewer or if you want to use it for data science purposes you can either choose to open it in the Viewer or the API. +The details of a WMS-layer are similar to that of a raster. +They can be found in the right-panel. The only change is the `download` functionality, which replaces the export of rasters. -.. image:: /images/e_catalog_08.png -Action menu ------------- +.. figure:: /images/e_catalog_08.png + + Example of a WMS-layer details panel. -.. image:: /images/e_catalog_09.png +.. figure:: /images/b_catalogue_07.png + + The actions overview within the details panel. You can download the wms directly, open it in the Viewer or in the API or analyse the wms layer in another application linking to Lizard. You can use this link to visualise the raster in external applications such as QGIS or ESRI applications. For more infomation, please consult the `WMS Services `_. + +.. _timeseries_reference_label: + Time series and monitoring networks ==================================== -When you open the Catalogue and choose 'Time series' in the top left, you will see an overview of all the layers you have access to. -It will show a list of 10 items, with the option to click through to other pages. -At the top of the screen there is a search bar. -Using search terms that are in the Name or the Description of the data layer you can more easily find specific data layers that you might be interested in. +Like the WMS-Layers, you first have to select the `Timeseries` date-type. +You will then be presented with available monitoring networks. +A monitoring network is a group of locations, with one or multiple timeseries. +An example of a monitoring network is the dutch meteorological measurements of the KNMI weatherstations. +In monitoring networks, you can group locations. These locations can have one, or multiple, timeseries. The following information is visible in this overview. -* **Monitoring network** Name of the data layer. -* **Organisation** To which organisation the data layer belongs. +* **Monitoring network** Name of the network. +* **Organisation** The organisation to which the monitoring network belongs. * **Access modifier** Divided into Public, Common and Private. .. note:: Information about the different access modifiers can be found under `organisation modifiers `_. -In monitoring networks, you can group timeseries. This can be done for example by grouping them by observation type or by source. - .. note:: New monitoring networks can be added via https://demo.lizard.net/api/v4/monitoringnetworks/ or {yourorganisation}.lizard.net/api/v4/monitoringnetworks/ or with the help of a consultant. In the near future, time series can be managed via the management screens. + Details -------- -Once you have selected a monitoring network, you will find detailed information about the dataset in the panel on the right. -Here it will show a map of the area and a visualisation of the data. -Below the map there is a table with detailed meta information about the data layer. +Once you have selected a monitoring network, the map within the right-panel will display all locations within the network. You will find the description right below, and the observation types of the timeseries can be found in the details tab. + +.. figure:: /images/b_catalogue_08.png + + An overview of the KNMI weatherstations monitoring network. -.. image:: /images/e_catalog_10.png Action menu ------------ -In the action menu, you can export the timeries you are interested in or open it in the Viewer or in the API. -You can filter on the observation type, which time series have data in a certain period and/or on location. +In the action menu, you can export the timeries you are interested in or open it in the Viewer or in the API. You can filter on the observation type or on the availability of data in a certain period and/or on location. -First choose "Select time series". +.. figure:: /images/b_catalogue_09.png -.. image:: /images/e_catalog_11.png + Monitoring networks have two actions, view the details within the API, or select a timeseries of interest. -Below you see a screenshot of all locations with time series for monitoring network KNMI weerstations without filtering. +First choose `Select time series`. -.. image:: /images/e_catalog_12.png -Below you see a screenshot of all locations with time series with observation type 'windsnelheid' and that have data between 14 and 16 March 2021. -Then location Bilt is manually selected (by clicking on a dot or use the search bar) and ready to export or view in the API or in the Viewer. +.. figure:: /images/b_catalogue_10.png -.. image:: /images/e_catalog_13.png + The `select time series` button will open the timeseries selection modality. -Scenarios -============== -When you open the Catalogue and choose 'Scenario' in the top left, you will see an overview of all the scenarios you have access to. -It will show a list of 10 items, with the option to click through to other pages. -At the top of the screen there is a search bar. -Using search terms that are in the Name or the Description of the data layer you can more easily find specific data layers that you might be interested in. +.. figure:: /images/b_catalogue_11.png -.. image:: /images/e_catalog_14.png + If you provide a timeframe, only locations where data is available will be shown. +.. _scenarios_reference_label: + +Scenarios +============== + +To find information in regards to the 3Di scenarios, that have been exported to Lizard, the first step is to select the `Scenario` date-type. + +.. figure:: /images/b_catalogue_12.png The following information is visible in this overview. @@ -230,6 +300,10 @@ The following information is visible in this overview. * **Last update** When the data layer was last updated. * **Access modifier** Divided into Public, Common and Private. +.. figure:: /images/b_catalogue_13.png + + A simulation has a extensive details page, further more, you are able to download related files or view the scenario in the API or Viewer. + .. note:: Information about the different access modifiers can be found under `organisation modifiers `_. @@ -239,7 +313,7 @@ Details Once you have selected a data layer, you will find detailed information about the layer in the panel on the right. -.. image:: /images/e_catalog_15.png +.. figure:: /images/b_catalogue_14.png Action menu @@ -247,9 +321,10 @@ Action menu In the action menu, you can open the scenario in the Viewer or in the API. -Results ------------- -In the results menu, you can download the results. +Downloads +--------- + +The downloads section shows all related files. There are basic and raw files available. -.. image:: /images/e_catalog_16.png \ No newline at end of file +.. figure:: /images/b_catalogue_15.png diff --git a/source/b_management.rst b/source/b_management.rst index 62a9fd6..ff61890 100644 --- a/source/b_management.rst +++ b/source/b_management.rst @@ -1,21 +1,49 @@ ========== Management ========== +This page discusses the Management page that can be accessed through the :ref:`Lizard homepage `. -In the management interface there is a variety of options. +The management page links to four subpages: -`Usermanagement `_ will be discussed later. +- :ref:`data_management` +- :ref:`Users ` +- :ref:`alarms` +- :ref:`personal_api_keys` + + +.. _data_management: + +==== +Data +==== +The data management page provides several options to interact with the data in the datawarehouse. +These options are divided by the type of data: + +- :ref:`data_management_rasters` +- :ref:`data_management_geoblocks` +- :ref:`data_management_wmslayers` +- :ref:`data_management_layercollections` +- :ref:`data_management_timeseries` +- :ref:`data_management_scenarios` +- :ref:`data_management_labels` + +.. image:: /images/c_datatypes_01.png + +.. _data_management_rasters: Rasters -============= +======= The data management interface for rasters can be used to upload, edit or remove rasters. Raster Sources are the data containers, Raster Layers are the configuration of how the data is visualised. .. image:: /images/c_manage_rasters_01.png + .. image:: /images/c_manage_rasters_02.png + .. image:: /images/c_manage_rasters_03.png + Creating and editing Raster Sources and Layers ---------------------------------------------- @@ -23,7 +51,7 @@ The first step in uploading your raster datasets is to create a Raster Source. The Data Management interface is available at: “www.{your_organisation}.lizard.net/management/”. -After landing on this page, click on ‘Data’ -> ‘Rasters’ -> 'Raster Sources'. +After landing on this page, click on `Data` -> `Rasters` -> `Raster Sources`. Click on “New Item” |NewItem| to open the form or choose an existing raster to edit. .. |NewItem| image:: /images/c_manage_newitem.png @@ -33,12 +61,13 @@ In case of a temporal raster source you need to specify which file belongs to wh This is recognised automatically if the filename is composed according to the specified format. When you save a new Source you will have the option to go straight to the Raster Layer form to publish your data. -.. image:: /images/c_datatypes_01.png - Interested in the possibilities for your organisation? Please contact us via info@lizard.net. -GeoBlocks management -==================== + +.. _data_management_geoblocks: + +GeoBlocks +========= The GeoBlocks management page provides you a powerful tool to build your GeoBlocks Rasters. It helps you configure complex GeoBlocks models and enables you to validate your work along the way. @@ -60,6 +89,7 @@ Example 2 shows a more complex model with multiple Raster Sources and a series o For more information about the possibilities of GeoBlocks see: :ref:`GeoBlocksAnchor` +.. _data_management_wmslayers: WMS Layers =========== @@ -231,6 +261,8 @@ Click OK and double click on the connection. If multiple layers appear, double c The styling will automatically be taken from Lizard. If the layer is temporal, you can also navigate through time. +.. _data_management_layercollections: + Layer collections ==================== @@ -238,9 +270,10 @@ Layer collections This section will be extended in the near future. +.. _data_management_timeseries: Time series -============== +=========== The data management interface for timeseries can be used to upload, edit or remove timeseries, monitoring networks and locations. @@ -381,9 +414,10 @@ Create a new object with the New Item button on the top right corner. If you are satisfied, click "SAVE" +.. _data_management_scenarios: Scenarios -============== +========= The data management interface for scenarios can be used to manage scenarios. @@ -464,8 +498,10 @@ Create a new project with the New Item button on the top right corner. .. image:: /images/c_manage_newitem.png +.. _data_management_labels: + Labels -============ +====== .. warning:: This section is to be extended. @@ -473,18 +509,57 @@ Labels .. image:: /images/c_manage_labeltypes.png +.. _alarms: + Alarms -====== +========== + +The Lizard Alarms are a powerful feature designed to provide real-time notifications and alerts based on user-defined criteria. +This system enables users to monitor various environmental conditions, ensuring timely responses to critical events. + + +Submenus +---------- +An alarm is set-up using multiple submenu's: + +* Contacts +* Groups +* Templates +* Notifications -Lizard provides an alarm feature that sends notifications via sms or email when newly processed values of timeseries or temporal rasters exceed a threshold. -It is used to notify people of events that may require action, for instance an upcoming rain event or flood. +1. Contacts -The alarm management screens are found at https://demo.lizard.net/management/#/alarms. +In the contacts menu, you can list names and add telephone numbers or email adresses for +respectively SMS and email alarm notifications. -.. image:: /images/f_alarms_01.jpg +2. Groups + +In the Groups menu, you can set up contacts to be grouped for receiving alerts. Note that only contact groups can be assigned to an alarm. If you want to send messages to a single contact, you need to assign that contact to a group with just one member. + +3. Templates + +In the templates map the alarm messages are set-up. Here you can configure specific messages using dynamic variables like +names, specific rain variables, timestamps and more. + +4. Notifications + +The Notifications tab is where you configure the alerts and bring everything together. +First you have to choose on what type of data the alert is connected: + +* Raster alarms +* Time series alarms + +To set up an alarm, choose the raster or time series you are interested in by searching for and selecting the object name. When selecting a raster alarm, you need to define measuring points using longitude-latitude coordinates (note that we specifically use the order longitude-latitude, not latitude-longitude). + +The "Limit to relative period" setting determines what selection of the data is used for alerts. If switched off, alarms are triggered whenever new data is added. If switched on, you can configure alerts to only be triggered by near-future events, which is useful for avoiding alerts when adding new historical data. + +After selecting the location and data, you can apply multiple boolean expressions to define the conditions for triggering alarms. You can also enter specific threshold values. + +For more varying measurements, there is a snooze button that allows you to trigger an alarm only after a threshold has been met or withdrawn a certain number of times. + +Finally, you can select the specific contact group (as defined in Groups) and the template message (as defined in Templates) for the alarm. -The configuration has a variety of options to generate relevant notifications with messages that include the specifics of the event. Notifications ============= @@ -561,3 +636,42 @@ The variables contain options for including the name of the receiver and details The option "No further impact" determines that a message is used specifically to notify when an alarm is fully withdrawn. This type of message can be set in addition to a standard message to let receivers know that the situation has settled down. This often requires a different text and therefore a different Template. + + +User Management +=============== + +As user management is only of interest to managers, this is discribed in its own section. Find the page on user management `here `_. + +.. _personal_api_keys: + +Personal API Keys +================= + +Personal API keys are used to authenticate external applications with basic authentication. These keys are essential for ensuring secure access to APIs without exposing your username and password. This follows a security measure, labeled as 'basic authentication'. The interface, allows you to manage your personal API keys. The list of keys is displayed on the right side of the page. You can add new keys by clicking the "+ New Item" button. + +.. image:: /images/b_management_13.png + +Within the viewport you can find the following information: + +* **Name:** The name provided to the API Key, this is mainly for you to remember what you used the API Key for. +* **Scope:** Currently two scopes are available - Read/Write and FTP. +* **Created on:** The date and time of the key creation. + + +.. tip:: + Visibility: The API key is only shown once at the time of creation. Ensure you save it securely, as it cannot be retrieved later. + +.. tip:: + Security: Treat your API key like a password. Do not share it publicly or expose it in your application code. + By using personal API keys, you can securely interact with external applications and services, ensuring that your API credentials are kept safe. + + +Authentication +-------------- + +To authenticate using a personal API key, follow these steps: + +1. Set the authentication type to 'basic authentication' +2. Set the username to __key__ (with double underscores on both sides of the word "key"). +3. The password is your unique API key. \ No newline at end of file diff --git a/source/c_digitale_delta.rst b/source/c_digitale_delta.rst new file mode 100644 index 0000000..b67a62e --- /dev/null +++ b/source/c_digitale_delta.rst @@ -0,0 +1,10 @@ +Digitale Delta API +================== + +De Nederlandse watersector staat voor de opgave om in een snel veranderende omgeving haar informatievoorziening te transformeren en klaar te maken voor de toekomst. +De Digitale Delta is het open platform voor het aanbieden en vinden van relevante data voor het waterbeheer in Nederland. +Lizard spreekt Digitale Delta en is een van de dataleveranciers binnen de Digitale Delta. +De Digitale Delta API Root is te vinden op https://demo.lizard.net/dd/api/v2. + +De documentatie van de Digitale Delta API is te vinden op: +https://github.com/DigitaleDeltaOrg/dd-api-spec/blob/master/README.md \ No newline at end of file diff --git a/source/c_introduction.rst b/source/c_introduction.rst index b663f95..7f21e8b 100644 --- a/source/c_introduction.rst +++ b/source/c_introduction.rst @@ -4,132 +4,126 @@ Introduction ============ -API functional documentation -============================== +This section gives more information on the Lizard API, which can be accessed via “{your_organisation}.lizard.net/api/v4/”. +The Lizard API can be used to retrieve data from or send data to the datawarehouse. The following topics are documented here: + +- :ref:`what_is_an_api` +- :ref:`basic_use_api` +- :ref:`api_versions` +- :ref:`api_data_uploads` +- :ref:`api_rasters` +- :ref:`api_timeseries` +- :ref:`api_assets` +- :ref:`api_contact` + +.. note:: + You can find the Lizard API here: “{your_organisation}.lizard.net/api/v4/”, for example https://demo.lizard.net/api/v4/. + -You can access the Lizard API via “{your_organisation}.lizard.net/api/v4/”. .. image:: /images/c_apifunctional_01.jpg +.. _what_is_an_api: + What is an API? =============== API stands for Application Programming Interface. -The API, looking like the picture above, gives back timeseries, rasters, or other data or information. -This is depending on the request you do to the API. -This request comes from the URL you type in the browser. -You can also access the API via another program, and make automatic requests. +The Lizard API enables users to communicate with the data that is stored within the datawarehouse. +The communication between you and the Lizard API happens through a request. +There are two main ways to send a request to the Lizard API: + +* From your browser +* From an environment with a programming language that supports requests, such as a Python script + + + +.. _basic_use_api: Basic use API ============= -Below we discuss a basic request to the API. -More examples and possibilities will be discussed further down +In this section we explain how to communicate with the Lizard API by making requests. +A request consists of an *endpoint* (required) and *query parameters* (optional). +An endpoint is a digital location that is connected to a specific resource, such as for example ``locations``. +All possible endpoints are shown at the API root: “{your_organisation}.lizard.net/api/v4/”. +Query parameters are filters that you can use, for example to filter on the location name or code. -The basic url is www.{your_organisation}.lizard.net/api/v4, for example: - www.demo.lizard.net/api/v4 +| An example of a request is: +| https://demo.lizard.net/api/v4/locations/ -If you type this in your browser, for example Google Chrome, you will get a list of parameters. -These parameters are so called *endpoints*. -If you paste this endpoint after your basic url, you will initiate a query. -An example is ``locations``. -If you click on the url www.demo.lizard.net/api/v4/locations , you will send a query to Lizard to search all locations that you have access to. -As a response, you will get indeed the locations back, as well as some metadata. +This example consists of an API root (demo.lizard.net/api/v4/) and an endpoint (``locations``). +The request asks Lizard to show all locations that you have access to, including their metadata. -.. image:: /images/c_apifunctional_02.jpg - -Above each page, you will see some additional parameters, with which you can specify your query more. -Most endpoints have examples of this. +If you want to look for specific locations, you can add query parameters. +Each endpoint page shows which query parameters can be used. +The image below shows the query parameters available for the endpoint ``locations``. .. image:: /images/c_apifunctional_03.jpg -If we are looking for a specific location, with a name that starts with 'Inlaat', we can use this query: +In the case of the endpoint ``locations`` you can for example filter on ``name`` and ``code``. +A request with query parameters should follow this structure: -https://demo.lizard.net/api/v4/locations/?name__startswith=Inlaat + {endpoint url}/?{query parameter}={your filter} -If you are an administrator or supplier of the data, you can also edit or delete the data via the API. +| An example of a request for locations with code ``3201_PS2``: +| https://demo.lizard.net/api/v4/locations/?code=3201_PS2 -Versions -======== -We support two versions of our API: +| If you want to use multiple query parameters in your request, you have to separate them by using an ampersand: +| {endpoint url}/?{query parameter 1}={filter 1}&{query parameter 2}={filter 2} + +| An example with two query parameters is when you look for locations with code ``3201_PS2`` (query parameter 1) and a name that starts with ``inlaat`` (query parameter 2): +| https://demo.lizard.net/api/v4/locations/?code=3201_PS2&name__startswith=inlaat -* API v3: deprecated (sunset date: 4 July 2023) -* API v4: stable +.. _api_versions: -API V3 will be taken offline by 4 July 2023. Any use in scripts or applications should be reimplemented in API V4. -API V4 is the stable version. We can make changes to this version, but they should always be backwards compatible and therefore not break any existing use. +Versions +======== -Digitale Delta API ------------------- +The current stable version of the Lizard API is v4. -De Nederlandse watersector staat voor de opgave om in een snel veranderende omgeving haar informatievoorziening te transformeren en klaar te maken voor de toekomst. -De Digitale Delta is het open platform voor het aanbieden en vinden van relevante data voor het waterbeheer in Nederland. -Lizard spreekt Digitale Delta en is een van de dataleveranciers binnen de Digitale Delta. -De Digitale Delta API Root is te vinden op https://demo.lizard.net/dd/api/v2 +The previous version v3 is deprecated since 2023. +Any use of v3 in scripts or applications should be reimplemented in API v4. +If you run into problems converting API v3 into v4, please contact us through the :ref:`self_service_portal`. -De documentatie van de Digitale Delta API is te vinden op: -https://github.com/DigitaleDeltaOrg/dd-api-spec/blob/master/README.md + +.. _api_data_uploads: Data uploads ================ We support multiple types of data uploads. -Data can be uploaded manually, via the data management interface, or you can set up real-time data connections using the API. -We can also provide support on either manual or automatic data uploads. +Data can be uploaded manually, via the :ref:`data management interface `, +or you can set up real-time data connections using the API. +We can also provide support on either manual or automatic data uploads. \ +This section deals with the data upload through the API. .. note:: Please note that Lizard assumes the data to be in UTC - - + +.. _api_rasters: + Rasters =========== Requirements -------------- -Your raster data has to be in the format of a single band, georeferenced TIFF (geotiff), with the following requirements: +Your raster data has to be in the format of a single band, georeferenced TIFF (GeoTIFF), with the following requirements: * **Geotiff should have valid projection** including transformation (EPSG code). All projections supported by proj4 are supported. * **Geotiff should have a NODATA value**. * **Geotiff should be single band**. RGB or multi-band is not supported. * **Temporal raster datasets** with multiple timesteps **should be supplied with a single geotiff per timestamp** +.. warning:: It is not possible to directly upload a NetCDF file to Lizard. + They have to be seperated into individual geotiffs. Upload ------ -You can supply your GeoTIFF’s in multiple ways: - -* Use the Data Management App -* Use the Lizard API -* Use the Lizard FTP - -Use of the Data Management App is fairly straightforward and is build upon our API. -If you want to upload larger raster datasets, please make use of our API. - - -Using the Data Management App -++++++++++++++++++++++++++++++ - -Once you have successfully created a raster store you will see the pop up below. - -.. image:: /images/c_dataexchange_03.png - -Choose upload data to browse your GeoTIFF’s. -When you want to add data to an existing raster store, click on the upload icon |uploadicon| in the list of existing Raster Stores. - -.. |uploadicon| image:: /images/c_dataexchange_04.png - -You can supply multiple rasters, Lizard will blend them together! Click “Save all Files” to start uploading your data. -Your GeoTIFF’s will be uploaded in a task. You can follow the status of the task by clicking “show asynchronous task”. - -.. image:: /images/c_dataexchange_05.png - -Using the Lizard API -++++++++++++++++++++ - Below you find an example of how to upload a temporal geotiff in Python: .. code-block:: python @@ -189,6 +183,7 @@ Below you find an example of how to upload a temporal geotiff in Python: ) file_id+= 1 +.. _api_timeseries: Time Series ============= @@ -277,6 +272,7 @@ An example of an upload of an image using requests in Python: 'username': 'jane.doe', 'password': 'janespassword' }) +.. _api_assets: Assets ======= @@ -357,6 +353,7 @@ This example .ini creates (a) new nested asset(s) from each record of the shapef You can copy paste this code in your own .ini file and zip it together with the shapefile. +.. _api_contact: Contact ======= diff --git a/source/d_authentication_user_management.rst b/source/d_authentication_user_management.rst index 5f03a78..ca905f3 100644 --- a/source/d_authentication_user_management.rst +++ b/source/d_authentication_user_management.rst @@ -92,6 +92,8 @@ We have 4 roles and 3 different types of privileges. * **Manager:** is allowed to grant roles to different users. A manager can not read or write data by default. To achieve this, one of the other roles has to be assigned seperately. +.. _user_management: + User management =============== diff --git a/source/d_self_service_portal.rst b/source/d_self_service_portal.rst index 2d4ee06..1f06d25 100644 --- a/source/d_self_service_portal.rst +++ b/source/d_self_service_portal.rst @@ -1,3 +1,5 @@ +.. _self_service_portal: + =================== Self Service Portal =================== @@ -5,21 +7,22 @@ Self Service Portal Topdesk =========== -Nelen & Schuurmans provide a Service Desk function via https://nelen-schuurmans.topdesk.net/, The Nelen & Schuurmans Self Service Portal shall be available 24/7. -The Service Desk giving support on all Lizard products for Lizard customers. -Customers can reach telephonic support (Prio 1) on working days from 09:00 - 17:00 (CEST) excluding the days declared as dutch public holiday close days. +Nelen & Schuurmans provides a Service Desk function via https://nelen-schuurmans.topdesk.net/. +The Nelen & Schuurmans Self Service Portal is available 24/7. +The Service Desk gives support on all Lizard products for Lizard customers. +Customers can reach telephonic support (Prio 1) on working days from 09:00 - 17:00 (CEST) excluding the Dutch public holidays. -Customers shall report incidents primarily via the Self Service Portal but may also do so via email: servicedesk@nelen-schuurmans.nl. +Customers can report incidents primarily via the Self Service Portal but may also do so via email: servicedesk@nelen-schuurmans.nl. -This access should be used for, but not limited to: +This access should be used for, but is not limited to: -* new incidents -* monitor service progress -* account requests -* malfunctions reports -* query, problem and defect reporting -* requests for general technical support -* submission of enhancement/feature requests +* New incidents +* Monitor service progress +* Account requests +* Malfunctions reports +* Query, problem and defect reporting +* Requests for general technical support +* Submission of enhancement/feature requests All incidents relating to the Lizard software with the exception of enhancement/feature requests are recorded and followed up at no additional cost. diff --git a/source/e_release_notes.rst b/source/e_release_notes.rst index 39609a3..64f24b9 100644 --- a/source/e_release_notes.rst +++ b/source/e_release_notes.rst @@ -9,19 +9,31 @@ Release Notes ============= +May 21st 2024 +================== + + +New features in API v4: + +* 3D tiles generation - Lizard postprocessing can now generate 3D tiles + +* Async (bulk) timeseries events import in API - The API now includes functionality for asynchronous import of bulk timeseries events, improving efficiency and performance for large data sets. + +* Vulnerable Buildings Analysis - An experimental functionality added to Lizard to allow you to determine vulnerable buildings based on waterdepth maps. + + February 20th 2024 ================== Lizard QGIS plugin updated: -* Download scenario'sor use them as a WMS. +* Download scenario's or use them as a WMS. -* Download rasters directly into your project. +* Download (non-scenario) rasters directly into your QGIS project. Everything can be found on the `Lizard Plugin page `_. - January 12th 2024 ================= diff --git a/source/images/b_catalogue_00.png b/source/images/b_catalogue_00.png new file mode 100644 index 0000000..fe2f1d8 Binary files /dev/null and b/source/images/b_catalogue_00.png differ diff --git a/source/images/b_catalogue_01.png b/source/images/b_catalogue_01.png new file mode 100644 index 0000000..5a978e9 Binary files /dev/null and b/source/images/b_catalogue_01.png differ diff --git a/source/images/b_catalogue_02.png b/source/images/b_catalogue_02.png new file mode 100644 index 0000000..d1ba18b Binary files /dev/null and b/source/images/b_catalogue_02.png differ diff --git a/source/images/b_catalogue_03.png b/source/images/b_catalogue_03.png new file mode 100644 index 0000000..a7abf25 Binary files /dev/null and b/source/images/b_catalogue_03.png differ diff --git a/source/images/b_catalogue_04.png b/source/images/b_catalogue_04.png new file mode 100644 index 0000000..5c2699b Binary files /dev/null and b/source/images/b_catalogue_04.png differ diff --git a/source/images/b_catalogue_05.png b/source/images/b_catalogue_05.png new file mode 100644 index 0000000..7cb28a8 Binary files /dev/null and b/source/images/b_catalogue_05.png differ diff --git a/source/images/b_catalogue_06.png b/source/images/b_catalogue_06.png new file mode 100644 index 0000000..2e516b2 Binary files /dev/null and b/source/images/b_catalogue_06.png differ diff --git a/source/images/b_catalogue_07.png b/source/images/b_catalogue_07.png new file mode 100644 index 0000000..65b2cda Binary files /dev/null and b/source/images/b_catalogue_07.png differ diff --git a/source/images/b_catalogue_08.png b/source/images/b_catalogue_08.png new file mode 100644 index 0000000..bcaee3f Binary files /dev/null and b/source/images/b_catalogue_08.png differ diff --git a/source/images/b_catalogue_09.png b/source/images/b_catalogue_09.png new file mode 100644 index 0000000..17da612 Binary files /dev/null and b/source/images/b_catalogue_09.png differ diff --git a/source/images/b_catalogue_10.png b/source/images/b_catalogue_10.png new file mode 100644 index 0000000..1a3396d Binary files /dev/null and b/source/images/b_catalogue_10.png differ diff --git a/source/images/b_catalogue_11.png b/source/images/b_catalogue_11.png new file mode 100644 index 0000000..25ccdc1 Binary files /dev/null and b/source/images/b_catalogue_11.png differ diff --git a/source/images/b_catalogue_12.png b/source/images/b_catalogue_12.png new file mode 100644 index 0000000..6349ce5 Binary files /dev/null and b/source/images/b_catalogue_12.png differ diff --git a/source/images/b_catalogue_13.png b/source/images/b_catalogue_13.png new file mode 100644 index 0000000..2438ec1 Binary files /dev/null and b/source/images/b_catalogue_13.png differ diff --git a/source/images/b_catalogue_14.png b/source/images/b_catalogue_14.png new file mode 100644 index 0000000..b71f926 Binary files /dev/null and b/source/images/b_catalogue_14.png differ diff --git a/source/images/b_catalogue_15.png b/source/images/b_catalogue_15.png new file mode 100644 index 0000000..b4a7668 Binary files /dev/null and b/source/images/b_catalogue_15.png differ diff --git a/source/images/b_management_13.png b/source/images/b_management_13.png new file mode 100644 index 0000000..5f3c4fd Binary files /dev/null and b/source/images/b_management_13.png differ diff --git a/source/index.rst b/source/index.rst index 14f02f6..4adddd2 100644 --- a/source/index.rst +++ b/source/index.rst @@ -54,6 +54,7 @@ Overview of the documentation pages c_introduction c_endpoints + c_digitale_delta .. toctree::