The GEOSS Discovery And Access Broker APIs
Authors: Fabrizio Papeschi, Mattia Santoro, Stefano Nativi
API version: 1.4.3-beta

DAB

Extends GINode
Module: Core

The API entry point. This object provides the ability to create a node connected to an existing DAB server instance. DAB is a composed node and it's the root of the hierarchical structure defined by the DAB brokered sources.
The main DAB operation allows to discover any nodes regardless of their level in the hierarchy.

How to create a DAB instance

In order to minimize the use of global variables DAB object is defined as a member of GIAPI. E.g.:

// remote endpoint
                        var remoteDab = GIAPI.DAB('https://api.geodab.eu/dab/');
                        
                        // local endpoint 
                        var localDab = GIAPI.DAB('./');

See also GIAPI.

Basic and advanced constraints

The discover supports basic and advanced constraints.

  • Basic constraints:

  • Advanced constraints:

The following parameters expressed as key-value pair allow to set advanced constraints.

  • Miscellaneous
    • General purpose constraints.

    • loc: name of a location where to constraint the discover. It can be used instead of the where constraint. E.g: "italy", "u.s.a", "africa"
    • gdc: includes only or excludes all the "GEOSS Data Core" datasets in the/from the discover. Possible values are 'true' or 'false'
    • sources: comma separated list of sources identifiers; only the related sources are included in the discover. This is an alternative way to the DABSource.include method
    • sba: a "GEO Societal Benefit Area". E.g.:"agriculture", "climate", "disasters"
    • hl: the type of node to discover. Possible values are: "dataset" for simple nodes, "series" for composed nodes
    • prot: a protocol used to access the data linked to the discovered nodes. E.g: "HTTP", "urn:ogc:serviceType:WebMapService:1.1.1:HTTP", "OGC:WMS-1.1.1-http-get-map"
    • frmt: a format of the data linked to the discovered nodes. E.g.: "image/gif", "application/zip"
    • kwd: a keyword which describes the nodes to discover
  • Legal constraints
    • These constraints can be used to filter the nodes basing on their legal constraints.

    • uselim: limitation applied on the use of the data linked to the discovered nodes (string)
    • lac: includes only or excludes all the nodes having some legal access constraints. Possible values are 'true' or 'false'
    • luc: includes only or excludes all the nodes having some legal use constraints. Possible values are 'true' or 'false'
  • IRIS Event constraints
    • These constraints affect only the "IRIS Event" source (type = "IRIS_EVENT").

    • minmag: integer value of the minimum magnitude
    • maxmag: integer value of the maximum magnitude
    • magt: the type of magnitude (case insensitive). E.g.: "ML", "Ms", "mb", "Mw", "all", "preferred"
    • mind: limit to events with depths equal to or greater than the specified depth. Double value expressed in kilometers
    • maxd: limit to events with depths less than or equal to the specified depth. Double value expressed in kilometers
    • evtOrd: ordering of the results. Possible values are: "time" and "magnitude"
  • INPE constraints
    • These constraints affect only the "INPE CDSR" source (type = "INPE").

    • inpe-sat-name: satellite name (string). E.g.: "AQUA"
    • inpe-instr-name: instrument name (string). E.g.: "MODIS"
  • Earth Observation constraints
    • Specific Earth Observation constraints.

    • sta: station description (string)
    • sensor: sensor description (string)
    • bandwl: histogram mean (double)
    • proclev: processing level (double)
    • illazan: illumination azimuth angle (double)
    • illzean: illumination zenith angle value (double)
    • cloudcp: cloud cover percentage (double)
    • sarPolCh: polarisation channels (string)
    • sarPolMd: polarisation mode (string)
    • sensorResolution: sensor resolution (double)
    • sensorResolutionMax: maximum sensor resolution (double)
    • sensorResolutionMin: minimum sensor resolution (double)

Constructor

DAB

(
  • endpoint
  • [viewId]
  • [servicePath]
  • [cswPath]
  • [openSearchPath]
)

Parameters:

  • endpoint String

    The endpoint of the DAB instance to connect

  • [viewId] String optional

    a "server-side" view identifier

  • [servicePath] String optional

    default: "services"

  • [cswPath] String optional

    default: "cswiso"

  • [openSearchPath] String optional

    default: "opensearch"

Methods

accessOptions

