cl-hubeau 0.6.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cl_hubeau-0.6.0/PKG-INFO +360 -0
- cl_hubeau-0.6.0/README.md +322 -0
- cl_hubeau-0.6.0/cl_hubeau/__init__.py +9 -0
- cl_hubeau-0.6.0/cl_hubeau/config.py +16 -0
- cl_hubeau-0.6.0/cl_hubeau/constants.py +11 -0
- cl_hubeau-0.6.0/cl_hubeau/drinking_water_quality/__init__.py +12 -0
- cl_hubeau-0.6.0/cl_hubeau/drinking_water_quality/drinking_water_quality_scraper.py +206 -0
- cl_hubeau-0.6.0/cl_hubeau/drinking_water_quality/utils.py +142 -0
- cl_hubeau-0.6.0/cl_hubeau/hydrometry/__init__.py +18 -0
- cl_hubeau-0.6.0/cl_hubeau/hydrometry/hydrometry_scraper.py +436 -0
- cl_hubeau-0.6.0/cl_hubeau/hydrometry/utils.py +178 -0
- cl_hubeau-0.6.0/cl_hubeau/piezometry/__init__.py +16 -0
- cl_hubeau-0.6.0/cl_hubeau/piezometry/piezometry_scraper.py +287 -0
- cl_hubeau-0.6.0/cl_hubeau/piezometry/utils.py +149 -0
- cl_hubeau-0.6.0/cl_hubeau/session/__init__.py +3 -0
- cl_hubeau-0.6.0/cl_hubeau/session/session.py +416 -0
- cl_hubeau-0.6.0/cl_hubeau/superficial_waterbodies_quality/__init__.py +21 -0
- cl_hubeau-0.6.0/cl_hubeau/superficial_waterbodies_quality/superficial_waterbodies_quality_scraper.py +527 -0
- cl_hubeau-0.6.0/cl_hubeau/superficial_waterbodies_quality/utils.py +302 -0
- cl_hubeau-0.6.0/cl_hubeau/utils/__init__.py +12 -0
- cl_hubeau-0.6.0/cl_hubeau/utils/cities_deps_regions.py +256 -0
- cl_hubeau-0.6.0/cl_hubeau/utils/clean_cache.py +36 -0
- cl_hubeau-0.6.0/cl_hubeau/utils/prepare_loops.py +100 -0
- cl_hubeau-0.6.0/cl_hubeau/watercourses_flow/__init__.py +12 -0
- cl_hubeau-0.6.0/cl_hubeau/watercourses_flow/utils.py +156 -0
- cl_hubeau-0.6.0/cl_hubeau/watercourses_flow/watercourses_flow_scraper.py +327 -0
- cl_hubeau-0.6.0/pyproject.toml +57 -0
cl_hubeau-0.6.0/PKG-INFO
ADDED
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: cl-hubeau
|
|
3
|
+
Version: 0.6.0
|
|
4
|
+
Summary: Hubeau client to collect data from the different APIs
|
|
5
|
+
License: GPL-3.0-or-later
|
|
6
|
+
Keywords: france,water,hydrology
|
|
7
|
+
Author: Thomas Grandjean
|
|
8
|
+
Author-email: thomas.grandjean@developpement-durable.gouv.fr
|
|
9
|
+
Maintainer: Thomas Grandjean
|
|
10
|
+
Maintainer-email: thomas.grandjean@developpement-durable.gouv.fr
|
|
11
|
+
Requires-Python: >=3.9,<4.0
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering
|
|
22
|
+
Requires-Dist: diskcache (>=5.6.3,<6.0.0)
|
|
23
|
+
Requires-Dist: geopandas (>=1.0.1,<2.0.0)
|
|
24
|
+
Requires-Dist: importlib-metadata (>=8.2.0,<9.0.0)
|
|
25
|
+
Requires-Dist: pandas (>=2.2.2,<3.0.0)
|
|
26
|
+
Requires-Dist: pebble (>=5.0.7,<6.0.0)
|
|
27
|
+
Requires-Dist: platformdirs (>=4.2.2,<5.0.0)
|
|
28
|
+
Requires-Dist: pynsee (>=0.1.8,<0.2.0)
|
|
29
|
+
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
|
|
30
|
+
Requires-Dist: requests-cache (>=1.2.1,<2.0.0)
|
|
31
|
+
Requires-Dist: requests-ratelimiter (>=0.7.0,<0.8.0)
|
|
32
|
+
Requires-Dist: setuptools (>=75.8.0,<76.0.0)
|
|
33
|
+
Requires-Dist: tqdm (>=4.66.4,<5.0.0)
|
|
34
|
+
Project-URL: Documentation, https://tgrandje.github.io/cl-hubeau
|
|
35
|
+
Project-URL: Homepage, https://tgrandje.github.io/cl-hubeau
|
|
36
|
+
Project-URL: Repository, https://github.com/tgrandje/cl-hubeau/
|
|
37
|
+
Description-Content-Type: text/markdown
|
|
38
|
+
|
|
39
|
+
# cl-hubeau
|
|
40
|
+
|
|
41
|
+
Simple hub'eau client for python
|
|
42
|
+
|
|
43
|
+
This package is currently under active development.
|
|
44
|
+
Every API on [Hub'eau](hubeau.eaufrance.fr/) will be covered by this package in
|
|
45
|
+
due time.
|
|
46
|
+
|
|
47
|
+
At this stage, the following APIs are covered by cl-hubeau:
|
|
48
|
+
* [piezometry/piézométrie](https://hubeau.eaufrance.fr/page/api-piezometrie)
|
|
49
|
+
* [hydrometry/hydrométrie](https://hubeau.eaufrance.fr/page/api-hydrometrie)
|
|
50
|
+
* [drinking water quality/qualité de l'eau potable](https://hubeau.eaufrance.fr/page/api-qualite-eau-potable)
|
|
51
|
+
* [superficial waterbodies quality/qualité physico-chimique des cours d'eau'](https://hubeau.eaufrance.fr/page/api-qualite-cours-deau)
|
|
52
|
+
* [watercourses flow/écoulement des cours d'eau'](https://hubeau.eaufrance.fr/page/api-ecoulement)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
For any help on available kwargs for each endpoint, please refer
|
|
56
|
+
directly to the documentation on hubeau (this will not be covered
|
|
57
|
+
by the current documentation).
|
|
58
|
+
|
|
59
|
+
Assume that each function from cl-hubeau will be consistent with
|
|
60
|
+
it's hub'eau counterpart, with the exception of the `size` and
|
|
61
|
+
`page` or `cursor` arguments (those will be set automatically by
|
|
62
|
+
cl-hubeau to crawl allong the results).
|
|
63
|
+
|
|
64
|
+
## Parallelization
|
|
65
|
+
|
|
66
|
+
`cl-hubeau` already uses simple multithreading pools to perform requests.
|
|
67
|
+
In order not to endanger the webservers and share ressources among users, a
|
|
68
|
+
rate limiter is set to 10 queries per second. This limiter should work fine on
|
|
69
|
+
any given machine, whatever the context (even with a new parallelization
|
|
70
|
+
overlay).
|
|
71
|
+
|
|
72
|
+
However `cl-hubeau` should **NOT** be used in containers (or pods) with
|
|
73
|
+
parallelization. There is currently no way of tracking the queries' rate
|
|
74
|
+
among multiple machines: greedy queries may end up blacklisted by the
|
|
75
|
+
team managing Hub'eau.
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
## Configuration
|
|
79
|
+
|
|
80
|
+
First of all, you will need API keys from INSEE to use some high level operations,
|
|
81
|
+
which may loop over cities'official codes. Please refer to pynsee's
|
|
82
|
+
[API subscription Tutorial ](https://pynsee.readthedocs.io/en/latest/api_subscription.html)
|
|
83
|
+
for help.
|
|
84
|
+
|
|
85
|
+
## Basic examples
|
|
86
|
+
|
|
87
|
+
### Clean cache
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from cl_hubeau.utils import clean_all_cache
|
|
91
|
+
clean_all_cache
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Piezometry
|
|
95
|
+
|
|
96
|
+
3 high level functions are available (and one class for low level operations).
|
|
97
|
+
|
|
98
|
+
Get all piezometers (uses a 30 days caching):
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from cl_hubeau import piezometry
|
|
102
|
+
gdf = piezometry.get_all_stations()
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Get chronicles for the first 100 piezometers (uses a 30 days caching):
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
df = piezometry.get_chronicles(gdf["code_bss"].head(100).tolist())
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Get realtime data for the first 100 piezometers:
|
|
112
|
+
|
|
113
|
+
A small cache is stored to allow for realtime consumption (cache expires after
|
|
114
|
+
only 15 minutes). Please, adopt a responsible usage with this functionnality !
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
df = get_realtime_chronicles(gdf["code_bss"].head(100).tolist())
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Low level class to perform the same tasks:
|
|
121
|
+
|
|
122
|
+
Note that :
|
|
123
|
+
|
|
124
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
125
|
+
* the cache handling will be your responsibility, noticely for realtime data
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
with piezometry.PiezometrySession() as session:
|
|
129
|
+
df = session.get_chronicles(code_bss="07548X0009/F")
|
|
130
|
+
df = session.get_stations(code_departement=['02', '59', '60', '62', '80'], format="geojson")
|
|
131
|
+
df = session.get_chronicles_real_time(code_bss="07548X0009/F")
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Hydrometry
|
|
135
|
+
|
|
136
|
+
4 high level functions are available (and one class for low level operations).
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
Get all stations (uses a 30 days caching):
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
from cl_hubeau import hydrometry
|
|
143
|
+
gdf = hydrometry.get_all_stations()
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Get all sites (uses a 30 days caching):
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
gdf = hydrometry.get_all_sites()
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Get observations for the first 5 sites (uses a 30 days caching):
|
|
153
|
+
_Note that this will also work with stations (instead of sites)._
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
df = hydrometry.get_observations(gdf["code_site"].head(5).tolist())
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Get realtime data for the first 5 sites (no cache stored):
|
|
160
|
+
|
|
161
|
+
A small cache is stored to allow for realtime consumption (cache expires after
|
|
162
|
+
only 15 minutes). Please, adopt a responsible usage with this functionnality !
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
df = hydrometry.get_realtime_observations(gdf["code_site"].head(5).tolist())
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Low level class to perform the same tasks:
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
Note that :
|
|
173
|
+
|
|
174
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
175
|
+
* the cache handling will be your responsibility, noticely for realtime data
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
with hydrometry.HydrometrySession() as session:
|
|
179
|
+
df = session.get_stations(code_station="K437311001")
|
|
180
|
+
df = session.get_sites(code_departement=['02', '59', '60', '62', '80'], format="geojson")
|
|
181
|
+
df = session.get_realtime_observations(code_entite="K437311001")
|
|
182
|
+
df = session.get_observations(code_entite="K437311001")
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Drinking water quality
|
|
187
|
+
|
|
188
|
+
2 high level functions are available (and one class for low level operations).
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
Get all water networks (UDI) (uses a 30 days caching):
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from cl_hubeau import drinking_water_quality
|
|
195
|
+
df = drinking_water_quality.get_all_water_networks()
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Get the sanitary controls's results for nitrates on all networks of Paris, Lyon & Marseille
|
|
199
|
+
(uses a 30 days caching) for nitrates
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
networks = drinking_water_quality.get_all_water_networks()
|
|
203
|
+
networks = networks[
|
|
204
|
+
networks.nom_commune.isin(["PARIS", "MARSEILLE", "LYON"])
|
|
205
|
+
]["code_reseau"].unique().tolist()
|
|
206
|
+
|
|
207
|
+
df = drinking_water_quality.get_control_results(
|
|
208
|
+
codes_reseaux=networks,
|
|
209
|
+
code_parametre="1340"
|
|
210
|
+
)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Note that this query is heavy, even if this was already restricted to nitrates.
|
|
214
|
+
In theory, you could also query the API without specifying the substance you're tracking,
|
|
215
|
+
but you may hit the 20k threshold and trigger an exception.
|
|
216
|
+
|
|
217
|
+
You can also call the same function, using official city codes directly:
|
|
218
|
+
```python
|
|
219
|
+
df = drinking_water_quality.get_control_results(
|
|
220
|
+
codes_communes=['59350'],
|
|
221
|
+
code_parametre="1340"
|
|
222
|
+
)
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Low level class to perform the same tasks:
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
Note that :
|
|
229
|
+
|
|
230
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
231
|
+
* the cache handling will be your responsibility
|
|
232
|
+
|
|
233
|
+
```python
|
|
234
|
+
with drinking_water_quality.DrinkingWaterQualitySession() as session:
|
|
235
|
+
df = session.get_cities_networks(nom_commune="LILLE")
|
|
236
|
+
df = session.get_control_results(code_departement='02', code_parametre="1340")
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Superficial waterbodies quality
|
|
241
|
+
|
|
242
|
+
4 high level functions are available (and one class for low level operations).
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
Get all stations (uses a 30 days caching):
|
|
246
|
+
|
|
247
|
+
```python
|
|
248
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
249
|
+
df = superficial_waterbodies_quality.get_all_stations()
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Get all operations (uses a 30 days caching):
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
256
|
+
df = superficial_waterbodies_quality.get_all_operations()
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Note that this query is heavy, users should restrict it to a given territory.
|
|
260
|
+
For instance, you could use :
|
|
261
|
+
```python
|
|
262
|
+
df = superficial_waterbodies_quality.get_all_operations(code_region="11")
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Get all environmental conditions:
|
|
266
|
+
|
|
267
|
+
```python
|
|
268
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
269
|
+
df = superficial_waterbodies_quality.get_all_environmental_conditions()
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Note that this query is heavy, users should restrict it to a given territory.
|
|
273
|
+
For instance, you could use :
|
|
274
|
+
```python
|
|
275
|
+
df = superficial_waterbodies_quality.get_all_environmental_conditions(code_region="11")
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Get all physicochemical analysis:
|
|
279
|
+
```python
|
|
280
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
281
|
+
df = superficial_waterbodies_quality.get_all_analysis()
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Note that this query is heavy, users should restrict it to a given territory
|
|
285
|
+
and given parameters. For instance, you could use :
|
|
286
|
+
```python
|
|
287
|
+
df = superficial_waterbodies_quality.get_all_analysis(
|
|
288
|
+
code_departement="59",
|
|
289
|
+
code_parametre="1313"
|
|
290
|
+
)
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
Low level class to perform the same tasks:
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
Note that :
|
|
298
|
+
|
|
299
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
300
|
+
* the cache handling will be your responsibility
|
|
301
|
+
|
|
302
|
+
```python
|
|
303
|
+
with superficial_waterbodies_quality.SuperficialWaterbodiesQualitySession() as session:
|
|
304
|
+
df = session.get_stations(code_commune="59183")
|
|
305
|
+
df = session.get_operations(code_commune="59183")
|
|
306
|
+
df = session.get_environmental_conditions(code_commune="59183")
|
|
307
|
+
df = session.get_analysis(code_commune='59183', code_parametre="1340")
|
|
308
|
+
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Watercourses flow
|
|
312
|
+
|
|
313
|
+
3 high level functions are available (and one class for low level operations).
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
get_all_campaigns
|
|
318
|
+
|
|
319
|
+
Get all stations (uses a 30 days caching):
|
|
320
|
+
|
|
321
|
+
```python
|
|
322
|
+
from cl_hubeau import watercourses_flow
|
|
323
|
+
df = watercourses_flow.get_all_stations()
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
Get all observations (uses a 30 days caching):
|
|
327
|
+
|
|
328
|
+
```python
|
|
329
|
+
from cl_hubeau import watercourses_flow
|
|
330
|
+
df = watercourses_flow.get_all_observations()
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
Note that this query is heavy, users should restrict it to a given territory when possible.
|
|
334
|
+
For instance, you could use :
|
|
335
|
+
```python
|
|
336
|
+
df = watercourses_flow.get_all_observations(code_region="11")
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
Get all campagins:
|
|
340
|
+
|
|
341
|
+
```python
|
|
342
|
+
from cl_hubeau import watercourses_flow
|
|
343
|
+
df = watercourses_flow.get_all_campaigns()
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Low level class to perform the same tasks:
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
Note that :
|
|
350
|
+
|
|
351
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
352
|
+
* the cache handling will be your responsibility
|
|
353
|
+
|
|
354
|
+
```python
|
|
355
|
+
with watercourses_flow.WatercoursesFlowSession() as session:
|
|
356
|
+
df = session.get_stations(code_departement="59")
|
|
357
|
+
df = session.get_campaigns(code_campagne=[12])
|
|
358
|
+
df = session.get_observations(code_station="F6640008")
|
|
359
|
+
|
|
360
|
+
```
|
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
# cl-hubeau
|
|
2
|
+
|
|
3
|
+
Simple hub'eau client for python
|
|
4
|
+
|
|
5
|
+
This package is currently under active development.
|
|
6
|
+
Every API on [Hub'eau](hubeau.eaufrance.fr/) will be covered by this package in
|
|
7
|
+
due time.
|
|
8
|
+
|
|
9
|
+
At this stage, the following APIs are covered by cl-hubeau:
|
|
10
|
+
* [piezometry/piézométrie](https://hubeau.eaufrance.fr/page/api-piezometrie)
|
|
11
|
+
* [hydrometry/hydrométrie](https://hubeau.eaufrance.fr/page/api-hydrometrie)
|
|
12
|
+
* [drinking water quality/qualité de l'eau potable](https://hubeau.eaufrance.fr/page/api-qualite-eau-potable)
|
|
13
|
+
* [superficial waterbodies quality/qualité physico-chimique des cours d'eau'](https://hubeau.eaufrance.fr/page/api-qualite-cours-deau)
|
|
14
|
+
* [watercourses flow/écoulement des cours d'eau'](https://hubeau.eaufrance.fr/page/api-ecoulement)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
For any help on available kwargs for each endpoint, please refer
|
|
18
|
+
directly to the documentation on hubeau (this will not be covered
|
|
19
|
+
by the current documentation).
|
|
20
|
+
|
|
21
|
+
Assume that each function from cl-hubeau will be consistent with
|
|
22
|
+
it's hub'eau counterpart, with the exception of the `size` and
|
|
23
|
+
`page` or `cursor` arguments (those will be set automatically by
|
|
24
|
+
cl-hubeau to crawl allong the results).
|
|
25
|
+
|
|
26
|
+
## Parallelization
|
|
27
|
+
|
|
28
|
+
`cl-hubeau` already uses simple multithreading pools to perform requests.
|
|
29
|
+
In order not to endanger the webservers and share ressources among users, a
|
|
30
|
+
rate limiter is set to 10 queries per second. This limiter should work fine on
|
|
31
|
+
any given machine, whatever the context (even with a new parallelization
|
|
32
|
+
overlay).
|
|
33
|
+
|
|
34
|
+
However `cl-hubeau` should **NOT** be used in containers (or pods) with
|
|
35
|
+
parallelization. There is currently no way of tracking the queries' rate
|
|
36
|
+
among multiple machines: greedy queries may end up blacklisted by the
|
|
37
|
+
team managing Hub'eau.
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Configuration
|
|
41
|
+
|
|
42
|
+
First of all, you will need API keys from INSEE to use some high level operations,
|
|
43
|
+
which may loop over cities'official codes. Please refer to pynsee's
|
|
44
|
+
[API subscription Tutorial ](https://pynsee.readthedocs.io/en/latest/api_subscription.html)
|
|
45
|
+
for help.
|
|
46
|
+
|
|
47
|
+
## Basic examples
|
|
48
|
+
|
|
49
|
+
### Clean cache
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from cl_hubeau.utils import clean_all_cache
|
|
53
|
+
clean_all_cache
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Piezometry
|
|
57
|
+
|
|
58
|
+
3 high level functions are available (and one class for low level operations).
|
|
59
|
+
|
|
60
|
+
Get all piezometers (uses a 30 days caching):
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from cl_hubeau import piezometry
|
|
64
|
+
gdf = piezometry.get_all_stations()
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Get chronicles for the first 100 piezometers (uses a 30 days caching):
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
df = piezometry.get_chronicles(gdf["code_bss"].head(100).tolist())
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Get realtime data for the first 100 piezometers:
|
|
74
|
+
|
|
75
|
+
A small cache is stored to allow for realtime consumption (cache expires after
|
|
76
|
+
only 15 minutes). Please, adopt a responsible usage with this functionnality !
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
df = get_realtime_chronicles(gdf["code_bss"].head(100).tolist())
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Low level class to perform the same tasks:
|
|
83
|
+
|
|
84
|
+
Note that :
|
|
85
|
+
|
|
86
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
87
|
+
* the cache handling will be your responsibility, noticely for realtime data
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
with piezometry.PiezometrySession() as session:
|
|
91
|
+
df = session.get_chronicles(code_bss="07548X0009/F")
|
|
92
|
+
df = session.get_stations(code_departement=['02', '59', '60', '62', '80'], format="geojson")
|
|
93
|
+
df = session.get_chronicles_real_time(code_bss="07548X0009/F")
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Hydrometry
|
|
97
|
+
|
|
98
|
+
4 high level functions are available (and one class for low level operations).
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
Get all stations (uses a 30 days caching):
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
from cl_hubeau import hydrometry
|
|
105
|
+
gdf = hydrometry.get_all_stations()
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Get all sites (uses a 30 days caching):
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
gdf = hydrometry.get_all_sites()
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Get observations for the first 5 sites (uses a 30 days caching):
|
|
115
|
+
_Note that this will also work with stations (instead of sites)._
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
df = hydrometry.get_observations(gdf["code_site"].head(5).tolist())
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Get realtime data for the first 5 sites (no cache stored):
|
|
122
|
+
|
|
123
|
+
A small cache is stored to allow for realtime consumption (cache expires after
|
|
124
|
+
only 15 minutes). Please, adopt a responsible usage with this functionnality !
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
df = hydrometry.get_realtime_observations(gdf["code_site"].head(5).tolist())
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Low level class to perform the same tasks:
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
Note that :
|
|
135
|
+
|
|
136
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
137
|
+
* the cache handling will be your responsibility, noticely for realtime data
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
with hydrometry.HydrometrySession() as session:
|
|
141
|
+
df = session.get_stations(code_station="K437311001")
|
|
142
|
+
df = session.get_sites(code_departement=['02', '59', '60', '62', '80'], format="geojson")
|
|
143
|
+
df = session.get_realtime_observations(code_entite="K437311001")
|
|
144
|
+
df = session.get_observations(code_entite="K437311001")
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Drinking water quality
|
|
149
|
+
|
|
150
|
+
2 high level functions are available (and one class for low level operations).
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
Get all water networks (UDI) (uses a 30 days caching):
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from cl_hubeau import drinking_water_quality
|
|
157
|
+
df = drinking_water_quality.get_all_water_networks()
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Get the sanitary controls's results for nitrates on all networks of Paris, Lyon & Marseille
|
|
161
|
+
(uses a 30 days caching) for nitrates
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
networks = drinking_water_quality.get_all_water_networks()
|
|
165
|
+
networks = networks[
|
|
166
|
+
networks.nom_commune.isin(["PARIS", "MARSEILLE", "LYON"])
|
|
167
|
+
]["code_reseau"].unique().tolist()
|
|
168
|
+
|
|
169
|
+
df = drinking_water_quality.get_control_results(
|
|
170
|
+
codes_reseaux=networks,
|
|
171
|
+
code_parametre="1340"
|
|
172
|
+
)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Note that this query is heavy, even if this was already restricted to nitrates.
|
|
176
|
+
In theory, you could also query the API without specifying the substance you're tracking,
|
|
177
|
+
but you may hit the 20k threshold and trigger an exception.
|
|
178
|
+
|
|
179
|
+
You can also call the same function, using official city codes directly:
|
|
180
|
+
```python
|
|
181
|
+
df = drinking_water_quality.get_control_results(
|
|
182
|
+
codes_communes=['59350'],
|
|
183
|
+
code_parametre="1340"
|
|
184
|
+
)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Low level class to perform the same tasks:
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
Note that :
|
|
191
|
+
|
|
192
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
193
|
+
* the cache handling will be your responsibility
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
with drinking_water_quality.DrinkingWaterQualitySession() as session:
|
|
197
|
+
df = session.get_cities_networks(nom_commune="LILLE")
|
|
198
|
+
df = session.get_control_results(code_departement='02', code_parametre="1340")
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Superficial waterbodies quality
|
|
203
|
+
|
|
204
|
+
4 high level functions are available (and one class for low level operations).
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
Get all stations (uses a 30 days caching):
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
211
|
+
df = superficial_waterbodies_quality.get_all_stations()
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Get all operations (uses a 30 days caching):
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
218
|
+
df = superficial_waterbodies_quality.get_all_operations()
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Note that this query is heavy, users should restrict it to a given territory.
|
|
222
|
+
For instance, you could use :
|
|
223
|
+
```python
|
|
224
|
+
df = superficial_waterbodies_quality.get_all_operations(code_region="11")
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Get all environmental conditions:
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
231
|
+
df = superficial_waterbodies_quality.get_all_environmental_conditions()
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Note that this query is heavy, users should restrict it to a given territory.
|
|
235
|
+
For instance, you could use :
|
|
236
|
+
```python
|
|
237
|
+
df = superficial_waterbodies_quality.get_all_environmental_conditions(code_region="11")
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Get all physicochemical analysis:
|
|
241
|
+
```python
|
|
242
|
+
from cl_hubeau import superficial_waterbodies_quality
|
|
243
|
+
df = superficial_waterbodies_quality.get_all_analysis()
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Note that this query is heavy, users should restrict it to a given territory
|
|
247
|
+
and given parameters. For instance, you could use :
|
|
248
|
+
```python
|
|
249
|
+
df = superficial_waterbodies_quality.get_all_analysis(
|
|
250
|
+
code_departement="59",
|
|
251
|
+
code_parametre="1313"
|
|
252
|
+
)
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
Low level class to perform the same tasks:
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
Note that :
|
|
260
|
+
|
|
261
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
262
|
+
* the cache handling will be your responsibility
|
|
263
|
+
|
|
264
|
+
```python
|
|
265
|
+
with superficial_waterbodies_quality.SuperficialWaterbodiesQualitySession() as session:
|
|
266
|
+
df = session.get_stations(code_commune="59183")
|
|
267
|
+
df = session.get_operations(code_commune="59183")
|
|
268
|
+
df = session.get_environmental_conditions(code_commune="59183")
|
|
269
|
+
df = session.get_analysis(code_commune='59183', code_parametre="1340")
|
|
270
|
+
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Watercourses flow
|
|
274
|
+
|
|
275
|
+
3 high level functions are available (and one class for low level operations).
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
get_all_campaigns
|
|
280
|
+
|
|
281
|
+
Get all stations (uses a 30 days caching):
|
|
282
|
+
|
|
283
|
+
```python
|
|
284
|
+
from cl_hubeau import watercourses_flow
|
|
285
|
+
df = watercourses_flow.get_all_stations()
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Get all observations (uses a 30 days caching):
|
|
289
|
+
|
|
290
|
+
```python
|
|
291
|
+
from cl_hubeau import watercourses_flow
|
|
292
|
+
df = watercourses_flow.get_all_observations()
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Note that this query is heavy, users should restrict it to a given territory when possible.
|
|
296
|
+
For instance, you could use :
|
|
297
|
+
```python
|
|
298
|
+
df = watercourses_flow.get_all_observations(code_region="11")
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Get all campagins:
|
|
302
|
+
|
|
303
|
+
```python
|
|
304
|
+
from cl_hubeau import watercourses_flow
|
|
305
|
+
df = watercourses_flow.get_all_campaigns()
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Low level class to perform the same tasks:
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
Note that :
|
|
312
|
+
|
|
313
|
+
* the API is forbidding results > 20k rows and you may need inner loops
|
|
314
|
+
* the cache handling will be your responsibility
|
|
315
|
+
|
|
316
|
+
```python
|
|
317
|
+
with watercourses_flow.WatercoursesFlowSession() as session:
|
|
318
|
+
df = session.get_stations(code_departement="59")
|
|
319
|
+
df = session.get_campaigns(code_campagne=[12])
|
|
320
|
+
df = session.get_observations(code_station="F6640008")
|
|
321
|
+
|
|
322
|
+
```
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# -*- coding: utf-8 -*-
|
|
3
|
+
"""
|
|
4
|
+
Package configuration
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from datetime import timedelta
|
|
8
|
+
|
|
9
|
+
_config = {
|
|
10
|
+
"DEFAULT_EXPIRE_AFTER": timedelta(days=30),
|
|
11
|
+
"DEFAULT_EXPIRE_AFTER_REALTIME": timedelta(minutes=15),
|
|
12
|
+
"SIZE": 1000, # Default size for each API's result
|
|
13
|
+
"RATE_LIMITER": 10, # queries per second
|
|
14
|
+
"TQDM_LEAVE": None, # keep tqdm progressbar after completion
|
|
15
|
+
"THREADS": 10, # Max number of threads to perform a request to an endpoint
|
|
16
|
+
}
|