Merge branch 'update' into 'master'

add station media and top N for send request See merge request !34

Merge branch 'update' into 'master'
add station media and top N for send request See merge request !34
e2b1f0ea · Jerome Touvier · 0f80459f · 6d03baa8 · e2b1f0ea · e2b1f0ea
Commit e2b1f0ea authored Jan 19, 2021 by Jerome Touvier
--- a/Dockerfile
+++ b/Dockerfile
--- a/LICENSE
+++ b/LICENSE
--- a/README.md
+++ b/README.md
--- a/apps/globals.py
+++ b/apps/globals.py
 STRING_TRUE = ("yes", "true", "t", "y", "1", "")
 STRING_FALSE = ("no", "false", "f", "n", "0")
 REQUEST = ("storage", "send", "country", "timeseries", "map")
-DATATYPE = ("all", "buffer", "validated")
-GRANULARITY = ("year", "month")
+DATATYPE = ("buffer", "validated")
 ORDERBY = ("nslc", "time", "country", "protocol")
 OUTPUT = ("csv", "json", "text")
-MEDIA = ("all", "seedlink", "dataselect")
+MEDIA = ("dataselect", "seedlink", "station")
 NODATA_CODE = ("204", "404")
 TIMEOUT = 120

@@ -37,7 +36,6 @@ class Error:
    YEAR = "Invalid year: "
    TIME = "Bad date value: "
    DATATYPE = f"Accepted type values are: {DATATYPE}." + BAD_VAL
-    GRANULARITY = f"Accepted type values are: {GRANULARITY}." + BAD_VAL
    REQUEST = f"Accepted request values are: {REQUEST}." + BAD_VAL
    MEDIA = f"Accepted media values are: {MEDIA}." + BAD_VAL
    ORDERBY = f"Accepted orderby values are: {ORDERBY}." + BAD_VAL
@@ -45,7 +43,7 @@ class Error:
    NODATA_CODE = f"Accepted nodata values are: {NODATA_CODE}." + BAD_VAL
    NO_SELECTION = "Request contains no selections."
    NO_WILDCARDS = "Wildcards or lists are not allowed." + BAD_VAL
-    COUNTRY_ALL = f"The special option country=all has no meaning in list." + BAD_VAL
+    COUNTRY_ALL = "The special option country=all has no meaning in list." + BAD_VAL


 class HTTP:

--- a/apps/isoalpha2.py
+++ b/apps/isoalpha2.py
--- a/apps/output.py
+++ b/apps/output.py
@@ -21,8 +21,8 @@ from apps.utils import tictac

 def humanize_size(size_in_bytes):
    index = 0
-    size_units = ["B", "KB", "MB", "GB", "TB", "PB", "PB"]
-    while size_in_bytes >= 1024 and index < 6:
+    size_units = ["B", "KB", "MB", "GB", "TB", "PB", ""]
+    while size_in_bytes >= 1024 and index < 5:
        size_in_bytes /= 1024
        index += 1
    return f"{round(size_in_bytes, 2)} {size_units[index]}"
@@ -49,14 +49,12 @@ def sql_common_string(params):
        s = f"""{s} AND ({is_like_or_equal(params, "channel")})"""

    if params["request"] != "storage":
-        if "seedlink" in params["media"] and "dataselect" in params["media"]:
-            s = f"{s} AND (protocol = 'seedlink' OR protocol = 'dataselect')"
-        elif "seedlink" in params["media"]:
-            s = f"{s} AND protocol = 'seedlink'"
-        elif "dataselect" in params["media"]:
-            s = f"{s} AND protocol = 'dataselect'"
-
-    if params["request"] in ("send", "timeseries"):
+        # media parameter
+        if params["media"]:
+            s = f"""{s} AND ({is_like_or_equal(params, "media")})"""
+            s = s.replace("media", "protocol")
+
+        # country parameter
        if "all" not in params["country"] and params["country"] != "*":
            s = f"""{s} AND ({is_like_or_equal(params, "country")})"""

@@ -67,59 +65,88 @@ def sql_common_string(params):
    if params["end"]:
        end = datetime.strftime(params["end"], "%Y-%m-%d")
        s = f"""{s} AND date <= '{end}'"""