(
  • onResponse
)
async

Inherited from GINode:

If this {{#crossLink "GINode"}}node{{/crossLink}} is accessible, retrieves one or more objects containing a list of {{#crossLink "AccessOptions"}}validOptions{{/crossLink}}, the {{#crossLink "AccessOptions"}}defaultOption{{/crossLink}} and the {{#crossLink "AccessOptions"}}reducedOption{{/crossLink}} to use as options for the {{#crossLink "GINode/accessLink:method"}}{{/crossLink}} method.
If this {{#crossLink "GINode"}}node{{/crossLink}} is not accessible, this method does nothing.

Each returned object contains a validOptions array, and a defaultOption and a reducedOption. E.g.: 
var options = {
                                                "validOptions": [
                                                	  {
                                            	         "CRS": "EPSG:4326",
                                            	     	 "format": "IMAGE_PNG",
                                            	     	 "firstAxisSize": {
                                            	        	"label": "Lat",
                                            	        	"value": 300
                                            	     	 },
                                            		     "secondAxisSize": {
                                            		        "label": "Lon",
                                            		        "value": 300
                                            		     },
                                            		     "spatialSubset": {
                                            		         "south": -60.0,
                                            		         "west": -180.0,
                                            		         "north": 90.000007823,
                                            		         "east": 180.000018775
                                            		     },
                                            		     "temporalSubset": {
                                            		         "from" : "2000-01-01T00:00:00Z",
                                            		         "to": "2013-01-01"        
                                            		     }
                                                	  },
                                                	  {
                                            	         "CRS": "EPSG:3857",
                                            	     	 "format": "IMAGE_JPEG",
                                            	     	 "firstAxisSize": {
                                            	        	"label": "X",
                                            	        	"value": 455
                                            	     	 },
                                            		     "secondAxisSize": {
                                            		        "label": "Y",
                                            		        "value": 300
                                            		     },
                                            		     "spatialSubset": {
                                            		         "south": -60.0,
                                            		         "west": -180.0,
                                            		         "north": 90.000007823,
                                            		         "east": 180.000018775
                                            		     },
                                            		     "temporalSubset": {
                                            		         "from" : "2000-01-01T00:00:00Z",
                                            		         "to": "2013-01-01"        
                                            		     }
                                                	  }],
                                                "defaultOption": 
                                                    {
                                            	         "CRS": "EPSG:4326",
                                            	     	 "format": "IMAGE_PNG",
                                            	     	 "firstAxisSize": {
                                            	        	"label": "Lat",
                                            	        	"value": 300
                                            	     	 },
                                            		     "secondAxisSize": {
                                            		        "label": "Lon",
                                            		        "value": 300
                                            		     },
                                            		     "spatialSubset": {
                                            		         "south": -60.0,
                                            		         "west": -180.0,
                                            		         "north": 90.000007823,
                                            		         "east": 180.000018775
                                            		     },
                                            		     "temporalSubset": {
                                            		         "from" : "2000-01-01T00:00:00Z",
                                            		         "to": "2013-01-01"        
                                            		     }
                                                	  },
                                                "reducedOption": 
                                                    {
                                            	         "CRS": "EPSG:4326",
                                            	     	 "format": "IMAGE_PNG",
                                            	     	 "firstAxisSize": {
                                            	        	"label": "Lat",
                                            	        	"value": 395
                                            	     	 },
                                            		     "secondAxisSize": {
                                            		        "label": "Lon",
                                            		        "value": 600
                                            		     },
                                            		     "spatialSubset": {
                                            		         "south": -60.0,
                                            		         "west": -180.0,
                                            		         "north": 90.000007823,
                                            		         "east": 180.000018775
                                            		     },
                                            		     "temporalSubset": {
                                            		         "from" : "2013-01-01",
                                            		         "to": "2013-01-01"        
                                            		     }
                                                	  }
                                                }

Parameters:

  • onResponse Function
    Callback function for receiving asynchronous query response
    • options Object

      the access options; in case of error this argument is set to null

    • [error] String optional

      In case of error this argument contains a message which describes the problem occurred

concept

(
  • keyword
  • onResponse
  • [options]
)
async

Retrieves concepts related to the given keyword

Parameters:

  • keyword String

    The keyword by which generates the related concepts

  • onResponse Function

    Callback function for receiving asynchronous query response

    • result Array

      Array of concepts In case of error, this argument contains an empty array

    • [error] String optional

      In case of error, this argument contains a message which describes the problem occurred

  • [options] Object optional

    Object literal of available options

    • [start=1] Integer optional

      The start index of the first returned concept, starting from 1

    • [count=10] Integer optional

      The maximum number of concepts to return

    • [topLevel=false] Boolean optional

      If set to true only the top level concepts is retrieved

cswPath

() String

Retrieves the CSW path

Returns:

String:

the service csw path

cswPath

() String

Retrieves the OpenSearch path

Returns:

String:

the service OpenSearch path

discover

(
  • onResponse
  • [constraints]
  • [options]
  • [onStatus]
)
async

While the expand is limited to the node children, the result set of a discover query contains any GINode with a report matching the given constraints (if any), regardless of their level in the hierarchy.

Extending a discover ResultSet

Normally the result of this method is a single ResultSet. When the extension option is used, the discover might generate more than one ResultSet according to the following rules:

  1. generation of concepts list
  2. execution of a specific query for each concept in the list
  3. creation of a ResultSet for each query with at least one result
The ResultSet can be extended by keyword or by concepts. In the first case the list of concepts is generated by retrieving concepts related to the provided keyword (see also concept method). In the second case the list of concepts is the provided one. Besides, if the provided relation is different from NONE, the generated list contains also concepts satisfying the provided relation.

The method throws an Exception if the extension option is not properly configured (see extension option for more info)

Parameters:

  • onResponse Function

    onResponse Callback function for receiving asynchronous query response

    • response Array

      Array of ResultSet resulting from the query

      • error String
        in case of error or timeout (see options.timeout), the response array contains an empty {{#crossLink "ResultSet"}}result set{{/crossLink}} and this property describes the problem occurred
  • [constraints] Object optional

    Only nodes matching the given constraints is returned as result of the discover. The constraints argument object supports the following properties:

    • [where] Bbox optional

      A bounding box which includes the results. See also spatial relation option

    • [when] TimePeriod optional

      A time period which includes the results

    • [what] String/Array optional

      A single search keyword or an array of search keywords; in case of multiple keywords, unless specified with the options.searchOperator, the search terms are related by OR logic operator. E.g:

           constraints.what = "sst";
                                            constraints.what = ["sst","temperature"];
                                            options.searchOperator = "AND";

      As default the search is performed on the report title and report keyword fields; the options.searchFields argument can be used to specify different fields. E.g.:

          options.searchFields = "title,abstract";
    • [who] String/Array optional

      A single report id or an array report id; only the content of the correspondent nodes (matching the above constraints if any) is discovered. In case of simple nodes (which have no content), they are always added to the result set regardless of the above constraints (if any).E.g:

           constraints.who = "id1";
                                            constraints.who = ["id1,"id2,"id3"];
    • [kvp] Object/Array optional

      A single advanced constraint or array of advanced constraints submitted in the key-value pair format. E.g.:

       constraints.kvp = {"key":"minmag","value":"6"};
                                            constraints.kvp = [{"key": "minmag", "value": "6"},{{"key": "magt", "value": "MWW"}}];
      See here for a complete list of supported key-value pair parameters.
  • [options] Object optional

    This parameter object supports the following properties:

    • [start=1] Integer optional

      The start index of the first result set node, starting from 1

    • [pageSize=10] Integer optional

      The size of the result set pages

    • [extension] Object optional

      This option allows to extend the discover and has the following properties:

      • relation Relation
        The relation to be used for the extension. If different from NONE and neither keyword nor concepts are set, an Exception is thrown
      • [keyword] String optional
        The keyword to used to generate the extension concepts. If the concepts is also set, an Exception is thrown
      • [concepts] Array optional
        The array of concepts to use for the extension. If keyword is also set, an Exception is thrown
    • [timeout] Integer optional

      set a request timeout (in milliseconds)

    • [searchFields="title,keyword"] String optional

      A single search field or a comma separated list of search fields in which to perform the keyword search (see constraints.what). Possible search fields are:

      • title (default): the search is performed in the report title
      • keyword (default): the search is performed in the report keyword
      • anytext: the search is performed in the whole textual content of the report
      • description: the search is performed in the report description
    • [searchOperator="OR"] String optional

      the logic operator for multiple keywords in the constraints.what constraints. Possible values are: "OR" and "AND"

    • [spatialRelation] SpatialRelation optional

      The spatial relation used to include the results in the bounding box selected with the where constraint

    • [termFrequency="keyword,format,protocol,source"] String optional

      One or more comma separated list of term frequency target; by default all the term frequency targets are selected.
      Possible term frequency targets are:

      • keyword
      • format
      • protocol
      • source

      See here for more info
  • [onStatus] Function optional

    Callback function called every second for receiving asynchronous source status info

    • status Array

      Every second, this argument is updated with an array of SourceStatus, one for each DAB source plus another representing the DAB node with the status of the whole process and with title "DAB"

endpoint

() String

Retrieves the DAB endpoint

Returns:

String:

The URL String of this DAB instance

expand

(
  • onResponse
  • [pageSize=10]
)
async

Inherited from GINode:

If this node is {{#crossLink "Report/type:property"}}composed{{/crossLink}}, the result of the expansion is a {{#crossLink "ResultSet"}}result set{{/crossLink}} split in {{#crossLink "Page"}}pages{{/crossLink}} (possibly one if the matched nodes are minor than the {{#crossLink "ResultSet"}}result set{{/crossLink}} {{#crossLink "Page/size:method"}}page size{{/crossLink}}).
The {{#crossLink "ResultSet"}}result set{{/crossLink}} contains the underlying first level nodes (this node children). If this node is a {{#crossLink "DAB"}}{{/crossLink}} instance, than the first call of this method returns the correspondent {{#crossLink "DABSource"}}sources{{/crossLink}}.
If the {{#crossLink "ResultSet"}}result set{{/crossLink}} is split in more than one {{#crossLink "Page"}}page{{/crossLink}} use the {{#crossLink "GINode/expandNext:method"}}expandNext method{{/crossLink}} to retrieve the next ones. If this is a {{#crossLink "Report/type:property"}}simple node{{/crossLink}}, the {{#crossLink "ResultSet"}}result set{{/crossLink}} is empty

Parameters:

  • onResponse Function
    onResponse Callback function for receiving asynchronous query response
    • resultSet ResultSet

      The expansion result set set. In case of error, this argument contains an empty result set with the ResultSet/error:property property describing the problem occurred

  • [pageSize=10] Integer optional
    The size of the {{#crossLink "ResultSet"}}result set{{/crossLink}} {{#crossLink "Page"}}pages{{/crossLink}}

expandNext

(
  • onResponse
  • [execute]
)
Boolean async

Inherited from GINode:

If this node has already been {{#crossLink "GINode/expand:method"}}expanded{{/crossLink}}, this method tests if other {{#crossLink "Page"}}pages{{/crossLink}} in the {{#crossLink "ResultSet"}}result set{{/crossLink}} are available. If the test is positive and the execute argument is true, retrieves the next {{#crossLink "ResultSet"}}result set{{/crossLink}} {{#crossLink "Page"}}page{{/crossLink}}. If this node is a {{#crossLink "Report/type:property"}}composed node{{/crossLink}} but it has never been expanded, an Exception is thrown.
If this is a {{#crossLink "Report/type:property"}}simple node{{/crossLink}}, this method returns false

Parameters:

  • onResponse Function
    onResponse Callback function for receiving asynchronous query response. See onResponse for more info
  • [execute] Boolean optional
    If omitted or set to false, this method tests if other pages in the result set are available and returns the test result. If set to true and the test is positive, this method retrieves the next result set page and returns true. If set to true and the test is negative this method returns false

Returns:

Boolean: true if other pages in the result set are available, false otherwise

find

(
  • id
  • onResponse
)
async

Retrieves the node with the given report id

Parameters:

  • id String

    The node report id

  • onResponse Function

    Callback function for receiving asynchronous query response

    • result GINode

      The requested node object. If a node with the given report id does not exist or in case of error, this argument is null

    • [error] String optional

      In case of error, this argument contains a message which describes the problem occurred

googleImageMapType

(
  • map
  • [initOptions]
)
google.maps.ImageMapType[]

Inherited from GINode:

Retrieves an array of google.maps.ImageMapType; if the current {{#crossLink "GINode"}}node{{/crossLink}} does not provide any layer an empty array is returned.
All the available ImageMapTypeOptions are allowed; this method implements the getTileUrl function in order to build the correct WMS GetMap request.

Parameters:

Returns:

google.maps.ImageMapType[]: array (possible empty) of google.maps.ImageMapType

has_olVector_Layer

() String[]

Inherited from GINode:

This method checks if the {{#crossLink "GINode"}}node{{/crossLink}} provides one or more layers of type OpenLayers.Layer.Vector. The method returns an array of Strings, each string is the name of an available vector layer.

Returns:

String[]: the Array of names of available OpenLayers.Layer.Vector layers.

isAccessible

()

Inherited from GINode:

Tests if this node is accessible.
See also {{#crossLink "GINode/accessOptions:method"}}{{/crossLink}} and {{#crossLink "GINode/accessLink:method"}}{{/crossLink}} methods

Returns:

true if this node is linked to one or more data and it is asynchronously accessible, false otherwise

isDirectlyAccessible

()

Inherited from GINode:

Tests if this node is directly accessible. See also {{#crossLink "GINode/directAccessLinks:method"}}{{/crossLink}} method.
See also {{#crossLink "OnlineInfo/accessType:property"}}OnlineInfo.accessType{{/crossLink}} property

Returns:

true if this node is linked to one or more data and it has one or more direct access links, false otherwise.

ol3WMS_Layer

(
  • [opt_options]
)
ol.source.TileWMS []

Inherited from GINode:

Retrieves an array of ol.source.TileWMS ; if the current {{#crossLink "GINode"}}node{{/crossLink}} does not provide any layer an empty array is returned.
As explained in the ol.source.TileWMS constructor documentation, the returned layers can be optionally created with additional parameters and options for the GetMap request (see opt_options argument). E.g.: 
var opt_options = {};
                                            opt_options.params = {LAYERS: name, TRANSPARENT: true}; //WMS request parameters. At least a LAYERS param is required.
                                            opt_options.attributions = new ol.Attribution({
                                                                                   html: 'All maps © ' + 'ExampleMap'
                                                                             }); 
                                            
                                            var layers = giNode.ol3WMS_Layer(opt_options);

Parameters:

Returns:

ol.source.TileWMS []: Array of ol.source.TileWMS possible empty if this {{#crossLink "GINode"}}node{{/crossLink}} does not provide any

olTiles_Layer

(
  • [initOptions]
)
OpenLayers.Layer.WMS[]

Inherited from GINode:

Retrieves an array of OpenLayers.Layer.WMS (TiledMapService type); if the current {{#crossLink "GINode"}}node{{/crossLink}} does not provide any layer an empty array is returned.
As explained in the OpenLayers.Layer.WMS constructor documentation, the returned layers can be optionally created with additional parameters and options for the GetMap request (see initOptions argument). E.g.: 
var initOptions = {};
                                            initOptions.params = {transparent: true}; // corresponds to the OpenLayers.Layer.WMS params argument
                                            initOptions.options = {opacity: 0.5}; // corresponds to the OpenLayers.Layer.WMS options argument
                                            
                                            var layers = giNode.olTiles_Layer(initOptions);

Parameters:

Returns:

OpenLayers.Layer.WMS[]: Array of OpenLayers.Layer.WMS possible empty if this {{#crossLink "GINode"}}node{{/crossLink}} does not provide any

olVector_Layer

(
  • onResponse
)
async

Inherited from GINode:

Retrieves an array of OpenLayers.Layer.Vector; if the current {{#crossLink "GINode"}}node{{/crossLink}} does not provide any layer an empty array is returned.
Besides, client applications are required (at the moment) to handle the cross-origin nature of the request which is executed (GML is an XML encoding)

Parameters:

olWMS_Layer

(
  • [initOptions]
)
OpenLayers.Layer.WMS[]

Inherited from GINode:

Retrieves an array of OpenLayers.Layer.WMS; if the current {{#crossLink "GINode"}}node{{/crossLink}} does not provide any layer an empty array is returned.
As explained in the OpenLayers.Layer.WMS constructor documentation, the returned layers can be optionally created with additional parameters and options for the GetMap request (see initOptions argument). E.g.: 
var initOptions = {};
                                            initOptions.params = {transparent: true}; // corresponds to the OpenLayers.Layer.WMS params argument
                                            initOptions.options = {opacity: 0.5}; // corresponds to the OpenLayers.Layer.WMS options argument
                                            
                                            var layers = giNode.olWMS_Layer(initOptions);

Parameters:

Returns:

OpenLayers.Layer.WMS[]: Array of OpenLayers.Layer.WMS possible empty if this {{#crossLink "GINode"}}node{{/crossLink}} does not provide any

overview

(
  • id
  • onResponse
  • [options]
)
Boolean async

Inherited from GINode:

If this {{#crossLink "GINode"}}node{{/crossLink}} has an {{#crossLink "Report/overview:property"}}overview{{/crossLink}}, creates an <img> having as source the {{#crossLink "Report/overview:property"}}overview{{/crossLink}} link at the given options.index (0 if not specified) and appends <img> to the element having the given id.
The {{#crossLink "Report/overview:property"}}overview{{/crossLink}} property can be available also if this {{#crossLink "GINode"}}node{{/crossLink}} is not accessible.

The method throws an Exception if id does not correspond to an element or if options.index does not respect the following statement: index >= 0 && index <= {{#crossLink "Report/overview:property"}}overview{{/crossLink}}.length - 1

Parameters:

  • id String
    the id of an element in which to append the <img> element of the selected overview
  • onResponse Function
    Callback function for receiving asynchronous request status
    • status String

      possible status are 'success' and 'error'

    • [message] String optional

      in case of 'error' status this argument contains the error message

    • [image] String optional

      the loaded image element or null in case of error

  • [options] Object optional
    • [index=0] Number optional

      index of this node overview array

    • [size="medium"] String optional

      The overview size (aspect ration is preserved). Possible values are:

      • "extra small": 48x48 px
      • "small": 96x96 px
      • "medium": 144x144 px
      • "large": 288x288 px
      • "original": the original size of the target overview image
    • [force=false] Boolean optional

      If set to true a "no overview" image is used in case of error or in case an overview is not available

    • [backgroundURL] String optional

      URL of an additional image to load as background of the overview image (use this only if the overview image is transparent)

Returns:

Boolean: true if this {{#crossLink "GINode"}}node{{/crossLink}} has an {{#crossLink "Report/overview:property"}}overview{{/crossLink}}, false otherwise

pubSubManager

() PubSubManager

Returns the PubSubManager instance.

Returns:

PubSubManager:

returns the PubSubManager instance

report

(
  • [newReport]
)
Report

Inherited from GINode:

Retrieves and optionally set a new {{#crossLink "Report"}}report{{/crossLink}}

Parameters:

  • [newReport] Report optional
    The new {{#crossLink "Report"}}report{{/crossLink}}

Returns:

Report: The node {{#crossLink "Report"}}report{{/crossLink}}

servicePath

() String

Retrieves the service path

Returns:

String:

the service path

sources

(
  • onResponse
  • [viewId]
)
async

Retrieves the nodes representing the sources brokered by this DAB instance. DAB sources can also be retrieved as result of the first call of the expand method

Parameters:

  • onResponse Function

    Callback function for receiving asynchronous query response

    • result Array

      Array of DAB sources In case of error, this argument contains an empty array

    • [error] String optional

      In case of error, this argument contains a message which describes the problem occurred

  • [viewId] String optional

view

(
  • [action]
  • [constraints]
)

Defining a "client-side" view on the result set

A "client-side" view is a way to limit the result set on one or more specific constraint like where constraint, thus providing a "view" of the entire result set. Additional constraints used in the discover are merged with the view constraints in order to further refine the initial result set.
For example, a web portal can provide earthquakes info only on the west coast of south America, by defining a view with the where constraint covering that area. When the users make a search they can retrieve only results from the area defined in the view; furthermore they can add, for example, when constraint to retrieve results in a particular temporal period.

Parameters:

  • [action] String optional

    possible values are: "enable" to enable the view, "disable" to disable it. Can be omitted if this method is used only as "get" method

  • [constraints] Object optional

    the view constraints (unnecessary if the action is "disable" or if this method is used only as "get" method)

Returns:

the current view constraints

Properties

uiId

String

Inherited from GINode:

Identifier created with {{#crossLink "GIAPI/random:method"}}{{/crossLink}} method which contains only alphanumeric characters and can be used inside the attributes of DOM elements