This is a Lizmap module to generate an API for G-Obs: https://docs.3liz.org/lizmap-gobsapi-module/api/
NB: all the path given are relative to your Lizmap Web Client instance folder.
-
Copy the
gobsapi
directory inside thelizmap/lizmap-modules/
of a working Lizmap Web Client instance to have a newlizmap/lizmap-modules/gobsapi/
folder containing the filesmodule.xml
,events.xml
, and folders. -
Then modify the file
lizmap/var/config/localconfig.ini.php
to addgobsapi.access=2
in the[modules]
section, such as
[modules]
gobsapi.access=2
- You need to manually edit the file
lizmap/projects.xml
and add the following content inside the<entrypoints>
section
<entry file="gobsapi.php" config="gobsapi/config.ini.php" type="classic"/>
Afterwards, you should have a content like this in the entrypoints
section
<entrypoints>
<entry file="index.php" config="index/config.ini.php"/>
<entry file="admin.php" config="admin/config.ini.php" type="classic"/>
<entry file="script.php" config="cmdline/script.ini.php" type="cmdline"/>
<entry file="gobsapi.php" config="gobsapi/config.ini.php" type="classic"/>
</entrypoints>
- Copy the folder
gobsapi/install/gobsapi
inside the Lizmap folderlizmap/var/config/
to have a new folderlizmap/var/config/gobsapi
with a fileconfig.ini.php
inside
cp -R lizmap/lizmap-modules/gobsapi/install/gobsapi lizmap/var/config/gobsapi
- Copy the file
gobsapi/install/gobsapi.php
inside thelizmap/www/
folder
cp -R lizmap/lizmap-modules/gobsapi/install/gobsapi.php lizmap/www/
- Then you need to run the Lizmap installer
lizmap/install/set_rights.sh
lizmap/install/clean_vartmp.sh
php lizmap/install/installer.php
- You need to add a new database profile in the
lizmap/var/config/profiles.ini.php
like the following example (change the required fields)
[jdb:gobsapi]
driver=pgsql
database=gobs
host=localhost
port=5433
user=gobs_user
password=gobs
persistent=off
If your Lizmap Web Client uses SAMLv2 to authenticate the users, you need to force the gobsapi module to use another driver. The SAML protocol is based on URL redirections, which are not suitable for the G-Obs API end point.
You can override the configuration to force the gobsapi.php
entry point to use another driver. To do so, you must first edit the file localconfig.ini.php
and change the [module]
section into:
[modules]
;; uncomment it if you want to use ldap for authentication
;; see documentation to complete the ldap configuration
ldapdao.access=0
lizmap.installparam=
multiauth.access=0
;; we deactivate gobs & saml which must be activated
;; only for the entry points index and admin
;; by editing their configuration files lizmap/var/config/index/config.ini.php
;; and lizmap/var/config/admin/config.ini.php
gobs.access=0
saml.access=0
;; we then activate the gobsapi module
gobsapi.access=2
We have deactivated gobs & saml in the main config (localconfig): they must now be activated only for the entry points index and admin by editing their configuration files lizmap/var/config/index/config.ini.php
and lizmap/var/config/admin/config.ini.php
. Example contents
- for the index entrypoint:
;<?php die(''); ?>
;for security reasons , don't remove or modify the first line
startModule=view
startAction="default:index"
[coordplugins]
jacl2=1
saml="saml/saml.coord.ini.php"
saml.name=auth
[modules]
dataviz.access=2
dynamicLayers.access=2
jelix.access=2
lizmap.access=2
view.access=2
filter.access=2
action.access=2
jacl2db_admin.access=1
jauthdb_admin.access=1
master_admin.access=1
saml.access=2
saml.installparam="localconfig;useradmin=mdouchin;[email protected]"
saml.path="app:my-packages/vendor/jelix/saml-module/saml"
gobs.access=2
[coordplugin_auth]
;; uncomment it if you want to use ldap for authentication
;; see documentation to complete the ldap configuration
driver=saml
- for the admin entrypoint:
;<?php die(''); ?>
;for security reasons , don't remove or modify the first line
startModule=master_admin
startAction="default:index"
[responses]
html=adminHtmlResponse
htmlauth=adminLoginHtmlResponse
[modules]
admin.access=2
jauthdb_admin.access=2
jacl2db_admin.access=2
master_admin.access=2
jcommunity.access=2
saml.access=2
saml.installparam="localconfig;useradmin=mdouchin;[email protected]"
saml.path="app:my-packages/vendor/jelix/saml-module/saml"
gobs.access=2
[coordplugins]
jacl2=1
saml="saml/saml.coord.ini.php"
saml.name=auth
[coordplugin_auth]
;; uncomment it if you want to use ldap for authentication
;; see documentation to complete the ldap configuration
driver=saml
- for the gobsapi entrypoint:
[modules]
jelix.access=1
lizmap.access=1
view.access=1
jacl2db_admin.access=1
jauthdb_admin.access=1
master_admin.access=1
;; on active le module gobsapi
gobsapi.access=2
;; et ldapdao
ldapdao.access=1
jacl2.access=1
jauth.access=1
jauthdb.access=1
[coordplugins]
jacl2=1
auth="gobsapi/auth.coord.ini.php"
[coordplugin_jacl2]
on_error=2
error_message="jacl2~errors.action.right.needed"
on_error_action="jelix~error:badright"
The G-Obs API module is tightly linked to the G-Obs QGIS plugin, and to the use of Lizmap Web Client as the web map publication tool.
We write here some help regarding the specific configuration needed for G-Obs API. A full documentation on Lizmap Web Client is available here: https://docs.lizmap.com/
A project in G-Obs corresponds to a QGIS project published to Lizmap, with some specifities:
-
Indicators: In the QGIS Project properties, you need to have a project variable
gobs_indicators
containing the list of indicators that you want to publish in the project. To do so, open the project properties (CTRL+MAJ+P), go to theVariables
tab, and add a new variable: namegobs_indicators
and value begining exactly with the termgobs_indicators:
, and containing the list of indicator codes separated by comma. For example:gobs_indicators:pluviometry,population
will "publish" these two indicators (pluviometry and population) with the QGIS project. -
Additionnal spatial data: you can also publish a Geopackage file alongside the project, to be used by any software to display referential spatial layers on the map with the observation data. To do so, just create and save a Geopackage file containing vector layers (and raster layers if needed) named as the QGIS project. For example, if you project file is
my_gobs_project.qgs
, you must save the Geopackage file in the same folder with the namemy_gobs_project.qgs.gpkg
. You can create and populate this Geopackage with the QGIS processing toolPackage layers
accessible with the Processing / Toolbox menu.
In the G-Obs database, you can add documents to illustrate each indicator. To do so, the table gobs.document
must be filled with appropriate data.
An indicator can have different types of documents:
document
: any document such as PDF, ODT, DOC, DOCX, ZIP fileicon
: the icon of the indicator (a simple and small image file). Must be a jpeg, jpg, png or gif.image
: an image file (photo, illustration)other
: any other unspecified type of documentpreview
: the image to be shown as the main illustration of the indicator. Must be a jpeg, jpg, png or gif.video
: a video file.url
: an URL pointing to an external ressource
All the document files must be stored in the API server. The document files must stored inside a media/gobsapi/documents/
folder, with the media
folder located in Lizmap repository root folder. This media
folder must be writable. Do it for example with
chown -R :www-data /srv/data/media
chmod 775 -R /srv/data/media
For example, if Lizmap Web Client repository root folder is /srv/data/
, the root gobsapi media folder will be /srv/data/media/
and the documents must be stored in /srv/data/media/gobsapi/documents/INDICATOR_CODE/DOCUMENT_TYPE/DOCUMENT_FILE_NAME.EXT
, where
INDICATOR_CODE
is the code of the indicator, for examplepluviometry
DOCUMENT_TYPE
is the type of the document, for exampleimage
DOCUMENT_FILE_NAME.EXT
is the name of the file, for examplea_picture.jpg
Two examples:
/srv/data/media/gobsapi/documents/pluviometry/image/a_picture.jpg
/srv/data/media/gobsapi/documents/population/document/explaining_demography.pdf
In the table gobs.document
of the G-Obs database , the path must be stored relative to the folder /srv/data/media/gobsapi/documents
, and must begin only with the code of the indicator. For example :
pluviometry/image/a_picture.jpg
population/document/explaining_demography.pdf
The API module will then propose an URL to acccess each document, returned when querying the details of an indicator.
Each observation can have a photo, called media. When uploading this media file with the API entry point /project/PROJECT_CODE/indicator/INDICATOR_CODE/observation/OBSERVATION_UID/uploadMedia
, the media file will be stored in the full path /srv/data/media/gobsapi/observations/OBSERVATION_UID.EXT
where:
INDICATOR_CODE
is the code of the indicator, for examplepluviometry
OBSERVATION_UID
is the UUID of the osbervation, for examplee8f0a46c-1d24-456a-925a-387740ade1c6
EXT
is the extension of the original file sent, for examplejpeg
which can build the example path: /srv/data/media/gobsapi/observations/e8f0a46c-1d24-456a-925a-387740ade1c6.jpeg
Then you are ready to test. For example with curl (you need curl to pass JWT token in Authorization header). Full API Documentation is available: https://docs.3liz.org/lizmap-gobsapi-module/api/
In the following examples, we use http://lizmap.localhost/
as the base URL:
- Define the API base URL:
BASEURL="http://lizmap.localhost/gobsapi.php"
- User:
# USER
###
# login
# we get the authentication TOKEN variable by first log the user in
TOKEN=$(curl -s -X GET -H 'Content-Type: application/json' "$BASEURL/user/login?username=admin&password=admin" | jq -r '.token') && echo $TOKEN
# User Projects
# we use the $TOKEN variable in the Authorization header
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" $BASEURL/user/projects)
# logUserOut
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" $BASEURL/user/logout)
- Project:
# PROJECT
###
# getProjectByKey
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" $BASEURL/project/lizmapdemo~lampadaires)
# getProjectIndicators
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" $BASEURL/project/lizmapdemo~lampadaires/indicators)
# getProjectGeopackage
curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/geopackage --output /tmp/test.gpkg
- Indicator:
# INDICATOR
###
# getIndicatorByCode
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry)
# getObservationsByIndicator
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "lastSyncDate: $(date '+%Y-%m-%d %H:%M:%S' -d '7 days ago')" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observations)
# getDeletedObservationsByIndicator
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "lastSyncDate: $(date '+%Y-%m-%d %H:%M:%S' -d '13 days ago')" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/deletedObservations)
# getIndicatorDocument
curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/document/946fee64-e86c-40fa-a55e-8d9ad3579734 --output /tmp/test.jpeg
- Observation:
# OBSERVATION
###
# createObservation
echo $(curl -X POST -H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" -H "Content-Type: application/json" -d "{\"id\":null,\"indicator\":\"pluviometry\",\"uuid\":null,\"start_timestamp\":\"2019-07-19 03:30:00\",\"end_timestamp\":null,\"coordinates\":{\"x\":-3.785956510771293,\"y\":48.4744332531894},\"wkt\":\"POINT(-3.78595651077129 48.4744332531894)\",\"values\":[0.8],\"photo\":null,\"created_at\":null,\"updated_at\":null}" "$BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation")
{"id":3595,"indicator":"pluviometry","uuid":"e8f0a46c-1d24-456a-925a-387740ade1c6","start_timestamp":"2019-07-19T03:30:00","end_timestamp":null,"coordinates":{"x":-3.78595651077129,"y":48.4744332531894},"wkt":"POINT(-3.78595651077129 48.4744332531894)","values":[0.8],"photo":null,"created_at":"2020-12-24T15:17:43","updated_at":"2020-12-24T15:17:43"}
# updateObservation
echo $(curl -X PUT -H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" -H "Content-Type: application/json" -d "{\"id\":1,\"indicator\":\"pluviometry\",\"uuid\":\"e8f0a46c-1d24-456a-925a-387740ade1c6\",\"start_timestamp\":\"2019-07-16 03:35:00\",\"end_timestamp\":null,\"coordinates\":{\"x\":-3.785956510771293,\"y\":48.4744332531894},\"wkt\":\"POINT(-3.78595651077999 48.4744332531999)\",\"values\":[1.2],\"photo\":null,\"created_at\":\"2020-12-03 15:04:40\",\"updated_at\":\"2020-12-03 17:55:59\"}" "$BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation")
# getObservationById
echo $(curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation/e8f0a46c-1d24-456a-925a-387740ade1c6)
# deleteObservationById
echo $(curl -X DELETE -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation/e8f0a46c-1d24-456a-925a-387740ade1c6)
- Observation media:
# uploadObservationMedia
echo $(curl -X POST -H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" -H "Content-Type: multipart/form-data" -F "mediaFile=@/home/mdouchin/Documents/3liz/mdouchin_carre.jpeg;type=image/jpeg" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation/e8f0a46c-1d24-456a-925a-387740ade1c6/uploadMedia)
# deleteObservationMedia
echo $(curl -X DELETE -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation/e8f0a46c-1d24-456a-925a-387740ade1c6/deleteMedia)
# getObservationMedia
curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "requestSyncDate: $(date '+%Y-%m-%d %H:%M:%S')" $BASEURL/project/lizmapdemo~lampadaires/indicator/pluviometry/observation/e8f0a46c-1d24-456a-925a-387740ade1c6/media --output /tmp/test.jpeg
Mozilla Public License 2: https://www.mozilla.org/en-US/MPL/2.0/