Skip to content

FEWS Rest API

Module for calling the FEWS REST API.

The module contains one class and methods corresponding with the FEWS PI-REST requests: https://publicwiki.deltares.nl/display/FEWSDOC/FEWS+PI+REST+Web+Service

Api

Python API for the Deltares FEWS PI REST Web Service.

For more info on how-to work with the FEWS REST Web Service, visit the Deltares Website: https://publicwiki.deltares.nl/display/FEWSDOC/FEWS+PI+REST+Web+Service

Source code in src\fewspy\api.py 
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class Api:
    """
    Python API for the Deltares FEWS PI REST Web Service.

    For more info on how-to work with the FEWS REST Web Service, visit the Deltares Website: https://publicwiki.deltares.nl/display/FEWSDOC/FEWS+PI+REST+Web+Service
    """

    def __init__(self, url, logger=None, ssl_verify=None):
        self.document_format = "PI_JSON"
        self.logger = logger
        self.timer = Timer(logger)
        self.url, verify = validate_url(url)

        # set ssl_verify
        if ssl_verify is None:
            self.ssl_verify = verify
        else:
            self.ssl_verify = ssl_verify

        # set logger
        if logger is None:
            self.logger = LOGGER
        else:
            self.logger = logger

    def __kwargs(self, url_post_fix: str, kwargs: dict) -> dict:
        kwargs = {
            **kwargs,
            **dict(
                url=f"{self.url}{url_post_fix}",
                document_format=self.document_format,
                verify=self.ssl_verify,
                logger=self.logger,
            ),
        }
        kwargs.pop("self")
        kwargs.pop("parallel", None)
        return kwargs

    def get_parameters(self, filter_id=None):
        """
        Get FEWS qualifiers as a pandas DataFrame

        Args:
            filter_id (str): the FEWS id of the filter to pass as request parameter

        Returns:
            df (pandas.DataFrame): Pandas dataframe with index "id" and columns
            "name" and "group_id".

        """

        kwargs = self.__kwargs(url_post_fix="parameters", kwargs=locals())
        result = get_parameters(**kwargs)

        return result

    def get_filters(self, filter_id=None):
        """
        Get FEWS qualifiers as a pandas DataFrame

        Args:
            E.g. http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/qualifiers
            filter_id (str): the FEWS id of the filter to pass as request parameter

        Returns:
            df (pandas.DataFrame): Pandas dataframe with index "id" and columns
            "name" and "group_id".

        """

        kwargs = self.__kwargs(url_post_fix="filters", kwargs=locals())
        result = get_filters(**kwargs)

        return result

    def get_locations(self, filter_id=None, attributes=[], remove_duplicates=False):
        """
        Get FEWS qualifiers as a pandas DataFrame

        Args:
            E.g. http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/qualifiers
            filter_id (str): the FEWS id of the filter to pass as request parameter
            attributes (list): if not emtpy, the location attributes to include as columns in the pandas DataFrame.
            remove_duplicates (bool): if True, duplicated location_ids are removed. Default = False

        Returns:
            df (pandas.DataFrame): Pandas dataframe with index "id" and columns
            "name" and "group_id".

        """

        kwargs = self.__kwargs(url_post_fix="locations", kwargs=locals())
        result = get_locations(**kwargs)

        return result

    def get_qualifiers(self) -> pd.DataFrame:
        """
        Get FEWS qualifiers as Pandas DataFrame

        Returns:
            df (pandas.DataFrame): Pandas dataframe with index "id" and columns
            "name" and "group_id".

        """
        url = f"{self.url}qualifiers"
        result = get_qualifiers(url, verify=self.ssl_verify, logger=self.logger)
        return result

    def get_timezone_id(self):
        """
        Get FEWS timezone_id

        Returns:
            str: timezone id FEWS API is running on

        """
        url = f"{self.url}timezoneid"
        result = get_timezone_id(url, verify=self.ssl_verify, logger=self.logger)
        return result

    def get_time_series(
        self,
        filter_id,
        location_ids=None,
        start_time=None,
        end_time=None,
        parameter_ids=None,
        qualifier_ids=None,
        thinning=None,
        only_headers=False,
        omit_missing=True,
        show_statistics=False,
        parallel=False,
    ):
        """
        Get FEWS qualifiers as a pandas DataFrame

        Args:
            filter_id (str): the FEWS id of the filter to pass as request parameter
            location_ids (list): list with FEWS location ids to extract timeseries from. Defaults to None.
            parameter_ids (list): list with FEWS parameter ids to extract timeseries from. Defaults to None.
            qualifier_ids (list): list with FEWS qualifier ids to extract timeseries from. Defaults to None.
            start_time (datetime.datetime): datetime-object with start datetime to use in request. Defaults to None.
            end_time (datetime.datetime): datetime-object with end datetime to use in request. Defaults to None.
            thinning (int): integer value for thinning parameter to use in request. Defaults to None.
            only_headers (bool): if True, only headers will be returned. Defaults to False.
            omit_missing (bool): if True, no missings values will be returned. Defaults to True.
            show_statistics (bool): if True, time series statistics will be included in header. Defaults to False.
            parallel (bool): if True, timeseries are requested by the asynchronous wrapper. Defaults to False

        Returns:
            df (pandas.DataFrame): Pandas dataframe with index "id" and columns
            "name" and "group_id".

        """
        kwargs = self.__kwargs(url_post_fix="timeseries", kwargs=locals())
        if parallel:
            kwargs.pop("only_headers")
            kwargs.pop("show_statistics")
            result = get_time_series_async(**kwargs)
        else:
            result = get_time_series(**kwargs)

        return result

