.. ARIA API documentation mapdata service file, created by
   vtran@aria.fr 01/2021.

Service de carte
================

Le service retourne des cartes de données d'une variable à une échéance pour un dataset donné.

Dépendances côté serveur
------------------------

* Python (3.7, 3.8, 3.9)
* Django (3.0, 3.1)
* Django REST Framework (3.10, 3.11, 3.12)
* Matplotlib library (1.9)
* Numpy (1.19)
* ARIA library (1.2.27) - ``ariapy`` à partir d'ARIA Gitlab repository

Usage
-----

.. http:get:: /maps/(int:zoom)/(int:tx)/(int:ty)?

  :query dataset: nom du dataset
  :query variable: nom du variable (tsmax, tsmin, rr, ...)
  :query date: la date de l'échéance au format AAAAMMJJ
  :query time: l'échéance au format ISO AAAA-MM-JJTHH:MM:SS 
  :query format: le format de la réponse (png, json)
  :query modifier: le type de données (avg, ano)
  :query timeavg: la méthode de moyennage (year, month)
  :query stat: la méthode de statistiques (mean, q10, q90, score)

  :reqheader Accept: Le type du contenu de la réponse accepté: `application/json`
  :reqheader Authorization: Le mécanisme d'authentification par Token
  :resheader Content-Type: Le type du contenu de la réponse: `application/json`

  :statuscode 200: OK
  :statuscode 403: Forbidden
  :statuscode 401: Incorrect token, Non authorisé
  :statuscode 404: Ressource non trouvée
  :statuscode 500: Erreur interne

  Le service GET comprend trois paramètres dans le chemin de l'URL: ``int``: **zoom**, **tx** and **ty**.
  Les paramètres **tx**, **ty** sont les coordonnées du tule Google.
  Le paramètre **zoom** est le niveau zoom du système des coordonnées de tuile Google.
  La réponse est une image au format *png* qui représente une carte colorée en 2D des valeurs d'une **variable**.

  **Exemple d'une requête**:

  .. sourcecode:: http

    GET /maps/6/33/25/?format=json&dataset=INMCLIMAT_RCP45&variable=CDD&time=1995-10-30T00:00:00&date=19900801&modifier=avg&timeavg=year&stat=mean HTTP/1.1
    Host: apibeta.aria.fr/py/v2
    Accept: image/png

  **Exemple d'une réponse**:

  .. sourcecode:: http

    HTTP/1.1 200 OK
    Allow: GET, HEAD, OPTIONS
    Vary: Accept
    Content-Type: image/png

  .. figure:: ./images/rcp45_cdd_6_33_25.png
    :align: center

    CDD, la carte d'un nombre de jours consécutifs secs centrée à l'année 1990 pour le tuile Google (z=6, x=33, y=25)