+    return s.replace("?", "_").replace("*", "%")
+
+
+def country_sql_request(params):
+    table = "sent_data_summary_weekly"
+    if params["country"] != "all":
+        s = f"SELECT coalesce(country, 'n/a'), sum(requests)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
+    else:
+        s = f"SELECT 'all' AS country, sum(requests)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
+    s = f"{s} {sql_common_string(params)}"
+    if params["country"] != "all":
+        s = f"{s} GROUP BY country ORDER BY 2 DESC"
    return s


-def sql_request(params):
-    """ Builds the PostgreSQL request """
+def map_sql_request(params):
+    table = "sent_data_summary_weekly"
+    s = f"SELECT country, sum(requests)::BIGINT FROM {table}"
+    s = f"{s} {sql_common_string(params)} GROUP BY country"
+    return s

-    if params["request"] == "storage":
-        columns = "year, network, station, channel, quality"
-        s = f"SELECT DISTINCT ON ({columns}) sum(size)::BIGINT, {columns}, date FROM dataholdings"
-        where = sql_common_string(params)
-        s = f"{s} {where} AND channel is not NULL"
-        if params["type"] != "all":
-            s = f"""{s} AND (type = '{params["type"]}')"""
-        if params["year"]:
-            s = f"""{s} AND ({is_like_or_equal(params, "year")})"""
-        s = f"{s} GROUP BY {columns}, date ORDER BY {columns}, date DESC"
+
+def send_sql_request(params):
+    table = "sent_data_summary_weekly"
+    if params["sum"]:
+        s = f"""SELECT '{params["network"]}' AS network, 'all' AS station, sum(bytes)::BIGINT AS size FROM {table}"""
+        s = f"{s} {sql_common_string(params)}"
+    elif params["ranklimit"]:
+        s = f"""SELECT network, station, size FROM
+        (SELECT *, DENSE_RANK() OVER (PARTITION BY network ORDER BY size DESC) AS rank FROM
+          (SELECT network, station, sum(bytes)::BIGINT AS size FROM {table} {sql_common_string(params)} GROUP BY network, station
+          ) AS table1
+        ) AS table2
+        WHERE rank <= {params["ranklimit"]};"""
+    else:
+        s = f"SELECT network, station, sum(bytes)::BIGINT AS size FROM {table} {sql_common_string(params)}"
+        s = f"{s} GROUP BY network, station ORDER BY network, size DESC, station"
+    return s
+
+
+def storage_sql_request(params):
+    table = "dataholdings"
+    columns = "year, network, station, channel, quality"
+    s = f"SELECT DISTINCT ON ({columns}) {columns}, date, sum(size)::BIGINT FROM {table}"
+    s = f"{s} {sql_common_string(params)} AND channel is not NULL"
+    if params["type"]:
+        s = f"""{s} AND ({is_like_or_equal(params, "type")})"""
        s = s.replace("buffer", "bud")
+    if params["year"]:
+        s = f"""{s} AND ({is_like_or_equal(params, "year")})"""
+    s = f"{s} GROUP BY {columns}, date ORDER BY {columns}, date DESC"
+    return s
+
+
+def timeseries_sql_request(params):
+    table = "sent_data_summary_weekly"
+    if params["country"] != "all":
+        s = f"SELECT date, country, sum(bytes)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
    else:
-        table = "sent_data_summary_weekly"
-        if params["request"] == "country":
-            s = f"SELECT 'all' AS country, sum(requests)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
-        elif params["request"] == "map":
-            s = f"SELECT country, sum(requests)::BIGINT FROM {table}"
-        elif params["request"] == "timeseries":
-            if params["country"] == "all":
-                s = f"SELECT date, 'all' as country, sum(bytes)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
-            else:
-                s = f"SELECT date, country, sum(bytes)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
-        elif params["request"] == "send":
-            if params["network"] == "*":
-                s = f"SELECT 'all' AS network, 'all' AS station, sum(bytes)::BIGINT AS size FROM {table}"
-            else:
-                s = f"SELECT network, station, sum(bytes)::BIGINT AS size FROM {table}"
+        s = f"SELECT date, 'all' as country, sum(bytes)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table}"
+    s = f"{s} {sql_common_string(params)}"
+    if params["country"] != "all":
+        s = f"{s} GROUP BY date, country ORDER BY date"
+    else:
+        s = f"{s} GROUP BY date ORDER BY date"
+    return s

