assets/

Available in ImageVault 5.9

The assets endpoint is for performing search on assets using the ImageVault search engine and is an alternative to the mediaservice/find endpoint. The ImageVault search engine is powered by Azure Search Service

info/

GET /apiv2/assets/info

C#

client.Get<AssetsEndpointInfo>("assets/info");

Since the search engine is optional you can perform a GET request on assets/info to see the status of the assets endpoint.

response

{ 
  "searchEnabled": true 
}

The response contains the following properties

Name Type Description
searchEnabled boolean If assets search endpoint is active, searchEnabled is set to true.

? search

GET /apiv2/assets?[queryParameters]

C#

client.Get<ODataResponse<Asset>>("assets", 
    new NameValueCollection { { "$top", "10" } });

The search function allows you to perform a search on the indexed assets.

Query parameters

Provides the term to search for. You can supply multiple terms separated by whitespace and they will match assets if they match one or more of the terms (see OR operator | )

Operators

AND operator +

The AND operator is a plus sign. For example, sun+beach will search for assets containing both sun and beach.

OR operator |

The OR operator is a vertical bar or pipe character. For example, sun | beach will search for documents containing either sun or beach or both.

(OR) NOT operator -

The (OR) NOT operator is a minus sign. For example, sun –beach will search for documents that have the sun term or do not have beach.

AND NOT operator +-

The AND NOT operator is a combination of the AND and NOT operators. For example, sun +–beach will search for documents that have the sun term and do not have beach.

Suffix operator *

The suffix operator is an asterisk. For example, bea* will search for documents that have a term that starts with bea, ignoring case.

Phrase search operator " "

The phrase operator encloses a phrase in quotation marks. For example, while Atlantic Ocean (without quotes) would search for documents containing Atlantic or Ocean anywhere in any order, "Atlantic Ocean" (with quotes) will only match documents that contain that whole phrase together and in that order (text analysis still applies).

Precedence operator ()

The precedence operator encloses the string in parentheses. For example, ocean+(sun | beach) will search for documents containing the ocean term and either sun or beach (or both).

Escaping search operators

In order to use the above symbols as actual part of the search text, they should be escaped by prefixing them with a backslash. For example, beach\+hotel will result in the term beach+hotel. In order to make things simple for the more typical cases, there are two exceptions to this rule where escaping is not needed:

  • The NOT operator - only needs to be escaped if it's the first character after whitespace, not if it's in the middle of a term. For example, wi-fi is a single term; whereas a GUID (such as 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD) are treated as a single token.
  • The suffix operator * needs to be escaped only if it's the last character before whitespace, not if it's in the middle of a term. For example, wi*fi is treated as a single token.

$filter

A $filter expression can execute standalone as a fully expressed query, or refine a query that has additional parameters. For more information on the filter syntax, please read through the Azure search documentation regarding Filter syntax.

$orderby

A list of comma-separated expressions to sort the results by. Each expression is a field name. Each expression can be followed by asc to indicate ascending, and desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no $orderby is specified, the default sort order is descending by document match score. There is a limit of 32 clauses for $orderby.

$skip (optional)

$skip=<number>

The number of search results to skip. This value cannot be greater than 100,000. If you need to scan documents in sequence, but cannot use $skip due to this limitation, consider using $orderby on a field that has unique values for every document in the index (like the Ocean id, for example) and $filter with a range query instead.

$top (optional)

$top=<number>

The number of search results to retrieve. This defaults to 50. If you specify a value greater than 1000 and there are more than 1000 results, only the first 1000 results will be returned.

Azure Search uses server-side paging to prevent queries from retrieving too many documents at once. The default page size is 50, while the maximum page size is 1000. This means that by default Search Documents returns at most 50 results if you don't specify $top.

$count (optional)

$count=true | false

Optional, defaults to false. When calling via POST, this parameter is named count instead of $count. Specifies whether to fetch the total count of results. This is the count of all documents that match the search and $filter parameters, ignoring $top and $skip. Setting this value to true may have a performance impact. Note that the count returned is an approximation. If you’d like to get only the count without any documents, you can use $top=0.

$select (optional)

$select=[string] (optional)

A list of comma-separated fields to include in the result set. If set to *, all fields are included in the projection.

Note

if you specify the symbols field in the select statement, it will only include symbols for the requested fields. In order to get all symbols, be sure to include the fields that the symbols are based on. (contentType (video symbol), metadata (metadata symbols), agreementId (agreement symbols))

$facet (optional)

A field to facet by. Optionally, the string may contain parameters to customize the faceting, expressed as comma-separated name:value pairs. ~When calling via POST, this parameter is named facets instead of facet.~

