usermanual.md 21.4 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
# Principes

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/**

Une requête particulière : *fieldnames* récupère des métadonnées sur l'API, avec la liste des attributs, avec leurs noms court et long, leurs types et leurs significations. On passe en paramètre le nom de l'api (optionnel) dont on veut connaître les attributs :  

- sans préciser l'api : on récupère les attributs des api 'pointcalls' et 'travels';
- api existantes : **pointcalls**, **ports**, **rawflows**, **travels**.

Trois grands types de requêtes :

- **pointcalls** : les données d'observation à chaque escale des navires
- **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
- **travels** : les données de trajectoire calculées

Liste des paramètres communs à chaque requête et valeurs 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**
- date : YYYY | **1787**
- zipped : true | **false**


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

**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>


**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>

**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.  

Exemple :  
<http://data.portic.fr/api/pointcalls/?format=json&date=1789>

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


# Requêtes possibles

## /fieldnames?

Métadonnées sur l'API souhaitée : liste des attributs, avec leurs noms court et long, leurs types et leurs significations.

Paramètres :

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


## /pointcalls?

Returns all the pointcalls as specified in API : "les données d'observation à chaque escale des navires".

Will be extracted from postgres, schema navigoviz, table pointcall (see navigocorpus/ETL)

Parameters :

- params : **all** | tableau des noms longs des attributs de l'API à renvoyer
- date : 4 digits representing a year, to extract data for this given year only. Defaults to no filtering on date.

Examples :

    http://data.portic.fr/api/pointcalls/?params=pointcall,pointcall_uhgs_id&shortenfields=true
    http://data.portic.fr/api/pointcalls/?format=csv
    http://data.portic.fr/api/pointcalls/?format=json
    http://data.portic.fr/api/pointcalls/?params=pointcall,pointcall_uhgs_id&date=1787&format=csv
    http://data.portic.fr/api/pointcalls/?params=pointcall,pointcall_uhgs_id&shortenfields=false
    http://data.portic.fr/api/pointcalls/?format=json&params=id,pointcall,ship_name,destination,destination_uhgs_id&shortenfields=true


## /travels?

Return the travels as specified in API : "les données de trajectoire calculées".

Will be extracted from postgres, schema navigoviz, table built_travels (see navigocorpus/ETL), 
but with a filter by default, to avoid duplicates :

`source_entry = from and both-from`

- params : **all** | tableau des noms longs des attributs de l'API à renvoyer  

    Exemple :

    `params=pointcall,pointcall_uhgs_id`

- both_to : true | **false** 
 
    Exemples :  

        http://127.0.0.1:5004/api/travels/?format=csv&both_to=false
        http://127.0.0.1:80/api/travels/?format=csv&both_to=true&shortenfields=true&date=1789
        http://127.0.0.1:80/api/travels/?format=json&params=id,departure,destination,destination_uhgs_id
        http://127.0.0.1:80/api/travels/?format=json&params=id,departure,destination,destination_uhgs_id&shortenfields=true

- date : par défaut, pas de filtre sur les dates


## /rawflows?

Returns the raw flows as specified in API (same as travel for the attributes).

Raw_flows is built by making an auto-join on pointcall for source_doc_id, 
and departure are "Out" action, destination are "In" action, ordered chronologically.  
Thus we do not take care of net_route_marker (A or Z), neither of ship_id to built travels.  
Data about the cargo, the captain, the homeport are those filled at the departure (there is no doublons).
        
Will be extracted from postgres, schema navigoviz, table raw_flows (see navigocorpus/ETL).

Parameters :

- params : **all** | tableau des noms longs des attributs de l'API à renvoyer  

    Exemple : 

    `params=pointcall,pointcall_uhgs_id`

Exemples :

    http://127.0.0.1:5004/api/rawflows/?format=csv
    http://127.0.0.1:80/api/rawflows/?format=csv&shortenfields=true&date=1789        
    http://127.0.0.1:80/api/rawflows/?format=json&params=id,departure,destination,destination_uhgs_id
    http://127.0.0.1:80/api/rawflows/?format=json&params=id,departure,destination,destination_uhgs_id&shortenfields=true


## /details/departures?

parameters :

- lon
- lat
- radius

Returns 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 to avoid duplicates :

`source_entry = from and both-from`

Examples :

    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

Par défaut, pas de filtre sur les dates

## /agg/departures?

parameters :

- lon
- lat
- radius

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

Exemple :

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

Renvoie :

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

Par défaut, pas de filtre sur les dates


## /agg/destinations?

parameters :

- lon
- lat
- radius

Returns 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}
]
```
Par défaut, pas de filtre sur les dates


## /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.

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)
- date : par défaut, filtrage sur la date à 1787.
    
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


Return the flows as specified in API : a list of travels linked to the specified ports, either by :

- entering in (direction In),
- exiting from (direction Out), 
- having sailing around (direction In-out),
- or for any direction (default, or specify direction No).

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.

Parameters:

- 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)
- date : **1787** | yyyy (4 digits) (by default, only data of 1787 year are extracted)
- params : **all** | tableau des noms longs des attributs de l'API à renvoyer  
  Exemple :  
  `params=pointcall,pointcall_uhgs_id`
- both_to : true | **false**
- date : **1787** | YYYY  

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

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


## /ports?

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,
- belonging_substates,
- 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

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](http://explorex.portic.fr) application (code alphaportic for visualisation) as client : it works


## /sources?

Get statistics about the amount of pointcall data found in sources (couverture des sources de navigo), related to ports of France only. Only observed ("O") pointcalls are taken in account.

Port data is grouped by : source, port, and year. 

This means that for a given source (source_suite = G5 | ...), the API lists the ports (identified by a : toponym, ogc_fid or uhgs_id), and for each port, there is a data line for each year (pointcall_year = 1787 | 1789 | ...). So there may be more than one record for each port ! You can filter or sum yourself port data received, by source, and / or by year, to build your own map for instance.

Data lines returned are :

- if **pointcall data is present** in the database for a port : **nb_conges_inputdone** is given, and all fields available (listed below) are relevant
- if **pointcall data is known** (from archives), but not present in the database for a port : nb_conges_inputdone is null, but **nb_conges_cr** is given. source_suite is 'G5', point_call_year is relevant but all 'computed fields' are null (because there's no data to compute)
- if **all pointcall data is missing** for a port, **only port data** (like toponym and geographical coordinates) is given. source_suite and pointcall_year are set to null

Fields available :

- source_suite : the source where the data comes from (G5 | Santé Marseille | Registre du petit cabotage (1786-1787) | Expéditions "coloniales" Marseille (1789) )
- pointcall_year : the year ( 1787 | 1789 ) for which data is computed. A data line is returned for each year (if data is available)

Fields counting *congés* data from sources :

  - nb_conges_inputdone : total number of observed ("O") pointcalls (congés) actually recorded in database for this port in this source, outgoing ships, computed for a given year
  - nb_conges_cr : number of congés that are known to exist, according to national records (archives), and that are expected. For a given year  
  - nb_conges_sante : number of congés recorded in database, from register of the office of health of Marseille ("Santé Marseille"), incoming ships only. For a given year
  - nb_petitcabotage : number of congés recorded in database, from register "Registre du petit cabotage (1786-1787)" of Marseille (mainly ships coming from Mediterranean areas), incoming ships only. For a given year

Other computed fields :

- nb_tonnage_filled : number of pointcalls where tonnage data (volume de marchandise en tonneaux ou quintaux) is given
- nb_homeport_filled : number of pointcalls where homeport (port d'attache du navire) is known
- nb_product_filled : number of pointcalls where commodity_purpose (nature de la marchandise transportée, ou objet du voyage) is given
- nb_birthplace_filled : number of pointcalls where birthplace (lieu d'origine du capitaine du bateau) is known
- nb_citizenship_filled : number of pointcalls where citizenship (nationalité du capitaine du bateau) is known
- nb_flag_filled : number of pointcalls where flag (pavillon du bateau) is known
- good_sum_tonnage : sum of the tonnage that goes by this port (converted to barrel unit if given in quintals)

A join is made between pointcall and port data, to get nearly the same information about a port as with the ports api (see /api/fieldnames?api=ports) :

- ogc_fid : id
- uhgs_id : geo_general text id of the port
- toponym : standardised name of the port, in the 'lang' language
- substate : belonging substate of the port in 1787 / 1789. In the 'lang' language
- status : null | "oblique" | "siège amirauté", type of port
- has_a_clerk : true / false. Présence d'un greffier de l'amirauté locale dans le port
- geonameid : nearest geoname identifier for the port
- admiralty : name of the home admiralty (amirauté) for the port, in 1787
- province : name of the home province for the port, in 1787
- shiparea : name of the maritime area for the port in 2020
- point : coordinates for representation on a map
    
Will be extracted from postgres, schema navigoviz, table pointcall (see navigocorpus/ETL), completed with schema ports, table port_points.

Parameters :

- srid : **900913** | 4326 | 3857, for geometry transformation of the coordinates of the point representing the port on a map
- date : **none** | 4 digits representing a year (1787 | 1789), to extract pointcall data from the source, for this given pointcall_year only. Otherwise, when no date is given, the API returns one line per year of data (sums are done per year). Make sure to specify an 'order' if you wish to compute sums per port over the years.
- lang : **fr** | en, language for toponym(_standard), substate_1789
- params : **all** | coma-separated list of fields to be returned by the API
- order : **none** | coma-separated list of fields in desired order. Data lines will be sent in ascending order of first field values, and if equals then in order of second field listed, ...  
Example : 
`order=toponym,pointcall_year`

Examples :
```
http://localhost/api/sources/?srid=4326
http://localhost/api/sources/?srid=4326&date=1789
http://localhost/api/sources/?srid=4326&date=1789&lang=en
http://localhost/api/sources/?srid=4326&params=uhgs_id,toponym,pointcall_year,nb_conges_inputdone,nb_conges_cr,point
http://localhost/api/sources/?srid=4326&params=uhgs_id,toponym,pointcall_year,nb_conges_inputdone,nb_conges_cr,point&order=toponym,pointcall_year,source_suite
504
http://localhost/api/sources/?srid=4326&params=uhgs_id,toponym,pointcall_year,source_suite,nb_conges_inputdone,nb_conges_cr,point&order=toponym,pointcall_year,source_suite&format=csv
505
506
```