-        where = sql_common_string(params)
-        s = f"{s} {where}"
-        if params["request"] == "country":
-            tmp = f"SELECT coalesce(country, 'n/a'), sum(requests)::BIGINT, hll_cardinality(hll_union_agg(clients))::INTEGER FROM {table} {where}"
-            if params["country"] != "*":
-                tmp = tmp + f""" AND ({is_like_or_equal(params, "country")})"""
-            s = f"{s} UNION {tmp} GROUP BY country ORDER BY 2 DESC"
-        elif params["request"] == "map":
-            s = f"{s} GROUP BY country"
-        elif params["request"] == "timeseries":
-            if params["country"] == "all":
-                s = f"{s} GROUP BY date ORDER BY date"
-            else:
-                s = f"{s} GROUP BY date, country ORDER BY date"
-        elif params["request"] == "send":
-            if params["network"] != "*":
-                s = f"{s} GROUP BY network, station ORDER BY network, size DESC, station"

-    return s.replace("?", "_").replace("*", "%")
+def sql_request(params):
+    """ Builds the PostgreSQL request """
+
+    if params["request"] == "country":
+        s = country_sql_request(params)
+    elif params["request"] == "map":
+        s = map_sql_request(params)
+    elif params["request"] == "send":
+        s = send_sql_request(params)
+    elif params["request"] == "storage":
+        s = storage_sql_request(params)
+    elif params["request"] == "timeseries":
+        s = timeseries_sql_request(params)
+    return s


 def collect_data(params):
@@ -139,23 +166,22 @@ def collect_data(params):

 def format_results(params, data):
    data = list(map(list, data))
-    if params["format"] not in ["csv", "json"]:
+    if params["format"] == "text":
        if params["request"] == "country":
            for row in data:
-                if row[1] and row[2]:
-                    row[:] = [row[0], "{:_}".format(row[1]), "{:_}".format(row[2])]
+                row[1] = format(row[1], ",") if row[1] else None
+                row[2] = format(row[2], ",") if row[2] else None
        elif params["request"] == "send":
            for row in data:
-                row[2] = "{:_}".format(row[2]) + f" ({humanize_size(row[2])})"
-
-    data = [[str(val) for val in row] for row in data]
+                if row[2]:
+                    row[2] = format(row[2], ",") + f" ({humanize_size(row[2])})"
    return data


 def get_header(params):
    if params["request"] == "storage":
-        header = ["size", "year", "network", "station", "channel", "quality"]
-        header.append("lastupdated")
+        header = ["year", "network", "station", "channel", "quality", "lastupdated"]
+        header.append("size")
    elif params["request"] == "country":
        header = ["country", "requests", "clients"]
    elif params["request"] == "map":
@@ -179,6 +205,7 @@ def get_column_widths(data, header=None):
 def records_to_text(params, data, sep=" "):
    text = ""
    header = get_header(params)
+    data = [[str(val) for val in row] for row in data]
    if params["format"] == "text":
        sizes = get_column_widths(data, header)
        # pad header and rows according to the maximum column width
@@ -186,9 +213,7 @@ def records_to_text(params, data, sep=" "):
        for row in data:
            row[:] = [val.ljust(sz) for val, sz in zip(row, sizes)]

-    if params["format"] != "request":
-        text = sep.join(header) + "\n"
-
+    text = sep.join(header) + "\n"
    data = [f"{sep.join(row)}\n" for row in data]
    text += "".join(data)
    return text
@@ -240,7 +265,6 @@ def map_requests(params, data):
            geodata["x"].append([x[0] for x in polygon[0]])
            geodata["y"].append([x[1] for x in polygon[0]])
            geodata["name"].append(country["properties"]["name"].lower())
-
    geodata["requests"] = [0 for i in range(0, len(geodata["name"]))]

    for code, requests in data:
