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

In this example, the standard command utility @curl@ is used; the URL used as argument can be used by any HTTP client, including directly in web browsers or with programming language libraries for automation.

The command is like:

<pre>

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

</pre>

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

h5. Output sample (truncated):

[                                                                                                                                              

    {                                                                                                                                          

        "temperature": 31.1,                                                                                                                   

        "time": "2019-06-30T00:00:00.000Z"                                                                                                     

    },                                                                                                                                         

    {                                                                                                                                          

        "temperature": 29.5,                                                                                                                   

        "time": "2019-07-31T00:00:00.000Z"                                                                                                     

    },                                                                                                                                         

    {                                                                                                                                          

        "temperature": 28.9,                                                                                                                   

        "time": "2019-08-31T00:00:00.000Z"

    },

    {

        "temperature": 27.7,

        "time": "2019-09-30T00:00:00.000Z"

    },

    {

        "temperature": 27.0,

        "time": "2019-10-31T00:00:00.000Z"

    },

    {

        "temperature": 26.2,

        "time": "2019-11-30T00:00:00.000Z"

    },

    {

        "temperature": 25.5,

        "time": "2020-11-30T00:00:00.000Z"

    }

]