There is Swagger documentation available for this service
https://api.papirfly.app/search/swagger-ui/index.html
Swagger URL for SSO login (replace [com_id] with your company ID): https://api.papirfly.app/login?state=%2Fsearch%2Fswagger-ui%2Findex.html&p_com_id=[com_id]
Swagger URL for non-SSO login (replace [com_id] with your company ID twice):
https://api.papirfly.app/mars/external.access?p_url=%2Flogin%3Fstate%3D%252Fsearch%252Fswagger-ui%252Findex.html%26p_com_id%3D[com_id]&p_com_id=[com_id]
Search Service can be refered to as SOLR API as this name is used internally. As the name suggests the search is being made inside Apache Solr and it is used to quickly search for assets in our Place application (DAM solution).
Archive Structure
See overview to understand different IDs used in our system.
Every asset is saved in one archive (use "oty_id" and "ptl_id" for filtering). To get all available archives for company, use endpoint in DAM API.
Instead of folders we use categories which are organized in a tree structure. Categories can be defined on a company level (global) or on an archive level (local categories) - their trees are separated. Field "categoryId" contains both parent and child IDs of local categories. Field "globalCategoryId_ss" contains both parent and child IDs of global categories. To get list of categories, use endpoint in Category service.
Every asset can be assigned to light box and bussiness area which are defined on an archive level. You can get light boxes and business areas available for chosen archive from DAM API.
There is a specific structure of documents tied to the records inside Solr Index. The structure can be found in our Solr record documentation.
Filtering
Filtering in Solr lets you filter which documents you’ll get as a result of a search.
+ operator:
If you want to search for a document which must have a field equal to a certain value you can use +.
E.g.: +assetType:ASSET -> will return only documents where assetType is equal to ASSET.
- operator:
If you don’t want some field value to be included in the search you can use -.
E.g.: -assetType:ASSET -> will return documents where assetType is not equal to ASSET
AND operator
If you have multiple field values that you want to be included in the searched documents you can use AND. E.g.: assetType:ASSET AND qcl_id:1 -> will return documents with assetType equal to ASSET and qcl_id equal to 1
OR operator
If you want to search for multiple field values and you want either of them to be included you can use OR.
E.g: assetType:ASSET OR qcl_id:1 -> will return documents where assetType is equal to ASSET or where qcl_id is equal to 1
Nesting
If you want to search for multiple values of the same field, you can move the condition one level lower like this:
E.g.: assetType:(ASSET OR CREATIVE) AND qcl_id:1 -> will return documents with assetType equal to ASSET or CREATIVE and qcl_id equal to 1
Ranges
For time filters you can use [ * to * ] where you can specify what time period you want to be included in search results.
E.g:
origin_date: [2018 TO 2019] -> will return every document created from 2018 to 2019
origin_date [NOW-7DAYS TO NOW] - will return documents created within last week (7days)
origin_date [NOW-3MONTHS TO NOW] - will return documents created within last 3 months
origin_date [NOW-1YEAR TO NOW] - will return documents created within last year
{!frange l=1 u=1}div(oty_id, owner_oty_id) - will return documents connected in owner archive(avoid duplications if one asset is connected to two archives)
Point pages
If Point pages are marked as "Searchable" they can be found through search API with this filter:
assetType:BrandBook
There is no other public API for Point yet.
Number of documents
In the response json, there is a field “numFound” which coresponds to the number of documents found in the whole index for the current query and filter settings. So for example if you want to update number of document hits in SOLR dynamically as the user adds their filters, you can send requests with the wanted filters and queries and get the number of hits for the given filter.
Also if you only want the facet fields or the number of hits you can send a request with “start” and “rows” equal to zero. The SOLR won’t be occupied with processing the documents and will just return the number of hits or requested facet fields.
In normal query SOLR has its own defaults to the start and rows parameters equal to start=0 and rows=10.
Request
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND orientation:square",
"start": 0,
"rows": 0,
"facetFields": [
"orientation"
]
}
Response
{
...
"numFound": 83,
"documents": [],
"facet_fields": {
"orientation": {
"square": 83,
"": 0,
"landscape": 0,
"portrait": 0
}
}
...
}
Search with include filter parameters
In request object, there can be specified include filter parameters. We provide 3 include filter parameters:
- includeExpiredFilter (DEFAULT false) - result will include expired assets, if user has privilege for it.
- includeGdprPendingRejectedFilter (DEFAULT false) - result will include GDPR not complied assets(status PENDING, REJECTED), if user has privilege for it.
- includeDuplicatedFilter (DEFAULT true) - result will include duplicated assets.
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND orientation:square",
"start": 0,
"rows": 0,
"facetFields": [
"privacy_subjects_status_s"
],
"includeGdprPendingRejectedFilter ": true
}
Response (for user, that has privilege to see GDPR not complied assets)
{
...
"numFound": 83,
"documents": [],
"facet_fields": {
"privacy_subjects_status_s": {
"PENDING": 50,
"REJECTED": 23,
"CONFIRMED": 10
}
}
...
}
Response (for user, that has not privilege to see GDPR not complied assets)
{
...
"numFound": 10,
"documents": [],
"facet_fields": {
"privacy_subjects_status_s": {
"CONFIRMED": 10
}
}
...
}
Faceting
Faceting fields is a functionality that returns the number of hits in the solr index for a given field and its values.
Request
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND (*:* NOT oav_id:(\"2\" \"-4\")) AND qcl_id:1",
"start": 0,
"rows": 0,
"facetFields": [
"orientation"
]
}
Response
{
...
"facet_fields": {
"orientation": {
"landscape": 352,
"portrait": 123,
"": 98,
"square": 83
}
}
...
}
So you can see how many documents hits you will get for each value of the field “orientation”.
You can facet multiple fields at the same time. And the facets also respond to the actual filter and query you send in. You can use all available fields for faceting.
Faceting multiple fields
Request
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND (*:* NOT oav_id:(\"2\" \"-4\")) AND qcl_id:1",
"start": 0,
"rows": 0,
"facetFields": [
"orientation",
"assetType"
]
Response
{
...
"facet_fields": {
"orientation": {
"landscape": 352,
"portrait": 123,
"": 98,
"square": 83
},
"assetType": {
"ASSET": 549,
"CHILI_TEMPLATE": 81,
"LEGACY_ASSET": 26,
"ASSET_PAGE": 0,
"BrandBook": 0,
"CM_ACTIVITY": 0,
"CM_ACTIVITY_FINANCE": 0,
"CREATIVE": 0,
"LIGHTBOX": 0,
"MS_ARTICLE": 0,
"PUBLISHER_TEMPLATE": 0,
"TC": 0,
"TGP": 0,
"WYSIWYG_TEMPLATE": 0
}
}
...
}
Faceting multiple fields with minCount, limit parameter
Request
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND (*:* NOT oav_id:(\"2\" \"-4\")) AND qcl_id:1",
"start": 0,
"rows": 0,
"facetFields": [
"orientation",
"assetType"
],
"facetFieldsMinCount": 30,
"facetFieldsLimit": 200
}
Response
{
...
"facet_fields": {
"orientation": {
"portrait": 123
},
"assetType": {
"CHILI_TEMPLATE": 81
}
}
...
}
So as you can see, parameters facetFieldsMinCount and facetFieldsLimit are applied for whole result.
Faceting multiple fields defined by specifiedFacetFields array
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND (*:* NOT oav_id:(\"2\" \"-4\")) AND qcl_id:1",
"start": 0,
"rows": 0,
"specifiedFacetFields": [
{
"name": "orientation",
"minCount": 0,
"limit": 100
},
{
"name": "assetType",
"minCount": 30,
"limit": 500
}
]
}
Response
{
...
"facet_fields": {
"orientation": {
"": 98,
"square": 83
},
"assetType": {
"CHILI_TEMPLATE": 81
}
}
...
}
So as you can see, you can specify minCount and limit parameters for each facet field object defined in array.
Basic examples
Lists all approved documents which are not attachments and are stored as ASSET under specified local category
(from archive specified by portal ID (ptlId) and archive ID (otyId) in ptlOtyFilter array of objects)
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "assetType:ASSET AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND categoryId:<categoryId>",
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
Lists all approved images which are not attachments and are present in specified lightboxes
(from archive specified by portal ID (ptlId) and archive ID (otyId) in ptlOtyFilter array of objects)
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND array_lightboxes:<lightboxId>",
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
Lists approved images which are not attachments with "circle" in any field and which are stored under specified local category
(from archive specified by portal ID (ptlId) and archive ID (otyId) in ptlOtyFilter array of objects)
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "circle",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND categoryId:<categoryId>",
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
Lists approved images which are not attachments with "circle" in the title field and which are stored under specified local category
(from archive specified by portal ID (ptlId) and archive ID (otyId) in ptlOtyFilter array of objects)
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "title:circle",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND categoryId:<categoryId>",
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
Lists approved images which are not attachments with word "circle" OR word "straight" in the title field, with specified local category
(from archive specified by portal ID (ptlId) and archive ID (otyId) in ptlOtyFilter array of objects)
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "title:(circle OR straight)",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\")) AND categoryId:<categoryId>",
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
Lists approved images which are not attachments sorted by the created_date field
(from archive specified by portal ID (ptlId) and archive ID (otyId) in ptlOtyFilter array of objects)
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\"))",
"sort": ["created_date"],
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
You can use DESC for descending order or ASC for ascending order
POST https://api.papirfly.app/search/v3/?laeId=2
{
"query": "*:*",
"filterQuery": "viewer:HIGHSLIDE AND qcl_id:1 AND (*:* NOT oav_id:(\"2\" \"-4\"))",
"sort": ["created_date DESC"],
"ptlOtyFilter": [
{
"ptlId": 1234,
"otyId": 4321
}
]
}
Downloading original asset
Asset returned from the SOLR should contain field “original_ref” with relative link to the asset’s original image e.g:
/original/gallery/10930/files/original/7f1e5359af674d22adff468b5530db28.jpg
If you prepend the environment domain you get an absolute url e.g:
https://app.papirfly.com/original/gallery/10930/files/original/7f1e5359af674d22adff468b5530db28.jpg
Downloading thumbnail
Asset returned from the SOLR should contain field “thumbnail_ref” with relative link to the asset’s thumbnail e.g:
/fr/gallery/10930/images/thumbnail/dfbdaa4c587e4a088c788a9501d3426f.png
If you prepend the environment domain you get an absolute url e.g:
https://app.papirfly.com/fr/gallery/10930/images/thumbnail/dfbdaa4c587e4a088c788a9501d3426f.png
Asset Versioning
Only original image is versioned (no other attributes). Versions are available in search response in field array_history_ss. This field contains list of all history items. Every item contains relative URL to previous original version and timestamp of creation of this version in format “DDMMYYYYHH24MISS”.
Example of array_history_ss
"array_history_ss": [
"{\"original_ref\":\"/dloriginal/gallery/10930/files/original/52d32f8b-ddca-4aad-a093-9fc938196752.png_20112019000000?f=578211-gettyimages-542930526 (2).jpg\",\"time_stamp\":\"20112019000000\"}",
"{\"original_ref\":\"/dloriginal/gallery/10930/files/original/52d32f8b-ddca-4aad-a093-9fc938196752.png_31032020084612?f=image.png\",\"time_stamp\":\"31032020084612\"}"
]
Transcodings
Transcodings are versions of assets which we process after the asset is uploaded based on the settings set in the given Place archive. The transcodings can be fetched from DAM API and then you can search for them in solr in “array_files” field. Different transcodings are applied to different extensions. Example of a transcoding can be: Medium Square Thumbnail, Lowres version, First frame of a video.
The “array_files” field is an array of json objects where each object has its own “file_ref” field and size information about the given transcoding of the given asset, in “width” and “height” fields.
Example array_files
“array_files”:[
"{\"id\":\"21513138\", \"tgt_id\":\"\", \"spec_id\":\"1\", \"file_size\":\"6973\", \"fte_id\":\"1\", \"width\":\"1024\", \"height\":\"768\", \"name\":\"Original\", \"system\":\"N\", \"applies_to_ext\":\"*\", \"file_ref\":\"/original/gallery/10930/files/original/3b18e6203869440595bb650d40244986.jpg\"}",
"{\"id\":\"21513140\", \"tgt_id\":\"\", \"spec_id\":\"7\", \"file_size\":\"707564\", \"fte_id\":\"3\", \"width\":\"800\", \"height\":\"600\", \"name\":\"Lowresfile\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/lowres/4438766a774945f8b29ee334f14b090b.png\"}",
"{\"id\":\"21513158\", \"tgt_id\":\"\", \"spec_id\":\"8\", \"file_size\":\"499946\", \"fte_id\":\"5\", \"width\":\"1024\", \"height\":\"768\", \"name\":\"Cachefile\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/cache/9e63bb6a2a1443a5a7bf09aa37c4ea2d.jpg\"}",
"{\"id\":\"21513142\", \"tgt_id\":\"\", \"spec_id\":\"9\", \"file_size\":\"24004\", \"fte_id\":\"2\", \"width\":\"149\", \"height\":\"112\", \"name\":\"Thumbnailfile\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/thumbnail/c989d67935dc47aaa4923eacbf3e9b6f.png\"}",
"{\"id\":\"21513143\", \"tgt_id\":\"\", \"spec_id\":\"-402\", \"file_size\":\"61133\", \"fte_id\":\"21\", \"width\":\"200\", \"height\":\"200\", \"name\":\"Mediumsquaredthumb\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/medium_square/c41f515b274d443582ac95609e5c30a9.png\"}",
"{\"id\":\"21513146\", \"tgt_id\":\"\", \"spec_id\":\"-400\", \"file_size\":\"4446\", \"fte_id\":\"19\", \"width\":\"50\", \"height\":\"50\", \"name\":\"Smallsquaredthumb\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/small_square/9773b7defc754b7e9fd94f5611050721.png\"}",
"{\"id\":\"21513148\", \"tgt_id\":\"\", \"spec_id\":\"-401\", \"file_size\":\"263800\", \"fte_id\":\"20\", \"width\":\"420\", \"height\":\"420\", \"name\":\"Largesquaredthumb\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/large_square/3b6647a250884d0d869737e25bdf9572.png\"}",
"{\"id\":\"21513150\", \"tgt_id\":\"\", \"spec_id\":\"-405\", \"file_size\":\"216902\", \"fte_id\":\"24\", \"width\":\"420\", \"height\":\"420\", \"name\":\"Largesquaredpaddedthumb\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/large_padded/2cada88cd90f4bfeaddd78847262885b.png\"}",
"{\"id\":\"21513154\", \"tgt_id\":\"\", \"spec_id\":\"-403\", \"file_size\":\"3988\", \"fte_id\":\"22\", \"width\":\"50\", \"height\":\"50\", \"name\":\"Smallsquaredpaddedthumb\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/small_padded/29d9208342bd459c8c183ba2187a3ec5.png\"}",
"{\"id\":\"21513155\", \"tgt_id\":\"\", \"spec_id\":\"-404\", \"file_size\":\"48193\", \"fte_id\":\"23\", \"width\":\"200\", \"height\":\"200\", \"name\":\"Mediumsquaredpaddedthumb\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/medium_padded/2eaefb36b5a14c4c8e98dbe21e71bf7c.png\"}",
"{\"id\":\"21513163\", \"tgt_id\":\"\", \"spec_id\":\"1010\", \"file_size\":\"795223\", \"fte_id\":\"1015\", \"width\":\"1024\", \"height\":\"768\", \"name\":\"Lowresjpeg\", \"system\":\"N\", \"applies_to_ext\":\"jpg, png\", \"file_ref\":\"/fr/gallery/10930/files/others/c6d4559949f7405b828bcddaa37bedc4.jpg\"}",
"{\"id\":\"21513162\", \"tgt_id\":\"\", \"spec_id\":\"1009\", \"file_size\":\"795223\", \"fte_id\":\"1014\", \"width\":\"1024\", \"height\":\"768\", \"name\":\"HighresJpeg\", \"system\":\"N\", \"applies_to_ext\":\"jpg, tif, png, eps\", \"file_ref\":\"/fr/gallery/10930/files/others/24ae8227bce347ef9ba71e1026a961a9.jpg\"}",
"{\"id\":\"21513159\", \"tgt_id\":\"\", \"spec_id\":\"1012\", \"file_size\":\"707625\", \"fte_id\":\"4\", \"width\":\"800\", \"height\":\"600\", \"name\":\"PNGfile\", \"system\":\"Y\", \"applies_to_ext\":\"jpg, jpeg, tif, tiff, eps, png, bmp, ps, gif, psd, ai, svg, dpx\", \"file_ref\":\"/fr/gallery/10930/images/png/1a3937e4aa1b4732a261f4dc7ba829c3.png\"}"
]
Comments
0 comments
Please sign in to leave a comment.