Hexagon Geospatial
MENU

API

M.App Portfolio provides a modern, cloud-based platform for creating and delivering diverse geospatial web applications.
Through the M.App Studio, our partners can design, build, and deploy their own Hexagon Smart M.Apps.
Showing results for 
Search instead for 
Do you mean 

Foundation - Search API

by Technical Evangelist ‎11-10-2016 05:40 AM - edited ‎11-10-2016 08:03 AM (1,331 Views)

Foundation - Search API

Provides the ability to search, filter, and format the results of a user's catalog. 

 

Basic search features

The Search API provides powerful search capabilities for a user's catalog. Not only does it provide search capabilities, but it also provides various filtering, ordering, and paging features. The general parameters used for the Search API are listed below. 

 

General Search Parameters:
Title Required Type Values Description
maxresults false int Any valid integer Maximum number of results to be returned
first false int Any valid integer Starting index for results, combine with maxresults for paging through results.
orderby false String or Array[String]

Any of the values below coupled with asc or desc:

  • class
  • registrationDate
  • modificationDate
  • creationDate
Space separated property used to help properly present results.
profile false String
  • full
  • summary
  • brief
  • eac-brief
Responsible for determining how much detail is included in each catalog item. 
template true JSON Object Any valid template property This parameter represents a pattern for the requested catalog items. The template consists of catalog items attributes and their desired properties. It is possible to specify a single value that requires an exact match or, for selected attributes types, a range of values.
class true Array[String] Any valid catalog entity Template property used to filter results based on class. 
parent false JSON Object Must contain an "id" property with a valid catalog item id of a folder.   Template property used to filter results based on parent folder.  
name false String Any valid JSON string Template property used to filter results based on search name
keyword false String Any valid JSON string Similar to the {name} with the exception that it provides a more expansive search of catalog item properties including: title, name, tags, descriptions, class, decoder types, etc.
 
 

All request made to the Search API must use the following endpoint:

POST http://mapp.hexagongeospatial.com/api/v1/search.json

 

The results for any request made will be all catalog items that match the specificed parameters. An example of the response is below:

 

{
  "_encodingVersion": "2.0",
  "_encodingTime": 118,
  "context": {
    "totalAvailableResults": 3216,
    "queryParameters": {},
    "maxResults": 10,
    "startIdx": 0,
    "queryTimeMillis": 79,
    "rootPath": "http://catalog.hexagongeospatial.vpc:80/api/v1",
    "_class": "com.erdas.rsp.babel.service.rest.RestletQueryContext"
  },
  "results": [
    {
      "identifier": "f2343c66-619b-45f4-9aa1-b3fb21672aa7",
      "defaultAttachmentName": "default",
      "name": "sample",
      "id": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c91808150716aab01507173f1300629",
      "_class": "com.erdas.rsp.babel.model.GenericItem",
      "title": "sample.rtf",
      "parentId": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918081506fed51015071568afe001e"
    },
    ...
  ]
}

 

 

Paging, profiles, and ordering

Here we will provide a few examples of using the general search parameters to configure and filter results. We will describe these properties while also explaining how these examples can be used in applications. 

 

Paging

 

Using the {first} and {maxresults} properties we are able to page through results. This means we are able to choose the number of items that are returned to us, as well as, the ability to specify our starting index. See the sample request below:

 

{
maxresults: 10,
first: 0,
'template' : {
'class': 'com.erdas.rsp.babel.model.CatalogItem',
}
}

 

 

This simple request would locate all items avaiable to the current user with a class of "com.erdas.rsp.babel.model.CatalogItem", then return to us items at index 0 through 10. If we wanted the next set of results, we simply need to change the {first} property to be 10(which is the index of the last item we returned in the first set). See an example of this request below:

 

{
 maxresults: 10,
 first: 10,
 'template' : {
     'class': 'com.erdas.rsp.babel.model.CatalogItem',
 }
}

 

 

Profiles

 

Another common feature many users require is the ability to specify how detailed the item they need are. Using the Search API users have the ability to return serveral levels of detailed information about each item. We specify the level of detail using the {profile} property. The values for this parameter can be found in the "General Search Parameters" table above. Here we will show you a sample request that will retrieve the maximum level of detail for each item. See the sample request below:

 

{
  maxresults: 10,
  first: 0,
  profile: 'full',
  'template' : {
       'class': 'com.erdas.rsp.babel.model.CatalogItem',
  }
}

 

This request will return the first ten items matching the "com.erdas.rsp.babel.model.CatalogItem" class in full detail. A sample of this response is below:

{
  "_encodingVersion": "2.0",
  "_encodingTime": 176,
  "context": {
    "totalAvailableResults": 3217,
    "queryParameters": {},
    "maxResults": 1,
    "startIdx": 0,
    "queryTimeMillis": 15,
    "rootPath": "http://catalog.hexagongeospatial.vpc:80/api/v1",
    "_class": "com.erdas.rsp.babel.service.rest.RestletQueryContext"
  },
  "results": [
    {
      "parent": {
        "identifier": "2762e0f2-9119-4b50-b6e9-4715366ca150",
        "defaultAttachmentName": "default",
        "name": "Test",
        "id": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de513f7426",
        "title": "Test",
        "parentId": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c9180c3506b476c01506b899f9f00dd"
      },
      "downloadEnabled": false,
      "publishIsAllowed": true,
      "geoServicesEnabled": false,
      "storageStatus": null,
      "classifyingConcepts": [],
      "metadataURI": null,
      "path": "60de3d24-4804-47e8-800c-f13affe7a8c7/null",
      "wmsEnabled": false,
      "wcsEnabled": false,
      "children": [],
      "registrationDate": "2016-10-31T21:20:53Z",
      "id": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918082579a7fab01581c9dccfe678a",
      "spatialExtentZPixelSize": null,
      "viewEnabled": false,
      "identifier": "5854e362-5e3c-4875-ae45-9f3a46882aef",
      "associationsAsSource": [],
      "jpipEnabled": false,
      "temporalExtentStartDate": null,
      "wmtsEnabled": false,
      "creationDate": null,
      "tags": [],
      "drawOrder": 0,
      "czsEnabled": false,
      "defaultAttachmentName": "default",
      "name": "newFolder",
      "onlineStoragePath": null,
      "_class": "com.erdas.rsp.babel.model.ResourceAggregate",
      "ogcUniqueName": null,
      "favorite": false,
      "providerConfig": null,
      "associationsAsTarget": [],
      "temporalExtentEndDate": null,
      "spatialExtentYPixelSize": null,
      "hidden": false,
      "nativeFootprint": null,
      "description": "description",
      "rangeSetDescription": null,
      "title": "newFolder",
      "connectorClass": null,
      "offlineStoragePath": null,
      "security": {
        "owner": "02ec7ba1-03bc-4b4c-8801-0130e188a2ca",
        "shared": false
      },
      "nameQualifier": "babel://coverages",
      "fileURI": null,
      "externalBucketName": null,
      "registryPackages": [],
      "imageXEnabled": false,
      "activeStoragePath": null,
      "pyramidDescriptor": null,
      "downloadIsAllowed": true,
      "parentId": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de513f7426",
      "spatialExtentXPixelSize": null,
      "modificationDate": null,
      "decoderName": null,
      "footprint": null,
      "domainSetExtent": null,
      "ecwpEnabled": false,
      "dBConnectionConfig": null,
      "properties": {}
    }
  ]
 

Ordering

 

In addition to filtering our search results we also have the ability control the order of how our how results are returned. We have the ability to order our results by using many of the same properties that we use for filtering. We can format our results in ascending or descending order based on: entitiy class, registrationDate, creationDate, modificationDate, etc. We do this by using the "orderby" property described below:

 

Title Required Type Values Description
orderby false String or Array[String]

Any of the values below coupled with asc or desc:

  • class
  • registrationDate
  • modificationDate
  • creationDate
The property used to format the order the results returned from the Search API.

 

Below is a simple example using the {orderby} property:

{
  maxresults: 10,
  first: 0,
  orderby: 'registrationDate desc',
  template : {
      'class': 'com.erdas.rsp.babel.model.CatalogItem'
  }
}

In the example above we display how the Search API can accept a single string for the "orderby" property. With this string we specify the property and the direction we want to order by. This request will return all catalog item's with an entity class of "com.erdas.rsp.babel.model.CatalogItem" in descending order according to "registrationDate".

 

Sample payload using orderby property as a string array:
{
  maxresults: 10,
  first: 0,
  orderby: ['class asc', 'registrationDate desc'],
  template : {
      'class': 'com.erdas.rsp.babel.model.CatalogItem'
  }
}

In the example above we display how the Search API can accept a string array for the "orderby" property. Each string in the array is the property and the direction we want to order by. This request will return all catalog item's with an entity class of "com.erdas.rsp.babel.model.CatalogItem", these results will be formatted in descending order according to registrationDate and acesding order according to their entity class.

 

 

Using the template

 

Search by name

 

The most basic feature of the Search API is the ability to search the catalog based on a text search. To do this we use the {name} property in the template. This will return all catalog items that match partial/full portion of your search. A basic example of a text search request is below:

{
  maxresults: 10,
  first: 0,
  orderby: 'registrationDate',
  template : {
      'class': 'com.erdas.rsp.babel.model.CatalogItem',
      'name': 'sample text'
  }
}

 

Search by parent

 

Using the Search API we have the ability to apply search criteria to a particular parent folder. Doing this would allow us to us to display all items inside of a folder that match our search criteria. To do this we use the {parent} object inside of the template. A description of the parent propety is below:

Title Required Type Values Description
parent false Object {id} - parameter containing the catalog id of the intended folder  Parameter used to filter results based on the parent folder. Use the {id} property to specify the catalog id of the intended folder.

 

Here is a sample request using the parent object in the template:

{
  "maxresults": 10,
  "start": 0,
  "profile": "full",
  "template": {
    "class": [
      "com.erdas.rsp.babel.model.CatalogItem"
    ],
    "parent": {
      "id": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de513f7426"
    }
  }
}

This example would return all items that have a class of "com.erdas.rsp.babel.model.CatalogItem" inside the folder with the matching catalog id.

 

 

Search by creation date

Displays results from the catalog that correspond to the creation start and end dates included in the request.

 

Filtering search results based on a catalog item's "creationDate" property is just one of many ways for a user to dictate how results are returned from the Search API. Date interval filtering works in a similiar fashion with all of a catalog item's date properties. The parameters that directly affect the ability to filter by the "creationDate" property are below: 

 

Title Required Type Values Description
creationDate false JSON Object

Valid JSON Object with the following properties:

  • _op
  • lo
  • hi
Object used to configure the creationDate filter.
_op false String Any valid creation date filter operation Type of filter operation applied to the results
lo false String Any valid ISO formatted date Date to be applied to the beginning of the date interval
hi false String Any valid ISO formatted date Date to be applied to the end of the date interval.

 

 

The code below is an example of how to correctly format a request payload that filters results based on the creationDate. The payload below would only retrieve catalog items with a "creationDate" between "2016-05-01" and "2016-05-30". 

 

Search template:
{
  maxresults: 10,
  first: 0,
  orderby: 'registrationDate',
  'template' : {
       'class': 'com.erdas.rsp.babel.model.CatalogItem',
       'creationDate' : {
           _op: 'interval',
           lo : '2016-05-01',
           hi : '2016-05-30'
       }
  }
}

 

 

Search by registration date

Displays results from the catalog that correspond to the registration start and end dates included in the request.

 

Filtering a user's search results based on "registrationDate" is very similar to the way we filter our search results by any catalog date property. We simply need add the "registrationDate" property to the template object and provide our interval properties. The parameters that directly affect the ability to filter by the "registrationDate" property are below:

 

Title Required Type Values Description
registrationDate false JSON Object

Valid JSON Object with the following properties:

  • _op
  • lo
  • hi
Object used to configure the registrationDate filter.
_op false String Any valid registration date filter operation Type of filter operation applied to the results
lo false String Any valid ISO formatted date Date to be applied to the beginning of the date interval
hi false String Any valid ISO formatted date Date to be applied to the end of the date interval.

 

Search template:
{
  maxresults: 10,
  first: 0,
  orderby: 'registrationDate',
  'template' : {
           'class'    : 'com.erdas.rsp.babel.model.CatalogItem',
           'registrationDate' : {
               _op: 'interval',
               lo : '2016-05-01',
               hi : '2016-05-30'
           }
  }
}

 

Search by modification date

Displays results from the catalog that correspond to the modification start and end dates included in the request.

 

Filtering the results from the Search API based on "modificationDate" is very similar to our other date filters. We simply need to include the "modificationDate" property in the template object, and specify the operation and date range. The parameters that directly affect the ability to filter by the "modificationDate" property are below:

 

Title Required Type Values Description
modificationDate false JSON Object

Valid JSON Object with the following properties:

  • _op
  • lo
  • hi
Object used to configure the modificationDate filter.
_op false String Any valid modification date filter operation Type of filter operation applied to the results
lo false String Any valid ISO formatted date Date to be applied to the beginning of the date interval
hi false String Any valid ISO formatted date Date to be applied to the end of the date interval.

 

Search template:
{
  maxresults: 10,
  first: 0,
  orderby: 'registrationDate',
  'template' : {
           'class'    : 'com.erdas.rsp.babel.model.imagery.DatasetReference',
           'modificationDate' : {
               _op: 'interval',
               lo : '2016-05-01',
               hi : '2016-05-30'
           }
  }
}

 

 

Spatial search

Displays results from the catalog that correspond to the geometry parameters included in the request. A spatial search describes a geometry that intersects the extent(footprint) of the desired catalog items.

 

Search template:

{
  maxresults: 10,
  first: 0,
  'template' : {
      'class': 'com.erdas.rsp.babel.model.ows.ServiceResource',
      'footprint': {
            _op: 'intersect',
            geom: {
                'srs':'EPSG:4326',
                'type':'POLYGON',
                'cardinality':2,
                'compression':1,
                'data':[[-89.28,-13.68,-128.16,61.2,45.36,88.56,7.92,-19.44]]
}
} } }

 

 

Search by classes

Filter results by multiple classes to only return catalog items of a particular class.

 

Using the Search API we also have the ability to filter our search results based on a class. For example if we needed to filter our results to only Images and Folders, we would make our request in the following format:

{
"maxresults": 10,
"first": 0,
"orderby": "registrationDate",
"template": {
"class": [
"com.erdas.rsp.babel.model.imagery.ImageReference",
"com.erdas.rsp.babel.model.imagery.Aggregate"
],
}
}

 

To do this we use the "class" property. Using this property we specify a string array of classes we want included in our results. We can use this to specify any number of valid classes we want in our request.

 

Title Required Type Values Description
class true Array[String] or String
  • com.erdas.rsp.babel.model.imagery.ImageReference
  • com.erdas.rsp.babel.model.ResourceAggregate
  • com.erdas.rsp.babel.model.vector.VectorReference
  • com.erdas.rsp.babel.model.pointcloud.PointCloudResource
  • com.erdas.rsp.babel.model.GenericItem
  • com.erdas.rsp.babel.model.application.ApplicationResource
  • com.erdas.rsp.babel.model.map.MapResource
  • com.erdas.rsp.babel.model.workflow.WorkflowResource
  • com.erdas.rsp.babel.model.ModelResource
Property that fiters the results by catalog item class. Only items of the given classes will be included in results.

 

 

Filter by Ownership

Displays results according to the owner property

 

A catalog item's shared status is a boolean value, therefore when using the Search API two options are available - retrieving results that are shared with the current user or retrieving results that solely belong to the current user. In the Search API we use the "owner" property to specify what results we want.

 

Owner property:
Title Required Type Values Description
owner false String
  • "me"
  • "not-me"
  • <user>
  • not-<user>
This property fitlers serch results based on shared property on catalog items. Setting the owner property to "me" will return items that solely belong to the current user. Setting the owner property to "not-me" will return only items shared with the current user. If this property is excluded from the request, the service will return all catalog items both shared and not-shared.   

 

 

Sample payload using owner filter:
{
  "maxresults": 10,
  "start": 0,
  "orderby": [
    "id asc"
  ],
  "profile": "full",
  "owner": "me",
  "template": {
    "class": [
      "com.erdas.rsp.babel.model.ResourceAggregate",
      "com.erdas.rsp.babel.model.imagery.ImageReference",
      "com.erdas.rsp.babel.model.vector.VectorReference",
      "com.erdas.rsp.babel.model.pointcloud.PointCloudResource",
      "com.erdas.rsp.babel.model.GenericItem"
    ],
    "parent": {
      "id": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de513f7426"
    }
  }
}

 

This request will retrieve all items that have been uploaded to the given parent aggregate id. Notice how the owner property is set to "me", which is what is responsible for filtering out data that has been shared with the current user.

 

To modify this request to only retrieve the items that have been shared with the current user, modify the request to match the following:

 

{
  "maxresults": 10,
  "start": 0,
  "orderby": [
    "id asc"
  ],
  "profile": "full",
  "owner": "not-me",
  "template": {
    "class": [
      "com.erdas.rsp.babel.model.ResourceAggregate",
      "com.erdas.rsp.babel.model.imagery.ImageReference",
      "com.erdas.rsp.babel.model.vector.VectorReference",
      "com.erdas.rsp.babel.model.pointcloud.PointCloudResource",
      "com.erdas.rsp.babel.model.GenericItem"
    ],
    "parent": {
      "id": "e18b0308-47c3-42ef-a9a9-fabf56ceda19_2c918083566d176f015671de513f7426"
    }
  }
}

 

Comments
by
on ‎11-10-2016 06:12 AM

Why is searching by name not possible? That seems one of the most basic ways to search? At least, that's what I'm looking for.

by Technical Evangelist
on ‎11-10-2016 08:01 AM
We noticed that right away, we missed including the {name} and {keyword} properties in the template. @haayman I believe this will help you with what you need.
Contributors