See also the RESTful API

Important changes from version 1.2.x

There are some important changes from the previous version 1.2.x. These changes redesigns the API in order to achieve the following goals:

• to have one or more result set as response of a DAB discover and GINode expand/expandNext methods instead of having one or more paginator
• update the result set in order provide the tools necessary to retrieve and refine its content

In particular there are the following major changes:

• DAB discover method: onResponse.result (array of Paginator) is deprecated and replaced by onResponse.response, an array of ResultSet
• GINode expand method: onResponse.page is deprecated and replaced by onResponse.resultSet, a ResultSet object having the response page in the page property
• Paginator resultSet method is deprecated since now the paginator can be retrieved in the paginator property of the ResultSet
• ResultSet provides all the following properties:
  • Content retrieval
    • paginator: provided only as response of a DAB discover method
    • page: provided only as response of GINode expand/expandNext method
  • Content refinement
    • termFrequency: see here for availability info
    • refiner: see here for availability info

Users of the previous versions of the API, are invited to update the code of their applications considering in particular the deprecated methods and properties depicted above.

The UI package

The UI package contains a complete set of widget and components which allow to easily create Graphical User interfaces; see here for a complete usage example.

New widgets and components as well as new functionalities for the existing ones are supplied continuously; often check these docs to be always updated!

Getting started

The DAB is modeled in this API by the DAB object which is the API entry point. DAB resources are modeled by nodes whose characteristics are described by a report. Nodes can be expanded to retrieve their content, or discovered to retrieve all the DAB nodes matching the given optional constraints. The following code snippet shows a basic discover example

                            // creates a new DAB instance with the given endpoint
                            var dab = GIAPI.DAB('https://api.geodab.eu/dab');
                        
                            // defines discover response callback function
                            var onResponse = function(response){
                            	
                            	// retrieves the result set
                            	// only one result set is expected (discover not expanded)     
                                var resultSet = response[0];
                            	
                            	if(resultSet.error){
                            	     document.writeln("Error occurred: "+resultSet.error); 
                                     return;
                                }
                                
                                // retrieves the paginator   
                                var paginator = resultSet.paginator;
                                                
                                // prints the result set
                                document.writeln("<h3>- Result set -</h3>");
                                document.writeln("start:"+resultSet.start+"<br>"); 
                                document.writeln("size:"+resultSet.size+"<br>"); 
                                document.writeln("pageCount:"+resultSet.pageCount+"<br>"); 
                                document.writeln("pageIndex:"+resultSet.pageIndex+"<br>"); 
                                document.writeln("pageSize:"+resultSet.pageSize+"<br>"); 
                         
                                // the current paginator page (the first of the result set)    
                                var page = paginator.page();
                                
                                // printing page nodes
                                document.writeln("<h3>- Nodes of first result set page-</h3>"); 
                                document.writeln("<pre>"); 
                        
                                while(page.hasNext()){
                        
                                    // retrieving the next page node
                                    var node = page.next();
                                
                                    // retrieving the node report
                                    var report = node.report();     
                                                   
                                    document.writeln(JSON.stringify(report,null,4));
                                }
                                document.writeln("</pre>");
                                document.close();
                            };
                        
                            // discover constraints
                            var constraints = {
                                
                                "where": {
                                    "south": 40,
                                    "west": -3,
                                    "north": 46,
                                    "east": 26
                                 },
                                 
                                 "when": {
                                     "from": "2000-01-01",
                                     "to": "2013-01-01"
                                 },
                                 
                                 "what": "temperature"               
                            };
                            
                            // set page size
                            var options = {
                                
                                "pageSize": 5           
                            };
                                        
                            // start discover
                            dab.discover(onResponse, constraints, options);
                            

Brokered sources are modeled by DABSource objects, a specialized type of node with the ability to be included or excluded from the discover.

Semantics-enrichment is modeled with the discover extension option which allows to retrieve more than one result set, one for each concept derived from the extension.

Access of resources is done by means of the GINode accessOptions and GINode accessLink methods.

API Usage Examples

Complete demo of all the DAB discover functionalities	VIEW
Demo portal build with widget and components of the UI package	VIEW
Basic usage example of the DAB discover functionality	VIEW
Basic usage example of the TermFrequency object	VIEW
Usage example of the GINode overview functionality	VIEW
Usage example of the GINodeTree UI control	VIEW
Usage example of the ConceptTree UI control	VIEW

Other usage examples will come soon!

API Dependencies

All the JavaScript libraries used by this API are included in the full minified file.

However if you use this API with other APIs, it is possible that one or more libraries included in the full minified file generate conflicts with other libraries. In that case download the light minified file and try to solve the conflicts by adding the required libraries separately.

Currently the API requires the the following libraries (included in the full minified file):

• jQuery (version currently used 1.11.3)
• jQuery UI (version currently used 1.11.14)
• jTable (version currently used 2.4.0)
• YUI 2 (version currently used 2.9.0)
• OpenLayers 3 (version currently used 3.15.1)
• Layer Switcher for OpenLayers 3

The following CSS is required with the API UI module components GINodeTree and ConceptTree:

• treeview.css

The following CSS is required with the API UI module component TermFrequencyWidget:

• highlight.css
• jtable_jqueryui.css

The following OpenLayers 3 CSS are required:

• ol3-v3.15.1.css
• ol3-layerswitcher.css

If you want to apply the JQuery UI theme to the jTable of the TermFrequencyWidget, add the following script:

                            <script type="text/javascript">
                                $.extend(true, $.hik.jtable.prototype.options, {
                                    jqueryuiTheme: true
                                });
                            </script>
                            

Support

• Subscribe to the DAB API mailing list to receive updates and provide us with your feeback: gi-api@lists.essi-lab.eu.

• To subscribe to the DAB API Mailing List go to the subscription page