README.md

- [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)
    - [1.2.1. Principes](#121-principes)
    - [1.2.2. /fieldnames?](#122-fieldnames)
    - [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.2. /agg/departures?lon=lat=radius=](#1242-aggdepartureslonlatradius)
      - [1.2.4.3. /agg/destinations?lon=lat=radius=](#1243-aggdestinationslonlatradius)
    - [1.2.5. /flows?](#125-flows)
    - [1.2.6. /ports?](#126-ports)



# 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

```bash

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

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


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

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

Trois grands types de requête : 
- **travels** : les données de trajectoire calculées
- **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

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

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

### 1.2.2. /fieldnames?
--- TOUT en json ou csv

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



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

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

Par défaut, pas de filtre sur les dates

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

Par défaut, pas de filtre sur les dates

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

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

Par défaut, pas de filtre sur les dates

#### 1.2.4.2. /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://data.portic.fr/api/agg/departures/?lat=46&lon=-1&radius=20`

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


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

### 1.2.5. /flows?

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**
        - date : **1787** | YYYY

Par défaut, filtrage sur la date à 1787.

  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


  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)


### 1.2.6. /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, 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 application (code alphaportic for visualisation) as client : it works