Publication d'observations hydro élaborées
==========================================

Ce web-service permet de publier des observations hydrométriques élaborées : débits journaliers,
débits mensuels, min, max,...

====== ==========================================
Code   Libellé
====== ==========================================
QmM    Débit moyen mensuel
QIXM   Débit instantané maximal mensuel
QINM   Débit instantané minimal mensuel
HIXM   Hauteur instantanée maximale mensuelle
HINM   Hauteur instantanée minimale mensuelle
QmnJ   Débit moyen sur n jours
QIXnJ  Débit instantané maximal n journalier
QINnJ  Débit instantané minimal n journalier
HIXnJ  Hauteur instantanée maximale n journalière
HINnJ  Hauteur instantanée minimale n journalière
QmnH   Débit moyen n horaire
HmnH   Hauteur moyenne n horaire
HmnJ   Hauteur moyenne n journalière
HmM    Hauteur moyenne mensuelle
QIXJ   Débit instantané maximal journalier
QINJ   Débit instantané minimal journalier
HIXJ   Hauteur instantanée maximal journalière
HINJ   Hauteur instantanée minimale journalière
Module Débit moyen inter-annuel
QIX    Débit instantané maximum
QIN    Débit instantané minimum
HIX    Hauteur instantanée maximum
HIN    Hauteur instantanée minimum
GRAD   Gradient horaire des hauteurs
====== ==========================================

Paramètres HTTP
---------------

========= =============
Paramètre Valeur
========= =============
Route     obsshydroelab
Méthode   POST
========= =============

Paramètres
----------

Les paramètres doivent être transmis dans le contenu de la requête au format format JSON.

============== ===================================== ========= ===
Nom            Description                           Type      O/F
============== ===================================== ========= ===
cdentites      liste de codes de site                list(str) O
               et/ou de codes de station
typeelabore    Grandeur élaborées (QmnJ,...)         str       O
statuts        Liste de statuts                      list(int) F
qualifications Liste de qualifications               list(int) F
methodes       Liste de méthodes                     list(int) F
pdt            Pas de temps (n de la grandeur)       int       F
glissant       observations glissantes               bool      F
dtdebut        Date de début                         datetime  F
dtfin          Date de fin                           datetime  F
dtinsdebut     date de début d'insertion             datetime  F
dtinsfin       Date de fin d'insertion               datetime  F
asynchrone     Publication asynchrone                bool      F
email          email lié à la publication asynchrone str       F
archive        Publication d'observations archivées  int       F
============== ===================================== ========= ===

Pas de temps
^^^^^^^^^^^^

Le pas de temps correspond au « n » du type élaboré.

Date de début
^^^^^^^^^^^^^

Pour des observations élaborées élémentaires stockées en PHyC (débits journaliers, débits mensuels,
les min et max des hauteurs et des débits journaliers et mensuels, Module et min et max des
chroniques) et lorsque le pas de temps est non défini ou égal à 1, la date de début des web-services
de publication d’observations élaborées est facultative.

En ne renseignant pas la date de début, la PHyC calcule nombre théorique de données retournées
avec la date de début: 1950-01-01.

La date de début correspond à la première observation nécessaire au calcul de la première
observation élaborée.

Exemple : pour la grandeur QmnJ avec n=3 et une date de début 1er janvier,
la première observation retournée par la PHyC sera le débit 3 jours du 3 janvier qui 
est la moyenne des débits du 1er janvier au 3 janvier.


Statistiques journalières
^^^^^^^^^^^^^^^^^^^^^^^^^

Si la statistique demandée est une statistique journalière, le pas de temps est exprimé en jours et
devra être compris entre 1 et 30. La statistique du jour j est calculée à partir des données des
(n-1) jours précédents et le jour j. Par exemple, avec un pas de temps de 3 jours, l’observation
élaborée du 10 juin 2016 sera calculée avec les données des jours du 8, 9 et 10 juin.

Statistiques horaires
^^^^^^^^^^^^^^^^^^^^^

Si le type élaboré est une statique horaire, le pas de temps est exprimé
en heures et devra être compris entre 1 et 23. La statistique du l’heure
h est calculée à partir des données des (n-1) heures précédentes et
l’heure h. Par exemple, avec un pas de temps de 3 heures, l’observation
élaborée du 10 heures sera calculée avec les données comprises dans
l’intervalle [8h-11h[.

Glissant
^^^^^^^^

Le booléen glissant permet de calculer des statistiques sur l’ensemble des jours de la période pour
des statistiques journalières ou l’ensemble des heures de la période pour des statistiques horaires.

Si le booléen glissant prend la valeur « false », le web-service ne renverra qu’une statistique par
pas de temps.

La date de la première observation élaborée correspond à la date début de la période tronquée
au jour ou à l’heure.

Lorsque le paramètre glissant est à « false », pour la période du 1er juin au 9 juin, le web-service
renverra au maximum 3 observations élaborées (3 juin, 6 juin et 9 juin) alors que s’il est à
« true », il renverra des indicateurs du 1er au 9 juin si ces statistiques peuvent être calculées.

======== ================================================
Glissant Dates des obs élaborées (pas de temps = 3 jours)
======== ================================================
false    3 juin, 6 juin et 9 juin
true     3, 4, 5, 6, 7, 8 et 9 juin
======== ================================================

Dans le cas d'un type élaboré « dQmM », les filtres sur le statut, la
qualification et la méthode sont inactifs.

Date de fin des séries d'observations élaborées
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Lorsque la date de fin n'est pas présente dans les paramètres du web-service, la date de fin des
séries correspond à :

-  la date actuelle tronqué au mois pour des observations élaborées
   mensuelles;
-  la date actuelle tronquée au jour pour des observations élaborées
   journalières;
-  la date actuelle tronquée à l'heure pour des observations élaborées
   horaires.

Paramètre archive
^^^^^^^^^^^^^^^^^

Par défaut, la PHyC ne renvoie pas les observations élaborées forcées archivées.

Le paramètre archive peut prendre 3 valeurs:

- 0: récupération des observations élaborées;
- 1: récupération des observations élaborées expertisées archivées;
- 2: récupération de l'ensemble des observations y compris celles archivées.

Pour la récupération d'observations archivées, le pas de temps doit être égal à 1.

La PHyC archive uniquement les observations élaborées forcées expertisées suivantes:

- min et max journaliers et mensuels;
- débits moyens journaliers et mensuels.

Droit de publication
--------------------

Sites et stations publics
^^^^^^^^^^^^^^^^^^^^^^^^^

IL n'est pas nécessaire d'être authentifié pour publier sur des sites et stations publics.

Stations "Hauteur publique"
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Il n'est pas nécessaire d'être authentifié pour publier des statistique de hauteur sur ces stations.

IL est nécessaire d'être authentifié pour publier des observations élaborées de débit et d'avoir le
profil institutionnel ou de posséder un rôle sur la station.

Stations "Débit public"
^^^^^^^^^^^^^^^^^^^^^^^

Il n'est pas nécessaire d'être authentifié pour publier des observations élaborées de débit sur ces stations.

IL est nécessaire d'être authentifié pour publier des observations élaborées de hauteur et d'avoir le
profil institutionnel ou de posséder un rôle sur la station.

Sites et Stations restreints
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Il est nécessaire d'être authentifié pour publier des observations élaborées d'avoir le profil
institutionnel ou de posséder un rôle sur le site ou la station.

Sites et stations privés
^^^^^^^^^^^^^^^^^^^^^^^^

IL est nécessaire d'être authentifié et de posséder un rôle sur le site ou la station.

Réponse du  web-service en mode asynchrone
------------------------------------------

En mode asynchrone, le web-service enregistrera la demande de publication.
En retour, la PHyC fournit deux paramètres.

- idpublication: identifiant de publication
- url : le lien de récupération de la demande

Réponse du  web-service en mode synchrone
-----------------------------------------

Dates des observations élaborées
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Statistiques min et max
"""""""""""""""""""""""

Pour des statistiques min, max journaliers (HIXnJ, HINnJ, QIXnJ et QINnJ) avec ou sans pas de temps,
la PHyC fournit la date d’obtention du min ou du max et la date de l’observation élaborée.

La date de l’observation se calcule à partir de la date de début de la série et le rang de
l’observation élaborée.

Statistiques moyennes
"""""""""""""""""""""

Pour les statistiques moyennes la date de l'observation correspond à la date l'observation élaborée

Module
""""""

Le module est une statistique non datée.

Pour cette statistique, la date de l'observation ainsi que les dates de début
et de fin ne sont pas présentes.

dQmM
""""

Dans le cas d'un type élaboré « dQmM », la balise <DtObsElabHydro>
correspond à la date du point pivot et la balise <DtProdObsElabHydro> à
la date de création du point.

Continuité d'une observations élaborée à pas de temps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pour une observation élaborée de date T de pas de temps n, la continuité est calculée à partir des
continuités des observations élaborées élémentaires T, T-1, …, T-n+1.

Réponse
^^^^^^^

Le web-service renvoie un json hydrométrie contenant les observations hydro à publier.

Le json hydrométrie contient les deux propriétés Scenario et Donnees.

Données
^^^^^^^

L'objet Données contiendra l'unique propriété SeriesObsElaborHydro.

SeriesObsElaborHydro est une liste non vide d'objets SerieObsElaborHydro.

SerieObsElaborHydro
^^^^^^^^^^^^^^^^^^^

Propriétés de l'objet SerieObsElaborHydro:

- TypDeGrdSerieObsElaborHydro
- PDTSerieObsElaborHydro
- DtDebPlagSerieObsElaborHydro
- DtFinPlagSerieObsElaborHydro
- DtProdSerieObsElaborHydro
- DtDesactivationSerieObsElaborHydro
- SysAltiSerieObsElaborHydro
- GlissanteSerieObsElaborHydro
- CdContact
- CdSiteHydro CdStationHydro
- ObssElaborHydro : liste non vide d'objets ObsElaborHydro

ObsElaborHydro
^^^^^^^^^^^^^^

Propriétés de l'objet ObsElaborHydro:

- DtObsHydro
- DtResObsElaborHydro
- ResObsElaborHydro
- QualifObsElaborHydro
- MethObsElaborHydro
- ContObsElaborHydro
- StObsElaborHydro

Exemple
^^^^^^^

.. code-block:: json
   :caption: Observations élaborées hydro au format json

   {
     "Scenario": {},
     "Donnnees": {
       "SeriesObsElaborHydro": [
         {
           "TypDeGrdSerieObsElaborHydro": "QIXnJ",
           "PDTSerieObsElaborHydro": 1,
           "DtDebPlagSerieObsElaborHydro": "2015-01-01T00:00:00",
           "DtFinPlagSerieObsElaborHydro": "2015-01-01T00:00:00",
           "DtProdSerieObsElaborHydro": "2024-01-01T00:00:00",
           "SysAltiSerieObsElaborHydro": 31,
           "GlissanteSerieObsElaborHydro": true,
           "CdContact": "0",
           "CdSiteHydro": "A1234567",
           "ObssElaborHydro": [
             {
               "DtObsHydro" : "2015-01-01T00:00:00",
               "DtResObsElaborHydro" : "2015-01-01T06:00:00",
               "ResObsElaborHydro": 154,
               "QualifObsElaborHydro": 16,
               "MethObsElaborHydro": 8,
               "ContObsElaborHydro": 0,
               "StObsElaborHydro": 4
             }
           ]
         }
       ]
     }
   }
