Commit 3a60e6df authored by Christine Plumejeaud's avatar Christine Plumejeaud
Browse files

Add some description in README

parent 7dc94556
......@@ -10,9 +10,10 @@
- [1.2.3. /pointcalls?](#123-pointcalls)
- [1.2.4. /travels?](#124-travels)
- [1.2.4.1. /details/departures?lon=lat=radius=](#1241-detailsdepartureslonlatradius)
- [1.2.4.1. /agg/departures?lon=lat=radius=](#1241-aggdepartureslonlatradius)
- [1.2.5. /agg/destinations?lon=lat=radius=](#125-aggdestinationslonlatradius)
- [1.2.4.2. /travels?link_to_port="UHGS_id du port"&both-to=true](#1242-travelslinktoport%22uhgsid-du-port%22both-totrue)
- [1.2.4.3. /travels?link_to_port="UHGS_id du port"&degree=0&both-to=true](#1243-travelslinktoport%22uhgsid-du-port%22degree0both-totrue)
- [1.2.5. /agg/destinations?lon=lat=radius=](#125-aggdestinationslonlatradius)
......@@ -65,12 +66,15 @@ C:\Python37\lib\site-packages\flask\app.py:2446: DtypeWarning: Columns (31) have
### 1.2.1. 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 leur nom court et long, leur type et leur signification.
fieldnames : liste des attributs, avec leur nom court et leur nom long
Deux types de requête :
travels : les données de trajectoire calculées
pointcalls : les données d'observation à chaque escale des navires
Deux grands types de requête :
- **travels** : les données de trajectoire calculées
- **pointcalls** : les données d'observation à chaque escale des navires
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
......@@ -82,9 +86,39 @@ Liste des paramètres communs à chaque requête et valeur par défaut en gras:
Si le parametre n'est pas précisé, le serveur opte pour la valeur de paramètre par défaut (en gras).
URL : **http://data.portic.fr/api/**
**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>
**zipped** : pas encore implémenté
### 1.2.2. /fieldnames?
--- TOUT en json ou csv
......@@ -98,30 +132,58 @@ URL : **http://data.portic.fr/api/**
### 1.2.4. /travels?
-- TOUT sans duplicats en json ou csv
-- TOUT sans duplicats par défaut en json ou csv
#### 1.2.4.1. /details/departures?lon=lat=radius=
Les travels seulement au départ dans un rayon de radium km autour du point long/lat
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
#### 1.2.4.1. /agg/departures?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://127.0.0.1:5004/api/agg/departures/?lat=46&lon=-1&radius=100`
`http://data.portic.fr/api/agg/departures/?lat=46&lon=-1&radius=20`
```JS
[{"departure":"La Rochelle","count":2631},{"departure":"Marennes","count":1996},{"departure":"Rochefort","count":894},{"departure":"Aligre de Marans","count":705},{"departure":"Saint Martin de R\u00e9","count":673},{"departure":"Ol\u00e9ron","count":600},{"departure":"Rib\u00e9rou Saujon","count":595},{"departure":"Ars en R\u00e9","count":460},{"departure":"La Tremblade","count":320},{"departure":"La Flotte en R\u00e9","count":289},{"departure":"Moricq","count":230},{"departure":"Aligre","count":155},{"departure":"Le Chateau d' Ol\u00e9ron","count":131},{"departure":"La Perrotine","count":121},{"departure":"Oleron","count":115},{"departure":"Saint Denis d' Ol\u00e9ron","count":102},{"departure":"Saint Savinien","count":100},{"departure":"Chaillevette","count":92},{"departure":"Marans","count":82},{"departure":"Olleron","count":79},{"departure":"Saint Michel en l' Herm","count":77},{"departure":"Ile de R\u00e9","count":76},{"departure":"Soubise","count":66},{"departure":"Esnandes","count":62},{"departure":"La Tranche sur Mer","count":56},{"departure":"Seudre","count":54},{"departure":"\u00eele de R\u00e9","count":38},{"departure":"Royan","count":31},{"departure":"Talmont Talmont Saint Hilaire","count":31},{"departure":"\u00cele d' Ol\u00e9ron","count":26},{"departure":"Ile d' Ol\u00e9ron","count":26},{"departure":"Port d' Envaux","count":22},{"departure":"Brouage","count":22},{"departure":"\u00cele de R\u00e9","count":20},{"departure":"Mortagne","count":17},{"departure":"Le Plomb","count":16},{"departure":"Saint Martin de Rh\u00e9","count":12},{"departure":"Loix en R\u00e9","count":12},{"departure":"L' Houm\u00e9e","count":12},{"departure":"la Rochelle","count":11},{"departure":"Taillebourg","count":10},{"departure":"dans le Pertuis","count":10},{"departure":"Dercie","count":8},{"departure":"Seudres","count":8},{"departure":"Saintes","count":8},{"departure":"Martroux","count":8},{"departure":"Bourcefranc","count":6},{"departure":"La Tranche sur mer","count":6},{"departure":"Lu\u00e7on","count":6},{"departure":"La Pr\u00e9e","count":6},{"departure":"Champagn\u00e9 sur Marais","count":5},{"departure":"Fouras","count":4},{"departure":"d' Aligre","count":4},{"departure":"Saint Martin","count":4},{"departure":"La tremblade","count":4},{"departure":"La Perotine","count":4},{"departure":"La Flotte","count":4},{"departure":"Martrou","count":4},{"departure":"la Tremblade","count":4},{"departure":"Marenne","count":4},{"departure":"Courreaux d' Ol\u00e9ron","count":4},{"departure":"Ars En R\u00e9","count":3},{"departure":"la Perrotine","count":3},{"departure":"Ars","count":3},{"departure":"Auvaux Port d' Envaux","count":2},{"departure":"\u00cele d' Oleron","count":2},{"departure":"Saint Michel en Poitou Saint Michel en l' Herm","count":2},{"departure":"Courraux d' Ol\u00e9ron","count":2},{"departure":"R\u00e9","count":2},{"departure":"La Seudre","count":2},{"departure":"Saint Trojan en Ol\u00e9ron","count":2},{"departure":"Rib\u00e9rou","count":2},{"departure":"La B\u00e9chel La B\u00e9chade","count":2},{"departure":"La Tranche","count":2},{"departure":"Aiguillon","count":2},{"departure":"dans Le Pertuis","count":2},{"departure":"Oll\u00e9ron","count":2},{"departure":"Rade de La Pallice","count":2},{"departure":"Coureaux de R\u00e9","count":2},{"departure":"Daligre","count":2},{"departure":"Saint Martin en R\u00e9","count":2},{"departure":"Ile de Re","count":2},{"departure":"L' Aiguillon","count":2},{"departure":"Saint Denis \u00cele d' Ol\u00e9ron","count":2},{"departure":"Sudre","count":2},{"departure":"Le Pr\u00e9e","count":2},{"departure":"Amiraut\u00e9 de Marennes Ch\u00e2teau d' Ol\u00e9ron","count":2},{"departure":"Port d' Envaux","count":2},{"departure":"Charrou","count":2},{"departure":"Esnandres","count":2},{"departure":"Mornac","count":2},{"departure":"Saint Michel de Herm","count":2},{"departure":"Poitou Rib\u00e9rou Saujon","count":2},{"departure":"LA Rochelle","count":2},{"departure":"Riberoux de Saujon","count":2},{"departure":"R\u00e9 Ile de","count":2},{"departure":"Loix","count":2},{"departure":"Ile d' Oleron","count":2},{"departure":"la Flotte-en-R\u00e9","count":2},{"departure":"Port des Barques","count":2},{"departure":"Ars en r\u00e9","count":2},{"departure":"Riberon Riberou","count":2},{"departure":"Saint Morice Moricq","count":1},{"departure":"Mescher","count":1}]
[{"departure":"Fouras","count":2},{"departure":"Martroux","count":6},{"departure":"Port des Barques","count":1},{"departure":"Rochefort","count":562},{"departure":"Soubise","count":44}]
```
### 1.2.5. /agg/destinations?lon=lat=radius=
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}]
```
#### 1.2.4.2. /travels?link_to_port="UHGS_id du port"&both-to=true
TODO not done yet
Donnerait les trajets passant par le port en question, et toutes les escales.
sans doublons par défaut
avec doublons si both-to=true
......@@ -141,8 +203,3 @@ avec doublons si both-to=true
- 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é
### 1.2.5. /agg/destinations?lon=lat=radius=
Les calculs spatiaux sont déportés dans le SGBD Postgres pour bénéficier des index spatiaux.
Les travels seulement à l'arrivée dans un rayon de radium km autour du point long/lat
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment