GIS » Gisaf

h1. APIs

Gisaf's web interface uses server's APIs, that can also be used for third party software integration, eg. for retrieving data from the database with HTTP requests.

The APIs use 2 technologies: json REST stores and Graphql.

This page is a work-in-progress documentation effort. Refer to source code for a comprehensive and up to date API list and usage:

* https://redmine.auroville.org.in/projects/gisaf/repository/revisions/master/entry/gisaf/api.py

* https://redmine.auroville.org.in/projects/gisaf/repository/revisions/master/entry/gisaf/graphql_api.py

It's also easy to track the HTTP requests in use by the web site, using standard web development tools like those embedded in all modern browsers.

h2. Json stores

h3. Getting record values from devices

For the custom models that define time-based values, eg. fetched from "IoT" enabled devices such as weather stations or other sensors, the generic HTTP request scheme is:

<pre>

<http_request_prefix>/api/<store>/values/<value>?<parameters>

</pre>

Where:

* http_request_prefix: base URI base of the site (eg. @https://gis.auroville.org.in@)

* store: name of the store of the geographical feature (eg. @avsm_misc.weather_station@)

* value: name of the value for the store (eg. @temperature@)

* parameters: URL-encoded query string, see below for details.

h4. Parameters

The parameters must be formatted with a URI-compliant query syntax. Note that the URI encoding isn't required

Required:

* where: JSON compliant string specifying the id of the feature (eg. @where={"avsm_misc.weather_station":4}@)

Optional:

* resample: plain text resampling time interval for Pandas, see https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#dateoffset-objects for a complete description (eg. @resample=D@ for day, @resample:15min@ for 15 minutes intervals) 

* sort: JSON compliant string specifying the value to sort on, with a boolean for the sort order (true for ascending, false for descending) (eg. @time=true@). If @resample@ is given, the returned series is  

h4. Output

The output is a json string: an array of data points with key-value pairs of the requested values.

h4. Real life example: gather historical weather station data

In the following scenario, a third party needs to get the time series of the temperatures recorded by weather stations.

Different weather stations send data to different cloud based services, using different conventions (field names, units, etc) and eventually access permissions. Luckily, Gisaf collects in near real-time the data from the different service providers, and its API can be used to unify the access of these data across all the providers.