@@ -259,7 +283,7 @@ def map_requests(params, data):

    TOOLS = "save, pan, wheel_zoom, box_zoom, reset"
    plot = figure(
-        title=f"Number of requests to the RESIF data center",
+        title="Number of requests to the RESIF data center",
        tools=TOOLS,
        plot_width=1200,
        plot_height=800,
@@ -300,7 +324,6 @@ def map_requests(params, data):
    )

    plot.add_layout(color_bar, "below")
-
    return make_response(file_html(plot, CDN, "resifws-statistics"))



--- a/apps/parameters.py
+++ b/apps/parameters.py
@@ -14,10 +14,12 @@ class Parameters:
        self.end = None
        self.country = "*"
        self.year = None
-        self.type = "all"
+        self.type = None
        self.request = None
-        self.media = "all"
+        self.media = None
        self.orderby = "nslc"
+        self.ranklimit = None
+        self.sum = "False"
        self.format = "text"
        self.nodata = "204"
        self.constraints = {
@@ -29,8 +31,8 @@ class Parameters:
                ("starttime", "start"),
                ("endtime", "end"),
            ],
-            "booleans": [],
-            "floats": [],
+            "booleans": ["sum"],
+            "floats": ["ranklimit"],
            "not_none": ["request"],
        }


--- a/apps/root.py
+++ b/apps/root.py
@@ -15,7 +15,6 @@ from apps.utils import error_param
 from apps.utils import error_request
 from apps.utils import is_valid_country
 from apps.utils import is_valid_datatype
-from apps.utils import is_valid_granularity
 from apps.utils import is_valid_media
 from apps.utils import is_valid_nodata
 from apps.utils import is_valid_orderby
@@ -44,28 +43,27 @@ def check_parameters(params):
    else:
        params["orderby"] = "nslc"

-    # media parameter validation
-    if params["media"]:
-        params["media"] = params["media"].split(",")
-        if "all" in params["media"]:
-            params["media"] = ["dataselect", "seedlink"]
-
-        for ind, media in enumerate(params["media"]):
-            if not is_valid_media(media):
-                return error_param(params, Error.MEDIA + str(media))
-            params["media"][ind] = media.lower()
-
    # year parameter validation
    if params["year"]:
        years = params["year"].split(",")
-        for ind, year in enumerate(years):
+        for year in years:
            if not is_valid_year(year):
                return error_param(params, Error.YEAR + str(year))

-    # type parameter validation
+    # media parameter validation
+    if params["media"]:
+        medias = params["media"].split(",")
+        for media in medias:
+            if not is_valid_media(media):
+                return error_param(params, Error.MEDIA + str(media))
+        params["media"] = params["media"].lower()
+
+    # data type parameter validation
    if params["type"]:
-        if not is_valid_datatype(params["type"]):
-            return error_param(params, Error.DATATYPE + str(params["type"]))
+        types = params["type"].split(",")
+        for datatype in types:
+            if not is_valid_datatype(datatype):
+                return error_param(params, Error.DATATYPE + str(datatype))
        params["type"] = params["type"].lower()

    # request parameter validation

--- a/apps/utils.py
+++ b/apps/utils.py
@@ -9,7 +9,6 @@ from flask import request, Response
 from apps.globals import DATATYPE
 from apps.globals import DOCUMENTATION_URI
 from apps.globals import Error
-from apps.globals import GRANULARITY
 from apps.globals import HTTP
 from apps.globals import MEDIA
 from apps.globals import NODATA_CODE
@@ -112,10 +111,6 @@ def is_valid_datatype(datatype):
    return datatype.lower() in DATATYPE if datatype else False


-def is_valid_granularity(granularity):
-    return granularity.lower() in GRANULARITY if granularity else False
-
-
 def is_valid_nodata(nodata):
    return nodata.lower() in NODATA_CODE if nodata else False


--- a/config.py
+++ b/config.py
--- a/docs/USAGE_EN.md
+++ b/docs/USAGE_EN.md
@@ -12,8 +12,9 @@ This service provides access to the RESIF-DC statistics.
    request-options    ::  (request=<country|map|send|storage|timeseries>)
    channel-options    ::  [net=<network> & sta=<station> & loc=<location> & cha=<channel>]
    date-options       ::  [starttime=<date>] & [endtime=<date>]