get_filters(filter_id=None)

Get FEWS qualifiers as a pandas DataFrame

Parameters:

Name Type Description Default
E.g. http

//localhost:8080/FewsWebServices/rest/fewspiservice/v1/qualifiers

 required
filter_id str

the FEWS id of the filter to pass as request parameter

 None

Returns:

Name Type Description
df DataFrame

Pandas dataframe with index "id" and columns

"name" and "group_id".
Source code in src\fewspy\api.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_filters(self, filter_id=None):
    """
    Get FEWS qualifiers as a pandas DataFrame

    Args:
        E.g. http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/qualifiers
        filter_id (str): the FEWS id of the filter to pass as request parameter

    Returns:
        df (pandas.DataFrame): Pandas dataframe with index "id" and columns
        "name" and "group_id".

    """

    kwargs = self.__kwargs(url_post_fix="filters", kwargs=locals())
    result = get_filters(**kwargs)

    return result

get_locations(filter_id=None, attributes=[], remove_duplicates=False)

Get FEWS qualifiers as a pandas DataFrame

Parameters:

Name Type Description Default
E.g. http

//localhost:8080/FewsWebServices/rest/fewspiservice/v1/qualifiers

 required
filter_id str

the FEWS id of the filter to pass as request parameter

 None
attributes list

if not emtpy, the location attributes to include as columns in the pandas DataFrame.

 []
remove_duplicates bool

if True, duplicated location_ids are removed. Default = False

 False

Returns:

Name Type Description
df DataFrame

Pandas dataframe with index "id" and columns

"name" and "group_id".
Source code in src\fewspy\api.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def get_locations(self, filter_id=None, attributes=[], remove_duplicates=False):
    """
    Get FEWS qualifiers as a pandas DataFrame

    Args:
        E.g. http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/qualifiers
        filter_id (str): the FEWS id of the filter to pass as request parameter
        attributes (list): if not emtpy, the location attributes to include as columns in the pandas DataFrame.
        remove_duplicates (bool): if True, duplicated location_ids are removed. Default = False

    Returns:
        df (pandas.DataFrame): Pandas dataframe with index "id" and columns
        "name" and "group_id".

    """

    kwargs = self.__kwargs(url_post_fix="locations", kwargs=locals())
    result = get_locations(**kwargs)

    return result

get_parameters(filter_id=None)

Get FEWS qualifiers as a pandas DataFrame

Parameters:

Name Type Description Default
filter_id str

the FEWS id of the filter to pass as request parameter

 None

Returns:

Name Type Description
df DataFrame

Pandas dataframe with index "id" and columns

"name" and "group_id".
Source code in src\fewspy\api.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def get_parameters(self, filter_id=None):
    """
    Get FEWS qualifiers as a pandas DataFrame

    Args:
        filter_id (str): the FEWS id of the filter to pass as request parameter

    Returns:
        df (pandas.DataFrame): Pandas dataframe with index "id" and columns
        "name" and "group_id".

    """

    kwargs = self.__kwargs(url_post_fix="parameters", kwargs=locals())
    result = get_parameters(**kwargs)

    return result

