API

The search controller. AdmiralCloud’s search is based on OpenSearch/ElasticSearch (ES). You can use ES query language (DSL). Some limitations might occur and some fields/properties might not be allowed to use or return unexpected results as we sanitize and enhance every search request to ensure security of the call.

If you want to create complex applications it is highly recommended to talk to our engineering team.

Default search

The default search parameters, like aggregations or searchableFields can be found using Misc Controller. The searchableFields are those the standard search uses.

Basic Search

Enable basic search to search in field “relevantWords”. Relevant words is a combined field from container_name and tags.

Customized search experience

You can customize the search experience on a customer or user base. You can define other aggregations (as long as they are members of the default aggregations set) and you can customize which fields you want to be searched and what boosting they should have.

See Customized search experience for an example

Examples for searches

Basic/Simple search

// search for the given search term in all default fields (usually container_name, container_description)
{
    "searchTerm": "my search term",
}

Complex searches

In order to work with complex searches, it is highly recommended to make yourself familiar with OpenSearch/ElasticSearch query DSL.

// search for huset (swedish for house) but search only videos and boost hits in swedish by factor 100.
{
   "size":30,
   "languages":[
      {
         "lang":"sv",
         "boost": 100
      }
   ],
   "searchTerm":"huset",
   "query":{
      "bool":{
         "filter":[
            {
               "terms":{
                  "type":[
                     "video"
                  ]
               }
            }
         ]
      }
   }
}

Special searches

// color search
{
   "searchTerm":"55,66,204",
   "field":"colorSearch",
   "colorSearchParams":{
      "diff_ab":20,
      "diff_l":10
   }
}

// geo search
{
   "searchTerm":"47.49, 19.05, 10",
   "field":"gps"
}

Caveats and important remarks

When using search with size and from, you might run into a situation where not all documents for the search or even duplicates (on the next page/batch) are returned. It you want to scroll through results, it is recommended to use scroll contexts instead of size and from.

Elasticsearch uses Lucene’s internal doc IDs as tie-breakers. These internal doc IDs can be completely different across replicas of the same data. When paging search hits, you might occasionally see that documents with the same sort values are not ordered consistently.

https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html

Reference

Search as you type

Search-as-you-type enables you to fetch already existing values for a given field (e.g. return existing artists for field meta_artists)

searchTerm	string
field	string

{
    "searchTerm": "prince",
    "field": "meta_artist"
}

Search

Search based on Open Search/ElasticSearch (ES). You can either use simple search with searchTerm and other parameters (except query) or use the ES query language with the query parameter to perform complex searches.

We are searching in uni language and in the user’s language. The latter has more relevance than uni.

Available fields for searchTerm/field search

Field	Type	Notes/Explanation
id	integer	id id of a specific mediacontainer
links	string	contains the links of external pages related to a mediacontainer (e.g. find a publicarea by link, …)
orientation	integer	orientation of media (image) – default 1, 8 > rotate clockwise, 3 > 180°, 6 > rotate counter-clockwise
width	integer	width of the original media of the mediacontainer
height	integer	height of the original media of the mediacontainer
fps	float	fps of the original media of the mediacontainer
colorSpace	string	colorSpace of the original media of the mediacontainer (RBG, CYMK, …)
checksum	string	search for this checksum (to find duplicates). Use prefix v1 for classic md5 checksum (deprecated) and v2 for new checksum based on AC-FileHash

Color Search

• searchTerm must be a comma-separated list of RGB values (55,66,204)
• Optional you can send colorSearchParams to set the range for the color search
• Use field “colorSearch”

GPS/Geo-Location search

• searchTerm must be a comma-separated list of lat, lng, search radius in km – 47.49, 19.05, 10 means search in a 10km radius around 47.49 lat and 19.05 lng
• Use field “gps”

Aggregations

Please note, that aggregations will be returned based on the user’s searchConfiguration. Aggregations for “meta_productionYearAndMonth” and “meta_productionYearAndDay” will only be returned if a appropriate range request is in bool.filter of the query.

Search similar items

Fetch similar items based on a given mediaContainerId. Similarity can be using phash, checksum and objectDetection.