-    storage-options    ::  [year=<year>] & [type=<all|buffer|validated>]
-    send-options       ::  [country=<country_code>] & [media=<all|dataselect|seedlink>]
+    storage-options    ::  [year=<year>] & [type=<buffer|validated>]
+    send-options       ::  [ranklimit=<number>] & [sum=<boolean>]
+    other-options      ::  [country=<country_code>] & [media=<dataselect|seedlink|station>]
    output-options     ::  [format=<csv|json|text>]

    (..) required
@@ -26,7 +27,9 @@ This service provides access to the RESIF-DC statistics.
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=storage&net=FR&year=2018&type=validated">http://ws.resif.fr/resifws/statistics/1/query?request=storage&net=FR&year=2018&type=validated</a>

 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR">http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR</a>\
-<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT">http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT</a>
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT">http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT</a>\
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&ranklimit=5">http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&ranklimit=5</a>\
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&endtime=2020-12-31&sum=true">http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&endtime=2020-12-31&sum=true</a>

 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND">http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND</a>\
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND&country=all">http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND&country=all</a>\
@@ -63,18 +66,23 @@ The 'time' field represents the first day of a period of one week.
 | format     | text     | The output format. Accepted values are text (the default), json, and csv.      |
 | request    | send     | Type of statistic requested. Allowed values : <br> - __country__ : the number of requests from each country <br> - __map__ : a color coded map with the number of requests from each country<br> - __send__ : the volume of distributed data by protocol <br> - __storage__ : the volume of data stored <br> - __timeseries__ : returns a timeseries with the country, the number and the volume of requests |

-### Additional parameters for country, send, and timeseries request options
+### Additional parameters for storage request option
 | Parameter  | Example  | Discussion                                                                      |
 | :--------- | :------- | :------------------------------------------------------------------------------ |
-| country    | FR,GB    | Data are filtered to their country of origin. Use the country code (ISO 3166-1 alpha-2). If country=all the sum on all country is returned. |
-| media      | seedlink | Protocol used to request data. Allowed values : all (the default), dataselect, and seedlink |
+| type       | validated | Choose validated data or not. Allowed values : __buffer__, and __validated__ (all by default) |
+| year       | 2019,2020 | List of years for which the volume of data is requested.                       |

-### Additional parameters for storage request option
+### Additional parameters for send request option
+| Parameter  | Example | Discussion                                                                      |
+| :--------- | :------ | :------------------------------------------------------------------------------ |
+| ranklimit  | 5       | Give only the largest stations of each network.                                 |
+| sum        | true    | Give the total amount of data on selected network.                              |
+
+### Additional parameters for country, send, and timeseries request options
 | Parameter  | Example  | Discussion                                                                      |
 | :--------- | :------- | :------------------------------------------------------------------------------ |
-| type       | validated | Choose validated data or not. Allowed values : all (the default), buffer, and validated |
-| years      | 2019,2020 | List of years for which the volume of data is requested.                       |
-
+| country    | FR,GB    | Data are filtered to their country of origin. Use the country code (ISO 3166-1 alpha-2). The value __all__ returns the sum on all country. |
+| media      | seedlink | Protocol used to request data. Allowed values : __dataselect__, __seedlink__, and __station__ (all by default) |

 ## Station code details


--- a/docs/USAGE_FR.md
+++ b/docs/USAGE_FR.md
@@ -12,8 +12,9 @@ Ce service donne accès aux statistiques de RESIF-DC.
    request-options    ::  (request=<country|map|send|storage|timeseries>)
    channel-options    ::  [net=<network> & sta=<station> & loc=<location> & cha=<channel>]
    date-options       ::  [starttime=<date>] & [endtime=<date>]
-    storage-options    ::  [year=<year>] & [type=<all|buffer|validated>]
-    send-options       ::  [country=<country_code>] & [media=<all|dataselect|seedlink>]
+    storage-options    ::  [year=<year>] & [type=<buffer|validated>]
+    send-options       ::  [ranklimit=<number>] & [sum=<boolean>]
+    other-options      ::  [country=<country_code>] & [media=<dataselect|seedlink|station>]
    output-options     ::  [format=<csv|json|text>]

    (..) requis
