README.md 9.51 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
15
16
      - [1.2.4.2. /agg/departures?lon=lat=radius=](#1242-aggdepartureslonlatradius)
      - [1.2.4.3. /agg/destinations?lon=lat=radius=](#1243-aggdestinationslonlatradius)
      - [1.2.4.4. /travels?link_to_port="UHGS_id du port"&both-to=true](#1244-travelslinktoport%22uhgsid-du-port%22both-totrue)
      - [1.2.4.5. /travels?link_to_port="UHGS_id du port"&degree=0&both-to=true](#1245-travelslinktoport%22uhgsid-du-port%22degree0both-totrue)
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
76
77
Deux grands types de requête : 
- **travels** : les données de trajectoire calculées
- **pointcalls** : les données d'observation à chaque escale des navires
78
79
80
81
82
83

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**
84
85
- zipped : true | **false**

86
87
88

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

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
**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>
109

110

111
112
113
114
115
116
117
118
119
120
121
**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>

**zipped** : pas encore implémenté
122

123
### 1.2.2. /fieldnames?
124
--- TOUT en json ou csv
125
126
127
128
129

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



130
### 1.2.3. /pointcalls?
131
-- TOUT en json ou csv
132

133

134
### 1.2.4. /travels?
135
-- TOUT sans duplicats par défaut en json ou csv
136

137

138
#### 1.2.4.1. /details/departures?lon=lat=radius=
139

140
141
142
143
144
145
146
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
147

148

149
#### 1.2.4.2. /agg/departures?lon=lat=radius=
150
151
152
153
154
155

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
156
157
Les calculs spatiaux sont déportés dans le SGBD Postgres pour bénéficier des index spatiaux.

158
Exemple
159
`http://data.portic.fr/api/agg/departures/?lat=46&lon=-1&radius=20`
160
161

```JS
162
[{"departure":"Fouras","count":2},{"departure":"Martroux","count":6},{"departure":"Port des Barques","count":1},{"departure":"Rochefort","count":562},{"departure":"Soubise","count":44}]
163
164
165
166
167
```




168
#### 1.2.4.3. /agg/destinations?lon=lat=radius=
169
170
171
172
173
174
175
176
177
178
179
180
181
182


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}]
```


183
#### 1.2.4.4. /travels?link_to_port="UHGS_id du port"&both-to=true
184

185
186
TODO not done yet

187
188
189
190
Donnerait les trajets passant par le port en question, et toutes les escales. 
sans doublons par défaut
avec doublons si both-to=true

191
192
193
- link_to_port : **null** | identifiant du port UHGS_id dans la base de données sur lequel on filtre les données si précisé


194
#### 1.2.4.5. /travels?link_to_port="UHGS_id du port"&degree=0&both-to=true
195

196
197
TODO not done yet

198
199
200
201
202
Donnerait les trajets entrants ou partants du port en question, 
sans doublons, seulement les escales directement précédentes ou suivantes 
sans doublons par défaut
avec doublons si both-to=true

203
204
205
- link_to_port : **null** | identifiant du port UHGS_id dans la base de données sur lequel on filtre les données si précisé