README.md 14.2 KB
Newer Older
1
2
3
4
5
6
7

- [1. Portic data API : get dynamic data from database](#1-portic-data-api--get-dynamic-data-from-database)
  - [1.1. Installation](#11-installation)
    - [1.1.1. Running without Apache](#111-running-without-apache)
    - [1.1.2. Running with Apache](#112-running-with-apache)
    - [1.1.3. Debug things](#113-debug-things)
  - [1.2. List of possible requests](#12-list-of-possible-requests)
8
    - [1.2.1. Principes](#121-principes)
9
    - [1.2.2. /fieldnames?](#122-fieldnames)
10
    - [1.2.3. /pointcalls?](#123-pointcalls)
11
12
    - [1.2.4. /travels?](#124-travels)
      - [1.2.4.1. /details/departures?lon=lat=radius=](#1241-detailsdepartureslonlatradius)
13
14
      - [1.2.4.2. /agg/departures?lon=lat=radius=](#1242-aggdepartureslonlatradius)
      - [1.2.4.3. /agg/destinations?lon=lat=radius=](#1243-aggdestinationslonlatradius)
15
    - [1.2.5. /flows?](#125-flows)
16
    - [1.2.6. /ports?](#126-ports)
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43



# 1. Portic data API : get dynamic data from database

Web API for data above the postgres database developped with Flask

![](temps_telechargement.png)

## 1.1. Installation

Neep Python 3 to be installed

Clone or download this git repo, then

pip3 install -r requirements.txt

### 1.1.1. Running without Apache

python apidata.py

(or create a virtualenv, then activate it and pip install -r requirements && python apidata.py)

Backend is running and serve the data on http://localhost:5004 (change the PORT variable in config.py)

### 1.1.2. Running with Apache

44
45
```bash

46
47
48
49
50
cd /home/plumegeo/navigo/Viz/porticapi
git fetch origin master
git reset --hard origin/master
cd ..
cp porticapi/porticapi/apidata.py porticapi/porticapi/__init__.py
51
52
53
54
55
56
57
58

sudo chown :www-data /home/plumegeo/navigo/Viz/porticapi/ -R
sudo chmod 755 /home/plumegeo/navigo/Viz/porticapi/ -R
for fic in $(find /home/plumegeo/navigo/Viz/porticapi/porticapi -type f -name "*.py"); do sudo dos2unix $fic; done

sudo  service apache2 reload
```

59
60
61
62
63
64
65
66

### 1.1.3. Debug things

C:\Python37\lib\site-packages\flask\app.py:2446: DtypeWarning: Columns (31) have mixed types.Specify dtype option on import or set low_memory=False.


## 1.2. List of possible requests

67
### 1.2.1. Principes
68

69
70
71
72
Les données exposées sont une compilation des données de navigocorpus pour 1787, du registre de la santé de Marseille et des congés du G5, ainsi que les cahiers du petit cabotage sur Marseille. Elles sont récupérées depuis la [base navigocorpus](http://navigocorpus.org/) (logiciel Filemaker) en ligne et téléchargées dans postgres avec le code d'un [ETL disponible dans le gitlab d'humanum](https://gitlab.huma-num.fr/portic/navigocorpus/-/tree/master/ETL). 

URL de l'API : **http://data.portic.fr/api/**

73
74
Une requête particulière : *fieldnames* récupère des métadonnées sur l'API, avec la liste des attributs, avec leur nom court et long, leur type et leur signification. 

75
Trois grands types de requête : 
76
77
- **travels** : les données de trajectoire calculées
- **pointcalls** : les données d'observation à chaque escale des navires
78
- **flows** : les données de trajectoire filtrées suivant les ports touchés, la direction (entrante, sortante, around), et le degré d'éloignement des escales dans l'ordre
79
80
81
82
83
84

Liste des paramètres communs à chaque requête et valeur par défaut en gras: 
- params : **all** | tableau des noms longs des attributs de l'API à renvoyer
- format : csv | **json**
- shortenfields : true | **false**
- both_to : true | **false**
85
- date : YYYY | **1787**
86
87
- zipped : true | **false**

88
89
90

Si le parametre n'est pas précisé, le serveur opte pour la valeur de paramètre par défaut (en gras).

91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
**params** permet de filtrer la liste des attributs récupérés. Par exemple : 
<http://data.portic.fr/api/travels/?params=id,departure,destination>

Renvoie : 
```json
[{"id":"0000001N- 01","departure":"Boulogne sur Mer","destination":"Angleterre","destination_uhgs_id":"A0390929"},{"id":"0000001N- 02","departure":"Angleterre","destination":"Boulogne sur Mer","destination_uhgs_id":"A0152606"}, 
..., 
{"id":"0021518N- 01","departure":"Honfleur","destination":"Havre du Four en Terreneuve","destination_uhgs_id":"B2119892"}] 
```

**format** permet de télécharger soit au format CSV soit au format JSON les données. 
Par exemple : 
- <http://data.portic.fr/api/fieldnames/?format=csv>
- <http://data.portic.fr/api/travels/?format=csv>
- <http://data.portic.fr/api/pointcalls/?format=csv>

Pour avoir les mêmes données en JSON : 
- <http://data.portic.fr/api/fieldnames/?format=json>
- <http://data.portic.fr/api/travels/?format=json>
- <http://data.portic.fr/api/pointcalls/?format=json>
111

112

113
114
115
116
117
118
119
120
121
122
**shortenfields** permet de raccourcir les noms des attributs et donc d'alléger la taille du JSON téléchargé. L'API permet de récupérer le mapping entre ces noms courts et longs avec <http://data.portic.fr/api/fieldnames/?format=json>
Exemple : 
<http://data.portic.fr/api/pointcalls/?format=json&shortenfields=true>

**both_to** est particulier : la reconstruction des données de trajectoire s'appuie sur la lecture des observations de départ (G5) et/ou d'arrivée (Marseille). Il se peut qu'un bateau observé dans le G5 au départ de bateau soit vu à l'arrivée de Marseille. Dans ce cas, il peut porter des informations ressemblantes mais légèrement différentes quant à son tonnage, son capitaine, l'orthographe de son nom, etc.
Dans la requête sur travels, par défaut, nous proposons les informations de description du bateau telles que données au départ pour éviter les duplicats d'information. Mais si souhaité, avec l'attribut *both_to*, l'utilisateur peut récupérer les données descriptives aussi au point d'arrivée, et il peut filtrer l'information sur l'attribut **source_entry** qui vaut : *from, to, both-from, both-to*
Voir la documentation de l'API pour plus de détails. 
Exemple : 
<http://data.portic.fr/api/travels/?format=json&params=id,departure,destination&both_to=true>

123
124
**date** : pour filtrer les données sur une année donnée. L'année de la date d'arrivée ou de la date de départ doit commencer par ces 4 digits : 1787 ou  1789 par exemple. 

125
**zipped** : pas encore implémenté
126

127
### 1.2.2. /fieldnames?
128
--- TOUT en json ou csv
129
130
131
132
133

- API = pointcalls | travels | **any**



134
### 1.2.3. /pointcalls?
135
-- TOUT en json ou csv
136

137
138
- http://data.portic.fr/api/pointcalls/?format=csv
- http://data.portic.fr/api/pointcalls/?format=json
139

140
141
Par défaut, pas de filtre sur les dates

142
### 1.2.4. /travels?
143
-- TOUT sans duplicats par défaut en json ou csv
144

145
Par défaut, pas de filtre sur les dates
146

147
#### 1.2.4.1. /details/departures?lon=lat=radius=
148

149
150
151
152
153
154
155
Return the travels, at the departure of the points located in a 100 km radius neighbourhood from the lat/lon given in parameter
    Will be extracted from postgres, schema navigoviz, table built_travels (see navigocorpus/ETL), 
    but with a filter by default : only source_entry = from and both-from, to avoid duplicates

    http://localhost:80/api/details/departures?lat=46&lon=-1&radius=100
    http://localhost/api/details/departures/?lat=45.2333&lon=-1.5&radius=100
    http://localhost/api/details/departures/?lat=45.2333&lon=toto&radius=100
156

157
Par défaut, pas de filtre sur les dates
158

159
#### 1.2.4.2. /agg/departures?lon=lat=radius=
160
161
162
163
164
165

Return the count of departures, for the points located in a radius km neighbourhood from the lat/lon given in parameter
    Will be extracted from postgres, schema navigoviz, table built_travels (see navigocorpus/ETL), 
    but with a filter by default : only source_entry = from and both-from, to avoid duplicates

Les travels seulement au départ dans un rayon de radium km autour du point long/lat
166
167
Les calculs spatiaux sont déportés dans le SGBD Postgres pour bénéficier des index spatiaux.

168
Exemple
169
`http://data.portic.fr/api/agg/departures/?lat=46&lon=-1&radius=20`
170
171

```JS
172
[{"departure":"Fouras","count":2},{"departure":"Martroux","count":6},{"departure":"Port des Barques","count":1},{"departure":"Rochefort","count":562},{"departure":"Soubise","count":44}]
173
174
```

175
Par défaut, pas de filtre sur les dates
176
177


178
#### 1.2.4.3. /agg/destinations?lon=lat=radius=
179
180
181
182
183
184
185
186
187
188
189
190


Return the count of destination for each different admiralties, for the points located in a radius km  neighbourhood from the lat/lon given in parameter
    Will be extracted from postgres, schema navigoviz, table built_travels (see navigocorpus/ETL), 
    but with a filter by default : only source_entry = from and both-from, to avoid duplicates

    `http://data.portic.fr/api/agg/destinations/?lat=45.2333&lon=-1&radius=50`

Les calculs spatiaux sont déportés dans le SGBD Postgres pour bénéficier des index spatiaux.
```JS
[{"label":"Bayonne","value":1,"id":"Bayonne"},{"label":"Bordeaux","value":27,"id":"Bordeaux"},{"label":"Brest","value":43,"id":"Brest"},{"label":"Cherbourg","value":10,"id":"Cherbourg"},{"label":"Dunkerque","value":1,"id":"Dunkerque"},{"label":"Granville","value":1,"id":"Granville"},{"label":"Isigny","value":1,"id":"Isigny"},{"label":"La Hougue","value":1,"id":"La Hougue"},{"label":"La Rochelle","value":3,"id":"La Rochelle"},{"label":"Marennes","value":4,"id":"Marennes"},{"label":"Morlaix","value":29,"id":"Morlaix"},{"label":"Quimper","value":8,"id":"Quimper"},{"label":"Rouen","value":2,"id":"Rouen"},{"label":"Saint-Brieuc","value":1,"id":"Saint-Brieuc"},{"label":"Saint-Malo","value":12,"id":"Saint-Malo"},{"label":"Vannes","value":11,"id":"Vannes"},{"label":null,"value":1,"id":null}]
```
191
Par défaut, pas de filtre sur les dates
192

193
### 1.2.5. /flows?
194

195
196
197
198
199
200
201
202
203
204
205
206
207
Return the flows as specified in API :  a list of travels linked to the specified ports, either by entering in 
    (direction In), either by existing from (direction Out), either by having sailing around (direction In-out), 
    or for any direction (default, or specify direction No). 
        - ports : ports identifiers (UHGS_id) for which travels are filtered, comma separated(,) 
        - direction : In | Out | In-out | **No**
        - degree : **0**, 1 or more 
        (when 0 : all flows going through out the list of cited ports, with also the list of previous and next pointcalls)
 
    Will be extracted from postgres, schema navigoviz, table built_travels (see navigocorpus/ETL), 
    but with a filter by default : only source_entry = from and both-from, to avoid duplicates
        - params : **all** | tableau des noms longs des attributs de l'API à renvoyer
        params=pointcall,pointcall_uhgs_id for instance
        - both_to : true | **false**
208
209
210
        - date : **1787** | YYYY

Par défaut, filtrage sur la date à 1787.
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236

  Examples : 
    - http://data.portic.fr:80/api/flows/?format=csv&both_to=false : VERY LONG, AVOID. Use travels instead
    - http://data.portic.fr:80/api/flows/?format=csv&both_to=true&shortenfields=true&ports=A0180923

    Incomings into Boulogne sur Mer (A0152606) and Bordeaux (A0180923)
    - http://data.portic.fr:80/api/flows/?format=json&ports=A0180923,A0152606&direction=In&params=travel_rank,ship_id,departure,destination,departure_action,destination_action,distance_dep_dest,travel_uncertainity
    
    Exits Boulogne sur Mer (A0152606) and Bordeaux (A0180923)
    - http://data.portic.fr:80/api/flows/?format=json&ports=A0180923,A0152606&direction=Out&params=travel_rank,ship_id,departure,destination,departure_action,destination_action,distance_dep_dest,travel_uncertainity

    Sailing around Bordeaux (A0180923)
    - http://data.portic.fr/api/flows/?format=json&ports=A0180923&direction=In-out&params=id,departure,destination&shortenfields=true

    ```JSON
    [{"t01":"0008663N- 05","t04":"Bordeaux","t19":"Bordeaux"},{"t01":"0009557N- 01","t04":"Bordeaux","t19":"Bordeaux"},{"t01":"0010656N- 01","t04":"Bordeaux","t19":"Bordeaux"}]
    ```

    All passing by Bordeaux (A0180923) and Boulogne sur Mer (A0152606)
    - http://data.portic.fr:80/api/flows/?format=json&ports=A0180923,A0152606&direction=No&params=travel_rank,ship_id,departure,destination,departure_action,destination_action,distance_dep_dest,travel_uncertainity
    
    All incomings into Boulogne sur Mer (A0152606) without previous steps
    - http://data.portic.fr:80/api/flows/?format=json&ports=A0152606&degree=0&direction=In&params=travel_rank,ship_id,departure,destination,departure_action,destination_action,distance_dep_dest,travel_uncertainity

    All outgoings from Bordeaux (A0180923) and Boulogne sur Mer (A0152606) with the next step
    - http://data.portic.fr:80/api/flows/?format=json&ports=A0180923,A0152606&degree=1&direction=Out&params=travel_rank,ship_id,departure,destination,departure_action,destination_action,distance_dep_dest,travel_uncertainity
237

238
239
    All ships having sailing around Bordeaux (A0180923) with the two next steps
    - http://data.portic.fr:80/api/flows/?format=json&ports=A0180923&degree=2&direction=In-out&params=travel_rank,ship_id,departure,destination,departure_action,destination_action,distance_dep_dest,travel_uncertainity
240

241

242
243
244
245
246
247
248
249
  paramètres  :
  - ports : identifiants des ports (UHGS_id) dans la base de données sur lesquels on filtre les données, séparés par des virgules (,) 
  - direction : In | Out | In-out | **No**
  - degree : **0**, 1 ou plus (si 0 : tous les flux passant par le port précisé, avec la liste des escales précédentes et suivantes)
    
  Tous les flux passant par ces ports, 
  - au degré spécifié (0 : toutes les escales sur les trajets passant par ces ports, 1 seulement les ports précédents et/ou suivants sur les trajets, 2 : jusqu'à 2 escales avant ou après les ports, etc.), 
  - et dans la direction spécifiée (In : les arrivées et les escales précédentes, Out : les départs et les escales suivantes, In-out : uniquement les trajectoires ayant navigué en aller-retour autour des mêmes ports, No : toutes directions confondues)
250

251

252
### 1.2.6. /ports?
253

254
255
256
257
258
259
260
Export list of ports_points (in 900013 projection or what is specified by user) in json format, 
    with all required attributes for visualisations (selection of parameters is not possible for the moment)
    List of attributes : 
    ogc_fid, uhgs_id, total, toponym, belonging_states, status, geonameid, admiralty, province, shiparea , point
    User can get a description of the attributes by using /api/fieldnames?api=ports
    Default srid is 900913
    You get another by specifying a srid param
261

262
263
264
265
266
    Will be extracted from postgres, schema ports, table port_points (see navigocorpus/ETL)
    Tested alone in a browser:  
    - http://data.portic.fr/api/ports?srid=4326 
    - http://data.portic.fr/api/ports?
    and by using explorex.portic.fr application (code alphaportic for visualisation) as client : it works
267