@@ -26,7 +27,9 @@ Ce service donne accès aux statistiques de RESIF-DC.
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=storage&net=FR&year=2018&type=validated">http://ws.resif.fr/resifws/statistics/1/query?request=storage&net=FR&year=2018&type=validated</a>

 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR">http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR</a>\
-<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT">http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT</a>
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT">http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT</a>\
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&ranklimit=5">http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&ranklimit=5</a>\
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&endtime=2020-12-31&sum=true">http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&endtime=2020-12-31&sum=true</a>

 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND">http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND</a>\
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND&country=all">http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND&country=all</a>\
@@ -40,6 +43,7 @@ Ce service donne accès aux statistiques de RESIF-DC.
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=timeseries&starttime=2020-01-01&country=all&media=dataselect">http://ws.resif.fr/resifws/statistics/1/query?request=timeseries&starttime=2020-01-01&country=all&media=dataselect</a>


+
 ### Exemple de sortie avec la requête timeseries

 time       country bytes         clients\
@@ -60,21 +64,26 @@ La colonne 'time' représente le premier jour d'une période d'une semaine.
 | cha[nnel]  | HHZ     | Code de canal. Ce paramètre accepte les jokers.                                 |
 | start[time] | 2010-01-10T00:00:00 | Donne les réponses qui couvrent la période après la date donnée incluse. |
 | end[time]  | 2011-02-11T01:00:00 | Donne les réponses qui couvrent la période avant la date donnée incluse. |
-| format     | text     | Format de sortie. Valeurs autorisées : text, json et csv.                           |
+| format     | text    | Format de sortie. Valeurs autorisées : text, json et csv.                           |
 | request    | send    | Type de la statistique demandée. Valeurs autorisées : <br> - __country__ : nombre de requêtes passées par pays <br> - __map__ : une carte avec le nombre de requêtes provenant de chaque pays <br> - __send__ : volume de données distribuées par protocoles <br> - __storage__ : quantité de données stockées brutes et validées <br> - __timeseries__ : produit une série temporelle avec en colonne le pays, le nombre et la taille cumulés des requêtes |

-### Options supplémentaires spécifiques aux requêtes country, send et timeseries
+### Options supplémentaires spécifiques à la requête storage
 | Paramètre  | Exemple | Discussion                                                                      |
 | :--------- | :------ | :------------------------------------------------------------------------------ |
-| country    | FR,GB   | Filtre les réponses avec une liste des pays d'origine. Utilisez l'abréviation en deux lettres du pays (ISO 3166-1 alpha-2). Si country=all la somme sur tous les pays est renvoyée. |
-| media      | seedlink | Protocoles utilisés pour la requête. Valeurs autorisées : all (par défaut), dataselect et seedlink |
+| type       | validated | Choix entre les données stockées validées ou non. Valeurs autorisées : __buffer__ et __validated__ (toutes par défaut) |
+| year       | 2019,2020 | Liste des années pour lesquelles on demande la quantité de données. |

-### Options supplémentaires spécifiques à la requête storage
+### Options supplémentaires spécifiques à la requête send
 | Paramètre  | Exemple | Discussion                                                                      |
 | :--------- | :------ | :------------------------------------------------------------------------------ |
-| type       | validated | Choix entre les données stockées validées ou non. Valeurs autorisées : all (par défaut), buffer et validated |
-| years      | 2019,2020 | Liste des années pour lesquelles on demande la quantité de données. |
+| ranklimit  | 5       | Limite les réponses aux stations les plus volumineuses de chaque réseau.        |
+| sum        | true    | Donne la somme des volumes de données sur les réseaux sélectionnés.             |

+### Options supplémentaires spécifiques aux requêtes country, send et timeseries
+| Paramètre  | Exemple | Discussion                                                                      |
+| :--------- | :------ | :------------------------------------------------------------------------------ |
+| country    | FR,GB   | Filtre les réponses avec une liste des pays d'origine. Utilisez l'abréviation en deux lettres du pays (ISO 3166-1 alpha-2). La valeur __all__ donne la somme sur tous les pays. |
+| media      | seedlink | Protocoles utilisés pour la requête. Valeurs autorisées : __dataselect__, __seedlink__ et __station__ (toutes par défaut)|

 ## Détails sur la nomenclature des codes


