Search API

The Search API is used to perform searches on domains and resources with search suggestions.

Required role: Read
Optional privilege: Domains.READ
Optional privilege: ThingTypes.READ

The search handles prefix-wildcard searches. Searches can be made on for example La, veg for results on Las Vegas, but searches on gas will not return any results. For best result it’s always recommended to be as granular as possible.

It’s possible to specify size and use pagination, change the default sort field and order, by default it’s enough to just pass a search term.

API Endpoint: [POST]: /search

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • term: A few characters like ‘Swe’ or the full word ‘Sweden’, leave empty for wildcard search required
  • size: Number of returned results, default is 100. optional
  • from: Use for pagination together with size. optional
  • sort: Default sort is ascending on field term. optional
    • field: Ex. dataType, thingType, resourceType, the default field is term. optional
    • order: asc (default) or desc. optional
  • filter: optional
    • type: Filter on type, ex. domain or resource, default is both. optional
    • dataType: Filter on data type, ex. string/long/geo_point/unknown (only applicable when searching for resources) optional
    • thingType: Filter on a thingType id (only applicable when searching for resources) optional
    • resourceType: Filter on type of resource, ex. thing/sub-thing/virtual/tcxn (only applicable when searching for resources) optional
    • topDomain: Filter on domainPath and returns the topDomain with all subDomains included optional

Example payload wildcard search for all domains and resources

The domain(s) in the result returned from this payload will be filtered by the domains where the calling user has the Domains.READ privilege.
The resource(s) in the result returned from this payload will be filtered by the Thing Types that exist in domains where the calling user has the ThingTypes.READ privilege.

{
  "term": ""
}

Example payload for domains called sub* (subdomain, child subdomain etc.)

The results returned from this payload will be filtered by the domains where the calling user has the Domains.READ privilege.

{
    "term": "sub",
    "filter": {
      "type": "domain"
    }
}

Example payload for resources with type geo_point

The results returned from this payload will be filtered by the Thing Types that exist in domains where the calling user has the ThingTypes.READ privilege.

{
    "term": "sub",
    "filter": {
      "type": "resource",
      "dataType": "geo_point"
    }
}

Response

A result object will be returned with the number of hits specified in size (default 100) to get next 100 results run the same query with from set to 100 instead of 0.

const hits = res.hits.hits; // Array with hits (100 by default)
const total = res.hits.total; //Total number of hits for ex. 150

Each hit in hits has a _source that looks a little bit different depending on the type (domain/resource). The difference in the response is the metadata object that returns different data for domains and resources.

Ex. Domain result:

  • _source
    • id: domainId
    • label: domain name/label
    • metadata
      • parent: Id of parent domain
      • path: Path to domain ex. root/subdomain1/sub-subdomain2 (you can only see up the path as far as you have access)
    • searchType: domain

Ex. Resource result:

  • _source
    • id: thingTypeId/resource name for ex: ‘1/latlng’
    • label: Name of resource for ex. ‘latlng’
    • metadata
      • dataType: ‘geo_point’ can also be string/long/unknown etc.
      • resourceType: ‘thing’ can also be sub-thing/virtual/tcxn
      • thingType: Id of the thingType the resource belongs to for ex. ‘1’
    • searchType: resource

Errors

Key Params Property Description
INVALID_ARGUMENTS query Returned if the query is invalid or doesn’t meet the requirements specified above.