Valid parameters are:

  • count (max # of facet terms; default is 10). There is no upper limit on the number of terms, but higher values incur a corresponding performance penalty, especially if the faceted field contains a large number of unique terms.

    For example, facet=modifiedBy,count:5 gets the top five categories in facet results. Note that if the count parameter is less than the number of unique terms, the results may not be accurate. This is due to the way faceting queries are distributed across shards. Increasing count generally increases the accuracy of term counts, but at a performance cost.

  • sort (one of count to sort descending by count, -count to sort ascending by count, value to sort ascending by value or -value to sort descending by value).

    For example, facet=category,count:3,sort:count gets the top three categories in facet results in descending order by the number of documents with each city name. If the top three categories are Budget, Motel, and Luxury, and Budget has 5 hits, Motel has 6, and Luxury has 4, then the buckets will be in the order Motel, Budget, Luxury. facet=rating,sort:-value produces buckets for all possible ratings, in descending order by value. For example, if the ratings are from 1 to 5, the buckets will be ordered 5, 4, 3, 2, 1, irrespective of how many documents match each rating.

  • values (pipe-delimited numeric or Edm.DateTimeOffset values specifying a dynamic set of facet entry values).

    For example, facet=baseRate,values:10|20 produces three buckets: one for base rate 0 up to but not including 10, one for 10 up to but not including 20, and one for 20 and higher. facet=lastRenovationDate,values:2010-02-01T00:00:00Z produces two buckets: one for hotels renovated before February 2010, and one for hotels renovated February 1st, 2010 or later.

  • interval (integer interval greater than 0 for numbers, or minute, hour, day, week, month, quarter, year for date time values).

    For example, facet=baseRate,interval:100 produces buckets based on base rate ranges of size 100. If base rates are all between $60 and $600, there will be buckets for 0-100, 100-200, 200-300, 300-400, 400-500, and 500-600. facet=lastRenovationDate,interval:year produces one bucket for each year when hotels were renovated.

  • timeoffset ([+-]hh:mm, [+-]hhmm, or [+-]hh). If used, the timeoffset parameter must be combined with the interval option, and only when applied to a field of type Edm.DateTimeOffset. The value specifies the UTC time offset to account for in setting time boundaries.

    For example: facet=lastRenovationDate,interval:day,timeoffset:-01:00 uses the day boundary that starts at 01:00:00 UTC (midnight in the target time zone).

count and sort can be combined in the same facet specification, but they cannot be combined with interval or values, and interval and values cannot be combined together.

Interval facets on date time are computed based on the UTC time if timeoffset is not specified. For example: for facet=lastRenovationDate,interval:day, the day boundary starts at 00:00:00 UTC.

Fields

The following table shows all available fields and for what parameters they can be used

Field name Data type filter orderby select Description
id int/string Yes(string) Yes Yes The id of the media item asset. Is considered a string when used in a filter
vaultId int Yes Yes Yes The id of the vault where the asset resides.
name string Yes Yes Yes The name of the asset. Normally the filename of the asset if not changed.
modified date Yes Yes Yes The date when the asset where modified the last time
modifiedBy string Yes Yes Yes The username of the user that modified the asset the last time
versionId int Yes Yes Yes The id of the version that is the current version of the asset.
isOrganized boolean Yes Yes Yes True if the asset is organized and ready to use
isShared boolean Yes Yes Yes (2) True if the asset is Shared
isPublished boolean Yes Yes Yes (3) True if the asset is published
contentType string Yes Yes Yes The content type of the original asset.
aspectRatio double Yes Yes Yes Aspect ratio (w/h) of the asset. 1 is a square, <1 is a portrait, >1 is a landscape. Added in 5.14
conversions AssetConversion[] No No Yes the indexed conversions of the asset
conversions/formatId int Yes No Yes The format of a conversion
conversions/mediaInformation* string No No Yes (1) Underlying storage for map1 fields
conversions/contentType string No No 1 The contentType of the conversion
conversions/url string No No 1 The url of the conversion
conversions/html string No No 1 Suggested html to use for displaying the conversion in a web browser
conversions/width int No No 1 The width of the converted asset
conversions/height int No No 1 The height of the converted asset
metadata AssetMetadata[] No No Yes the metadata of the asset
metadata/definitionId int Yes No Yes The id of the metadata definition
metadata/value string Yes No Yes The string value of a specific metadata. If the metadata is not a string, this column contains the string representation of the value
metadata/booleanValue boolean Yes No Yes The boolean value of a specific metadata
metadata/dateValue date Yes No Yes The date value of a specific metadata
metadata/doubleValue double Yes No Yes The double value of a specific metadata
metadata/integerValue int Yes No Yes The integer value of a specific metadata
metadata/language string Yes No Yes The language of the metadata value
symbols AssetSymbol[] No No Yes,2,3,4 The different symbols associated with the asset.
access VaultRoles No No Yes The access level that the user has for the asset.
canBeDownloaded boolean Yes Yes Yes If the asset can be downloaded or not
agreementId int[] Yes No Yes (4) The different agreements that the asset is linked to
categories AssetCategory[] No No Yes,5,6 The categories an asset belongs to
category* string[] Yes No Yes (5) The name of a category
categoryId* int[] Yes No Yes (6) The id of a category

\* indicates a field that is not visible on the asset but is extracted to other properties. Check the select column to see what other fields it controls

Examples

Only include organized data

Should be applied to all queries

$filter=isOrganized

Filter on vault, one, multiple (any)

Filter all organized assets from vault with id 1

$filter=isOrganized and vaultId eq 1

Filter all organized assets from vaults with id 1,5 and 7

$filter=isOrganized and (vaultId eq 1 or vaultId eq 5 or vaultId eq 7)

Filter on categories, one, multiple (any/all)

Filter all assets that belongs to category id 3

$filter=categoryId/any(c: c eq 3)

Filter all assets that belongs to category id 3 or 4

$filter=categoryId/any(c: c eq 3 or c eq 4)

Filter all assets that belongs to category id 3 AND 4

$filter=categoryId/any(c: c eq 3) and categoryId/any(c: c eq 4)

Filter all assets that don't belong to any categories

$filter=not categoryId/any()

Filter on contentType, one, multiple (any), groups (image/video/?)

Filter a specific contentType

$filter=contentType eq 'image/jpeg'

Filter all images (contentType contains image/)

$filter=search.ismatch('image/','contentType')

Filter all video (contentType contains video/)

$filter=search.ismatch('video/','contentType')

Filter on modifiedBy

See contentType

Filter on specific metadata

Filter where metadata with definitionId 1 equals 'jpg'

$filter=metadata/any(m: m/definitionId eq 1 and m/value eq 'jpg')

Filter on specific metadata (range)

Filter where metadata with definitionId 2 and integerValue is greater than 1000000 ( filesize > 1Mb)

$filter=metadata/any(m: m/definitionId eq 2 and m/integerValue gt 10000000)

Filter square/portrait/landscape

New in 5.14 Only select landscape assets

$filter=aspectRatio gt 1

Only select portrait assets

$filter=aspectRatio lt 1

Only select square assets

$filter=aspectRatio eq 1

Search by name

Search by any metadata

Search by specific metadata (string,integer,double,date,bool)

Search by specific metadata range of values (integer,double,date)

Search by text, single word, phrase (string)

Search by text, multiple words, and and or

Facets (category,agreement,vault)

Request facets on categoryId, top 5

$facet=categoryId,count:5

Request facets on agreementId and vaultId

$facet=agreementId&$facet=vaultId

Response

The response document follows the syntax below

@odata.count

Is set if you specify $count=true and will contain the approximate number of assets that matches the query.

@search.facets

If you request facets, these are contained as named properties in the @search.facets property where each entry contains of an array of facet values. Each facet value contains two properties; value and count.

value

Contains an array of all matched assets (MediaItem)

Example

{
  "@odata.count": 8,
  "@search.facets":{
      "categoryId": [
        {
            "value": 41,
            "count": 26962
        },
        {
            "value": 143,
            "count": 24856
        },
        {
            "value": 84,
            "count": 10447
        },
        {
            "value": 161,
            "count": 8433
        },
        {
            "value": 144,
            "count": 8413
        }
      ]
  },
  "value": [
    {
      "id": 1,
      "vaultId": 1,
      "name": "img074.jpg",
      "modifiedBy": "epiadmin",
      "modified": "2018-09-18T10:56:42.88Z",
      "versionId": 1,
      "isShared": true,
      "isPublished": true,
      "conversions": [
        {
          "formatId": 1,
          "contentType": "image/jpeg",
          "url": "/media/exyoh0d3994rhaijbdjt/img074.jpg",
          "html": "<img src=\"/media/exyoh0d3994rhaijbdjt/img074.jpg\" width=\"3528\" height=\"2340\" alt=\"\" />"
        },
        {
          "formatId": 2,
          "contentType": "image/jpeg",
          "url": "/media/r97veook8eqsu3c7lo0x/img074.jpg",
          "html": "<img src=\"/media/r97veook8eqsu3c7lo0x/img074.jpg\" width=\"120\" height=\"80\" alt=\"\" />"
        },
        {
          "formatId": 3,
          "contentType": "image/jpeg",
          "url": "/media/14vjm0ewwryrxlb8j0fj/img074.jpg",
          "html": "<img src=\"/media/14vjm0ewwryrxlb8j0fj/img074.jpg\" width=\"240\" height=\"159\" alt=\"\" />"
        },
        {
          "formatId": 4,
          "contentType": "image/jpeg",
          "url": "/media/fyjdjeusrqpg32hwoxio/img074.jpg",
          "html": "<img src=\"/media/fyjdjeusrqpg32hwoxio/img074.jpg\" width=\"340\" height=\"226\" alt=\"\" />"
        }
      ],
      "metadata": [
        {
          "definitionId": 1,
          "value": "jpg"
        },
        {
          "definitionId": 2,
          "value": "1322725",
          "integerValue": 1322725
        },
        {
          "definitionId": 3,
          "value": "3528",
          "integerValue": 3528
        },
        {
          "definitionId": 4,
          "value": "2340",
          "integerValue": 2340
        }
      ],
      "categories": [
          {
              "id": 1332,
              "name": "Flowers"
          },
          {
              "id": 1333,
              "name": "Bees"
          }
      ]
    }
  ]
}