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.

Json stores¶

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:

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

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.

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

Output¶

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

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 for data analytics coupled with other inputs.

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 data from the different service providers, and its API can be used to unify the access of these data across all the devices in a consistent way, independent from the device models and service providers.

For this example, the standard command utility curl is used; it can be replaced with any HTTP client.

The command is like:

curl 'https://gis.auroville.org.in/api/avsm_misc.weather_station/values/temperature?where={"avsm_misc.weather_station":4}&time=false&resample=m'

Where:

• The Auroville Gisaf public server is used
• The store for weather stations is avsm_misc.weather_station
• The id of the weather station is 4. The list of weather stations can be found at https://gis.auroville.org.in/measures/avsm_misc.weather_station
• The value to be fetched is temperature. The list of the available values can be found at https://gis.auroville.org.in/measures/avsm_misc.weather_station/4
• The resample base is 1 month. Other valid resampling interval include: * h or 1h: 1 hour * 15m: 15 minutes * d or 1d: 1 day * 2w: 2 weeks