\nThe result can be narrowed by the same filters as Navigator Pro uses, given as the filters object\nof the payload next to the queries. Each value may be a single value or an array of values.\n
\nA filter value is always a technical key, never a display name. A display name is not rejected, it simply\nmatches no product. These filters are supported:\n
\nFeatures are defined within a class, so a FEATURE_... or properties filter is only applied\nonce a class is known - either from metaclass or recognized within the query text. Without a class\nit is silently ignored.\n
\nFor compatibility with the Navigator Pro vocabulary, all of these are alternatively accepted as\nfilters[<name>][] parameters of the query string, which then take precedence.\n
\nBy default, a query which matches more products than limit is treated as a miss and the next\nquery of the cascade is tried instead - so that a query which is too broad to be useful does not\nreturn an arbitrary excerpt of it. Setting truncate to true disables this: the query is\naccepted as a match, total reports the real number of matches, and only the first limit\nproducts are returned.\n
\nSetting includeFacets to true adds a facets object to a matched result.\n
\nfacets.filters lists the brands, product series, ETIM classes and product groups within the result.\nThe code of an entry is the filter name to pass it back as, and the value of a choice is\nthe filter value - so a facet can be applied without translating anything. A facet is omitted if no\nproduct of the result carries a value for it, and it is capped at the 25 most frequent choices. Its\ntotalChoices reports how many distinct values the result actually holds, so a value above the\nnumber of choices means the listed ones are only the most frequent, not the complete set. Note that\na facet whose filter is already applied only reports the selected value, as the result is narrowed to it.\n
\nfacets.features and facets.properties are only filled once a concrete class is known (either\nfrom metaclass or recognized within the query text - an ETIM group alone carries no features);\nwithout one they are emitted as empty arrays. facets.features lists the ETIM features of that class\nwhich are relevant as a filter, each either as type: \"bool\" or \"choice\" with a\nchoices array of value/label/count, or as type: \"range\" with a\nmin/max (always the external, human-facing value regardless of request locale) and an\noptional unit. facets.properties lists the boolean ETIM properties of the class with a\ncount each - the code of an entry is the value to put into the properties filter.\n
\nEvery hit carries the datasheetUrl of its product datasheet in the requested portal, so it does not\nhave to be assembled from the item and supplier number. The field is absent - rather than empty - for a\nportal which has deep links disabled, and it addresses the product by its normalized item number, which is\nwhy it need not match itemNumber character by character.\n", "parameters" : [ { "name" : "accessToken", "in" : "query", "required" : true, "description" : "Access token for non-public portals. When submitting a user or roles, the respective values need to be considered during the computation of the token. See kba:INT63 for details.", "schema" : { "type" : "string" }, "example" : "d0765f518ff0cab426dbbd6d467c9967" }, { "name" : "portal", "in" : "query", "required" : true, "description" : "Globally unique alpha-numeric code as set up or automatically assigned. Also visible in the respective URL on the Portals page.", "schema" : { "type" : "string" }, "example" : "9999999" }, { "name" : "user", "in" : "query", "required" : true, "description" : "User name", "schema" : { "type" : "string" }, "example" : "john.doe" }, { "name" : "filterCountry", "in" : "query", "required" : false, "description" : "The country to filter by. Provide a two-letter ISO code. Note that internationalisation is a paid feature that needs to be purchased and enabled separately.", "schema" : { "type" : "string" }, "example" : "de" }, { "name" : "filterLanguage", "in" : "query", "required" : false, "description" : "The language to filter by in case of multi language portals. Provide a two-letter ISO code. Note that internationalisation is a paid feature that needs to be purchased and enabled separately.", "schema" : { "type" : "string" }, "example" : "de" }, { "name" : "language", "in" : "query", "required" : false, "description" : "Language to use for human-readable data. Does not affect content where applicable. Provide a two-letter ISO code.", "schema" : { "type" : "string" }, "example" : "de" }, { "name" : "roles", "in" : "query", "required" : false, "description" : "Comma-separated list of roles assigned to the user. Can be omitted if roles are not in use, or if the portal is public.", "schema" : { "type" : "string" }, "example" : "Heating,Electronics,Top-Customer" } ], "requestBody" : { "description" : "Providing multiple query texts and the filters to narrow the result", "required" : false, "content" : { "application/json" : { "examples" : { "example1" : { "value" : { "limit" : 10, "queries" : [ "ST.001.A", "00012345600012", "ST Sanitär Halbeinbauwaschtisch weiß mit Tisch schwarz", "ST Sanitär Waschtisch weiß" ], "filters" : { "brand" : "86AFJJLLCIDDA7AE169EFJP3M4", "metaclass" : "metaclass|EG000001>metaclass|EC000123", "FEATURE_EF002336" : [ "EV022510", "EV022511" ], "FEATURE_EF025889-min" : 10 }, "truncate" : false, "includeFacets" : false } } } } } }, "responses" : { "200" : { "description" : "Result on query match", "content" : { "application/json" : { "examples" : { "example1" : { "value" : { "success" : true, "error" : false, "matchedQuery" : 0, "total" : 1, "products" : [ { "itemNumber" : "ST.001.A", "supplierNumber" : "1351", "gtin" : "00012345600012", "model" : "ST 001 A", "previewImageUrl" : "https://oxomi.com/dasd/cv/attachments/.../product-image-preview/....jpg", "datasheetUrl" : "https://oxomi.com/p/9999999/datasheet/1351/st.001.a", "brand" : { "id" : "ABC123", "name" : "ST Sanitär", "mediumImageUrl" : "https://oxomi.com/dasd/cv/tenants/.../tenant-medium/....jpg" }, "series" : { "id" : "XYZ123", "code" : "ST-CeramX", "name" : "ST-CeramX", "mediumImageUrl" : "https://oxomi.com/dasd/p/series/.../.../....jpg" }, "shortText" : "Halbeinbauwaschtisch weiß mit Tisch schwarz", "descriptionText" : "Ein Halbeinbauwaschtisch von ST Sanitär aus der Serie ST-CeramX. Erhältlich in weiß mit schwarzem Tisch.", "marketingText" : "Der Halbeinbauwaschtisch ST.001.A von ST Sanitär aus der Serie ST-CeramX überzeugt durch sein modernes Design und die hochwertige Verarbeitung." } ], "facets" : { "filters" : [ { "code" : "brand", "label" : "Marke", "totalChoices" : 1, "choices" : [ { "value" : "ABC123", "label" : "ST Sanitär", "count" : 1 } ] }, { "code" : "metaclass", "label" : "Produktgruppe", "totalChoices" : 1, "choices" : [ { "value" : "metaclass|EC000123", "label" : "Waschtisch", "count" : 1 } ] } ], "features" : [ { "code" : "FEATURE_EF002336", "label" : "Farbe", "type" : "choice", "choices" : [ { "value" : "EV000123", "label" : "weiß", "count" : 1 } ] }, { "code" : "FEATURE_EF025889", "label" : "Breite", "type" : "range", "min" : 45.0, "max" : 100.0, "unit" : "cm" } ], "properties" : [ { "code" : "FEATURE_EF099999", "label" : "Unterbaufähig", "count" : 1 } ] } } } } } } }, "400" : { "description" : "Missing parameter or malformed request", "content" : { "application/json" : { "examples" : { "example1" : { "value" : { "success" : false, "error" : true, "message" : "The parameter {missingParameter} must be filled." } } } } } }, "401" : { "description" : "Authentication required but none provided", "content" : { "application/json" : { } } }, "403" : { "description" : "Invalid authentication or missing permission", "content" : { "application/json" : { } } }, "404" : { "description" : "Resource not found", "content" : { "application/json" : { } } }, "405" : { "description" : "Incorrect request method, e.g. GET instead of POST", "content" : { "application/json" : { } } }, "500" : { "description" : "Unexpected server-side error", "content" : { "application/json" : { } } } } } } } }