--- a/requirements.txt
+++ b/requirements.txt
--- a/start.py
+++ b/start.py
--- a/static/images/en.png
+++ b/static/images/en.png
--- a/static/images/fr.png
+++ b/static/images/fr.png
--- a/static/images/logoresif.png
+++ b/static/images/logoresif.png
--- a/static/resifws.css
+++ b/static/resifws.css
--- a/templates/doc.html
+++ b/templates/doc.html
@@ -28,8 +28,9 @@ où :
 request-options    ::  (request=&lt;country|map|send|storage|timeseries&gt;)
 channel-options    ::  [net=&lt;network&gt; &amp; sta=&lt;station&gt; &amp; loc=&lt;location&gt; &amp; cha=&lt;channel&gt;]
 date-options       ::  [starttime=&lt;date&gt;] &amp; [endtime=&lt;date&gt;]
-storage-options    ::  [year=&lt;year&gt;] &amp; [type=&lt;all|buffer|validated&gt;]
-send-options       ::  [country=&lt;country_code&gt;] &amp; [media=&lt;all|dataselect|seedlink&gt;]
+storage-options    ::  [year=&lt;year&gt;] &amp; [type=&lt;buffer|validated&gt;]
+send-options       ::  [ranklimit=&lt;number&gt;] &amp; [sum=&lt;boolean&gt;]
+other-options      ::  [country=&lt;country_code&gt;] &amp; [media=&lt;dataselect|seedlink|station&gt;]
 output-options     ::  [format=&lt;csv|json|text&gt;]

 (..) requis
@@ -38,7 +39,9 @@ output-options     ::  [format=&lt;csv|json|text&gt;]
 <p><a href="http://ws.resif.fr/resifws/statistics/1/query?request=storage&net=FR&year=2020">http://ws.resif.fr/resifws/statistics/1/query?request=storage&amp;net=FR&amp;year=2020</a><br />
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=storage&net=FR&year=2018&type=validated">http://ws.resif.fr/resifws/statistics/1/query?request=storage&amp;net=FR&amp;year=2018&amp;type=validated</a></p>
 <p><a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR">http://ws.resif.fr/resifws/statistics/1/query?request=send&amp;media=dataselect&amp;net=FR</a><br />
-<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT">http://ws.resif.fr/resifws/statistics/1/query?request=send&amp;media=dataselect&amp;net=FR&amp;country=IT</a></p>
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&media=dataselect&net=FR&country=IT">http://ws.resif.fr/resifws/statistics/1/query?request=send&amp;media=dataselect&amp;net=FR&amp;country=IT</a><br />
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&ranklimit=5">http://ws.resif.fr/resifws/statistics/1/query?request=send&amp;net=FR,RA&amp;starttime=2020-01-01&amp;ranklimit=5</a><br />
+<a href="http://ws.resif.fr/resifws/statistics/1/query?request=send&net=FR,RA&starttime=2020-01-01&endtime=2020-12-31&sum=true">http://ws.resif.fr/resifws/statistics/1/query?request=send&amp;net=FR,RA&amp;starttime=2020-01-01&amp;endtime=2020-12-31&amp;sum=true</a></p>
 <p><a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND">http://ws.resif.fr/resifws/statistics/1/query?request=country&amp;net=RA,ND</a><br />
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND&country=all">http://ws.resif.fr/resifws/statistics/1/query?request=country&amp;net=RA,ND&amp;country=all</a><br />
 <a href="http://ws.resif.fr/resifws/statistics/1/query?request=country&net=RA,ND&country=IT,US,FR">http://ws.resif.fr/resifws/statistics/1/query?request=country&amp;net=RA,ND&amp;country=IT,US,FR</a></p>
@@ -110,7 +113,7 @@ output-options     ::  [format=&lt;csv|json|text&gt;]
 </tr>
 </tbody>
 </table>
-<h3 id="options-supplémentaires-spécifiques-aux-requêtes-country-send-et-timeseries">Options supplémentaires spécifiques aux requêtes country, send et timeseries</h3>
+<h3 id="options-supplémentaires-spécifiques-à-la-requête-storage">Options supplémentaires spécifiques à la requête storage</h3>
 <table>
 <colgroup>
 <col style="width: 10%" />