get_qualifiers()

Get FEWS qualifiers as Pandas DataFrame

Returns:

Name Type Description
df DataFrame

Pandas dataframe with index "id" and columns
DataFrame

"name" and "group_id".
Source code in src\fewspy\api.py 
126
127
128
129
130
131
132
133
134
135
136
137
def get_qualifiers(self) -> pd.DataFrame:
    """
    Get FEWS qualifiers as Pandas DataFrame

    Returns:
        df (pandas.DataFrame): Pandas dataframe with index "id" and columns
        "name" and "group_id".

    """
    url = f"{self.url}qualifiers"
    result = get_qualifiers(url, verify=self.ssl_verify, logger=self.logger)
    return result

get_time_series(filter_id, location_ids=None, start_time=None, end_time=None, parameter_ids=None, qualifier_ids=None, thinning=None, only_headers=False, omit_missing=True, show_statistics=False, parallel=False)

Get FEWS qualifiers as a pandas DataFrame

Parameters:

Name Type Description Default
filter_id str

the FEWS id of the filter to pass as request parameter

 required
location_ids list

list with FEWS location ids to extract timeseries from. Defaults to None.

 None
parameter_ids list

list with FEWS parameter ids to extract timeseries from. Defaults to None.

 None
qualifier_ids list

list with FEWS qualifier ids to extract timeseries from. Defaults to None.

 None
start_time datetime

datetime-object with start datetime to use in request. Defaults to None.

 None
end_time datetime

datetime-object with end datetime to use in request. Defaults to None.

 None
thinning int

integer value for thinning parameter to use in request. Defaults to None.

 None
only_headers bool

if True, only headers will be returned. Defaults to False.

 False
omit_missing bool

if True, no missings values will be returned. Defaults to True.

 True
show_statistics bool

if True, time series statistics will be included in header. Defaults to False.

 False
parallel bool

if True, timeseries are requested by the asynchronous wrapper. Defaults to False

 False

Returns:

Name Type Description
df DataFrame

Pandas dataframe with index "id" and columns

"name" and "group_id".
Source code in src\fewspy\api.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
def get_time_series(
    self,
    filter_id,
    location_ids=None,
    start_time=None,
    end_time=None,
    parameter_ids=None,
    qualifier_ids=None,
    thinning=None,
    only_headers=False,
    omit_missing=True,
    show_statistics=False,
    parallel=False,
):
    """
    Get FEWS qualifiers as a pandas DataFrame

    Args:
        filter_id (str): the FEWS id of the filter to pass as request parameter
        location_ids (list): list with FEWS location ids to extract timeseries from. Defaults to None.
        parameter_ids (list): list with FEWS parameter ids to extract timeseries from. Defaults to None.
        qualifier_ids (list): list with FEWS qualifier ids to extract timeseries from. Defaults to None.
        start_time (datetime.datetime): datetime-object with start datetime to use in request. Defaults to None.
        end_time (datetime.datetime): datetime-object with end datetime to use in request. Defaults to None.
        thinning (int): integer value for thinning parameter to use in request. Defaults to None.
        only_headers (bool): if True, only headers will be returned. Defaults to False.
        omit_missing (bool): if True, no missings values will be returned. Defaults to True.
        show_statistics (bool): if True, time series statistics will be included in header. Defaults to False.
        parallel (bool): if True, timeseries are requested by the asynchronous wrapper. Defaults to False

    Returns:
        df (pandas.DataFrame): Pandas dataframe with index "id" and columns
        "name" and "group_id".

    """
    kwargs = self.__kwargs(url_post_fix="timeseries", kwargs=locals())
    if parallel:
        kwargs.pop("only_headers")
        kwargs.pop("show_statistics")
        result = get_time_series_async(**kwargs)
    else:
        result = get_time_series(**kwargs)

    return result

get_timezone_id()

Get FEWS timezone_id

Returns:

Name Type Description
str

timezone id FEWS API is running on
Source code in src\fewspy\api.py 
139
140
141
142
143
144
145
146
147
148
149
def get_timezone_id(self):
    """
    Get FEWS timezone_id

    Returns:
        str: timezone id FEWS API is running on

    """
    url = f"{self.url}timezoneid"
    result = get_timezone_id(url, verify=self.ssl_verify, logger=self.logger)
    return result