Commit 19631ef3 authored by Bernard PRADINES's avatar Bernard PRADINES
Browse files

Site de doc utilisateur a la racine du site

parent f082013c
......@@ -5,4 +5,5 @@ a_installer_pip.txt
gethelp.bat
help.txt
README.pdf
test.py
\ No newline at end of file
test.py
manual/*
\ No newline at end of file
This diff is collapsed.
......@@ -10,8 +10,9 @@ This requires :
@see navigocorpus/ETL/BuildNavigoviz.py
'''
from flask import Flask, jsonify, abort, render_template,url_for,request, make_response
from flask import Flask, jsonify, abort, render_template,url_for,request, make_response, send_from_directory
from flask_cors import CORS, cross_origin
from werkzeug.urls import url_parse
from flask_caching import Cache
import numpy as np
......@@ -41,9 +42,22 @@ port = '80'
postgresport = '5432'
database = 'portic_v6'
# API documentation as statically generated website
@app.route('/')
def serve_static_root():
return send_from_directory('manual', 'index.html')
@app.route('/<path:filename>')
def serve_static_manual(filename):
return send_from_directory('manual', filename)
# URL doesn't exist
@app.errorhandler(404)
def resource_not_found(e):
# Tester l'URL de la requête :
if not url_parse(request.url).path.startswith('/api/'):
# Ce n'est pas une erreur de l'API : renvoyer la page d'erreur standard en HTML
abort(404)
# Sinon c'est une erreur de l'API, renvoyer le message d'erreur en JSON
return jsonify(str(e)), 404
# Request with bad HTTP method (GET, PUT, POST, ...)
......@@ -863,66 +877,73 @@ def keepDfCastsFoundInSelect(dict_cast_colonnes_df, champs_select):
@app.route('/api/sources/')
def getSources():
"""
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 into account.
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.
Port data is a dataframe grouped by : source, port, and year.
This means that for a given source (source_suite = G5 | Santé Marseille | Registre du petit cabotage (1786-1787) | ...),
the API lists the ports (identified by a : toponym, ogc_fid or uhgs_id), and for each port,
there is data for each year (pointcall_year = 1787 | 1789 | ...) except if port is missing in all sources.
So there may be more than one record for each port ! You can filter or sum 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 (G5 | Santé Marseille | Registre du petit cabotage (1786-1787) | Expéditions "coloniales" Marseille (1789) ) where the data comes from
- 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 or null if none
- 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 or null if none
- nb_conges_sante : number of congés recorded in database, from register of the office of health of Marseille, incoming ships only. For a given year or null if none
- nb_petitcabotage : number of congés recorded in database, from register "Petit cabotage" of Marseille (mainly ships coming from Mediterranean areas), incoming ships only. For a given year or null if none
Other computed fields :
- nb_tonnage_filled : number of pointcalls where tonnage data (volume de marchandise en tonneaux ou quintaux) is given or null if none
- nb_homeport_filled : number of pointcalls where homeport (port d'attache du navire) is known or null if none
- nb_product_filled : number of pointcalls where commodity_purpose (nature de la marchandise transportée, ou objet du voyage) is given or null if none
- nb_birthplace_filled : number of pointcalls where birthplace (lieu d'origine du capitaine du bateau) is known or null if none
- nb_citizenship_filled : number of pointcalls where citizenship (nationalité du capitaine du bateau) is known or null if none
- nb_flag_filled : number of pointcalls where flag (pavillon du navire, i.e. nationalité/étendard du navire) is known or null if none
- good_sum_tonnage : sum of the tonnage that goes by this port (converted to barrel unit if given in quintals) or null if none
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) :
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 if there was a clerk (cases of "oblique" ou "siège amirauté")
- 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 : projeted coordinates for representation on a map
- 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 :
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
Example :
`order=toponym,pointcall_year`
Examples :
Examples :
- http://data.portic.fr/api/sources/?srid=4326&date=1789
- http://data.portic.fr/api/sources/?srid=4326&date=1789&format=csv
- 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,source_suite&format=csv
- http://localhost/api/sources/?srid=4326&params=uhgs_id,toponym,pointcall_year,nb_conges_inputdone,nb_conges_cr,point,source_suite&order=toponym,pointcall_year,source_suite&format=csv
- http://localhost/api/sources/?srid=4326&params=uhgs_id,toponym,pointcall_year,nb_conges_inputdone,nb_conges_cr,nb_conges_sante,nb_petitcabotage,source_suite,point&order=toponym,pointcall_year,source_suite&format=csv
- 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
"""
# select the srid given by user for geometry transformation
srid = request.args.get("srid")
......
This diff is collapsed.
# Portic data API : get dynamic data from database
*Web API for data above the postgres database developped with Flask*
API URL : **http://data.portic.fr/api/**
See [user manual](usermanual.md) first for details
![Pointcalls API - Results, and download time](img/temps_telechargement.png)
Licence : [![AGPLv3.png](http://www.gnu.org/graphics/agplv3-with-text-162x68.png)](agpl-3.0.md)
This is a **documentation** site for *porticapi*, a part of the *ANR Portic Project* : [https://anr.portic.fr/](https://anr.portic.fr/)
\ No newline at end of file
This diff is collapsed.
# name of the website, with link, at the left of the navbar :
site_name: Porticapi
site_url: http://data.portic.fr
site_description: Documentation website for the porticapi project
# to get the 'Editer dans GitLab huma-num' link at the right of the navbar, when browsing documentation :
repo_url: https://gitlab.huma-num.fr/portic/porticapi/
repo_name: GitLab huma-num
edit_uri: -/blob/master/docs/
# 'blob' to open a read-only view, which supports anonymous access.
# if you don't want the 'Edit' link, put edit_uri to ''
# choose and configure an installed mkdocs theme :
theme:
# available themes : mkdocs (default), readthedocs
name: mkdocs
# style of the mkdocs theme : primary (default), dark, light
nav_style: dark
# localization of the theme only : en, fr, ...
locale: fr
# maximum depth of the navigation tree in the sidebar. Default: 2
navigation_depth: 2
# extensions to regular markdown syntax : https://daringfireball.net/projects/markdown/
# and the Python-Markdown library syntax : https://python-markdown.github.io/
# available (installed) extensions : https://python-markdown.github.io/extensions/
markdown_extensions:
# Python-Markdown extra : Abbreviations, Attribute Lists, Definition Lists, Fenced Code Blocks, Footnotes, Tables, Markdown in HTML
- extra
# Table of contents : place the [TOC] marker in markdown (useless, only here to configure max headers level. See also navigation_depth)
- toc:
# Base level for headers. Defaults to 1. Suppose the Markdown text for a page should not contain any headers higher than level 1 (<h1>)
baselevel: 1
# path of source markdown files
docs_dir: 'docs'
# output path of built HTML documentation
site_dir: 'manual'
# true for directory 'manual/' links, false for 'manual/index.html' links
use_directory_urls: false
# layout of the navbar (menu) :
# - 'Displayed title': 'markdown_file.md or external link'
nav:
- 'Accueil': 'index.md'
- 'Manuel utilisateur': 'usermanual.md'
- 'Licence': 'agpl-3.0.md'
- 'Code source': 'https://gitlab.huma-num.fr/portic/porticapi'
\ 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