@@ -126,18 +129,18 @@ output-options     ::  [format=&lt;csv|json|text&gt;]
 </thead>
 <tbody>
 <tr class="odd">
-<td style="text-align: left;">country</td>
-<td style="text-align: left;">FR,GB</td>
-<td style="text-align: left;">Filtre les réponses avec une liste des pays d’origine. Utilisez l’abréviation en deux lettres du pays (ISO 3166-1 alpha-2). Si country=all la somme sur tous les pays est renvoyée.</td>
+<td style="text-align: left;">type</td>
+<td style="text-align: left;">validated</td>
+<td style="text-align: left;">Choix entre les données stockées validées ou non. Valeurs autorisées : <strong>buffer</strong> et <strong>validated</strong> (toutes par défaut)</td>
 </tr>
 <tr class="even">
-<td style="text-align: left;">media</td>
-<td style="text-align: left;">seedlink</td>
-<td style="text-align: left;">Protocoles utilisés pour la requête. Valeurs autorisées : all (par défaut), dataselect et seedlink</td>
+<td style="text-align: left;">year</td>
+<td style="text-align: left;">2019,2020</td>
+<td style="text-align: left;">Liste des années pour lesquelles on demande la quantité de données.</td>
 </tr>
 </tbody>
 </table>
-<h3 id="options-supplémentaires-spécifiques-à-la-requête-storage">Options supplémentaires spécifiques à la requête storage</h3>
+<h3 id="options-supplémentaires-spécifiques-à-la-requête-send">Options supplémentaires spécifiques à la requête send</h3>
 <table>
 <colgroup>
 <col style="width: 10%" />
@@ -153,14 +156,41 @@ output-options     ::  [format=&lt;csv|json|text&gt;]
 </thead>
 <tbody>
 <tr class="odd">
-<td style="text-align: left;">type</td>
-<td style="text-align: left;">validated</td>
-<td style="text-align: left;">Choix entre les données stockées validées ou non. Valeurs autorisées : all (par défaut), buffer et validated</td>
+<td style="text-align: left;">ranklimit</td>
+<td style="text-align: left;">5</td>
+<td style="text-align: left;">Limite les réponses aux stations les plus volumineuses de chaque réseau.</td>
 </tr>
 <tr class="even">
-<td style="text-align: left;">years</td>
-<td style="text-align: left;">2019,2020</td>
-<td style="text-align: left;">Liste des années pour lesquelles on demande la quantité de données.</td>
+<td style="text-align: left;">sum</td>
+<td style="text-align: left;">true</td>
+<td style="text-align: left;">Donne la somme des volumes de données sur les réseaux sélectionnés.</td>
+</tr>
+</tbody>
+</table>
+<h3 id="options-supplémentaires-spécifiques-aux-requêtes-country-send-et-timeseries">Options supplémentaires spécifiques aux requêtes country, send et timeseries</h3>
+<table>
+<colgroup>
+<col style="width: 10%" />
+<col style="width: 7%" />
+<col style="width: 82%" />
+</colgroup>
+<thead>
+<tr class="header">
+<th style="text-align: left;">Paramètre</th>
+<th style="text-align: left;">Exemple</th>
+<th style="text-align: left;">Discussion</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td style="text-align: left;">country</td>
+<td style="text-align: left;">FR,GB</td>
+<td style="text-align: left;">Filtre les réponses avec une liste des pays d’origine. Utilisez l’abréviation en deux lettres du pays (ISO 3166-1 alpha-2). La valeur <strong>all</strong> donne la somme sur tous les pays.</td>
+</tr>
+<tr class="even">
+<td style="text-align: left;">media</td>
+<td style="text-align: left;">seedlink</td>
+<td style="text-align: left;">Protocoles utilisés pour la requête. Valeurs autorisées : <strong>dataselect</strong>, <strong>seedlink</strong> et <strong>station</strong> (toutes par défaut)</td>
 </tr>
 </tbody>
 </table>

--- a/templates/doc_en.html
+++ b/templates/doc_en.html
@@ -28,8 +28,9 @@ where :
 request-options    ::