Product list retrieval/product search
Abfrage per /products/search gefolgt von Key/Value-Paaren, die den Suchfilter beschreiben.
A call in the form of /products/search followed by key/value pairs describing the search filter:
- each key may only occur once
- the order of the key/value pairs does not matter
- key and value are separated by an equal sign (‘=’)
- key/value pairs are separated from each other using semicolons (‘;’)
- predefined keys must be used as other entries invalidate the URL
- for the values, HTML request invalid characters must be masked as follows: a space should be masked with the code %20, a hashtag (‘#’) with the code ‘%23’, a slash (‘/’) with the code ‘%2F’ etc.
- please note: if, despite masking, no products can be found, then the % character in the masked codes may need to be explicitly coded with a %25 again (double-coding). For example, %2F would then be coded as %252F
- up to 50 values can be specified for a key, separated by a comma (‘,’)
Search filter keys
- keywords: free search text
- do not replace spaces with +, instead use %20. For example, a search for the Lenovo Thinkpad I5 would be structured as Lenovo%20Thinkpad%20I5 and not Lenovo+Thinkpad+I5
- ean: a product EAN
- puid: ITscope ID
- plzid: source of supply number
- pid: internal ITscope ID
- cnetid: 1WorldSync product number (formerly known as CNET)
- hstpid: manufacturer number, SKU (should be used in combination with ‘manufacturer’ or with keywords to limit the manufacturer’s name)
- distpid: product number of the distributor
- id: is interpreted as one of the internal ITscope IDs, with fallback option on puid
- manufacturer (MAN): unique identifier of the manufacturer
- producttype (SET): unique identifier of the product category
- distributor (PRL): unique identifier of the supplier
- cluster (CLU): unique identifier of the property cluster
The resulting list can either be empty, contain exactly one product or contain up to 50 products.
Query parameter page
The ‘page’ query parameter allows the next 50 products to be requested for search results with >50 products.
For example, ‘page = 3’ would request products 101 to 150.
No information regarding how many products were found is provided in advance during the first request, meaning it is necessary to work with page = xx until there are no more products in order to reach the end of the list.
Query parameter item
The ‘item’ parameter allows you to retrieve the nth data set.
For example, if page = 2 and item = 3, this would retrieve the 3rd result from the 2nd page from a list of (e.g.) 90 products. As each page contains 50 results, this example would return the 53rd result from the list.
The item number can only be between 1 and 50, i.e. the item number does not depend on the parameter page.
Query Parameter plzproducts
You can use the ‘plzproducts’ query parameter to find and display price list lines. These products end with a ‘999’ on the ITscope online platform. This parameter is false by default, i.e. not set.
Query parameter realtime
With the ‘realtime’ query parameter, real-time calls are performed with the corresponding suppliers for all prices. Requirement for a real-time call is a successfully set up real-time eService with the respective suppliers.
Real-time price requests can only be used for product ID requests with the following keys: ean, puid, plzid, pid, cnetid, hstpid, distpid, id with a maximum of 10 total IDs to keep the load burden manageable, as these requests are forwarded directly to the supplier’s interface.
Real-time price calls can take up to 5 seconds, as they are forwarded directly to the supplier’s interface and the system waits up to 5 seconds for the supplier’s response. In other words, it is possible that no real-time price can be transmitted if the limit of 5 seconds is exceeded. In this case, the individual price list price or the standard price will be returned.
Query parameter sort
Product searches can be sorted according to specific criteria.
Here is a list of sorting criteria including an explanation:
- DEFAULT: descending by relevance. If there is no relevance, then IRANK is used
- PRICE_ASC: ascending price
- PRICE_DESC: descending price
- SOURCES_COUNT: descending by number of sources
- STOCK: descending according to stock level
- MANUFACTURER_SKU: descending according to manufacturer’s article number
- NAME_ASC: ascending by product name
- NAME_DESC: descending by product name
- QUAL: descending according to qualification of the product
- TOPSELLER: descending according to top product rank (number of clicks in the last 4 weeks)
- EXACT: descending according to exact productId hits
- IRANK: descending by popularity ranking, see ‘rank‘ field in format descriptions for products
Query parameter for filtering based on product entry date
These request parameters are only available starting with API 2.1. These parameters filter according to the entryDate export field for the product, see the relevant format descriptions for products for more information. The entry date indicates when the product was added to the ITscope catalogue and not when it was last modified. It is therefore not possible to use these parameters to search for recently modified products.
- productEntryFrom: the start date for the filtering of the product entry date period in the format yyyy-MM-dd. Only if this parameter is set will the products be filtered by the entry date period. The time is always 00:00:00.
- productEntryTo: the end date for the restriction of the product entry date period in the format yyyy-MM-dd. If no value is specified, the current date is taken as the default value. The time is always 00:00:00. The value cannot be less than productEntryFrom, i.e. the date cannot be before productEntryFrom.
Query parameters for historical data
Historical data and the corresponding request parameters are only available starting with API 2.1.
Examples – mass queries up to 50 items
Looking for a range of ITscope product IDs:
In this example, the following ITscope product IDs are searched: 3534638001, 2069677000, 2650828000, 4201083000. Up to 50 ITscope product IDs can be specified in a single request.
Search for a series of EANs:
This example looks for the following EANs: 5032037044288, 7636490025914, 8806086522977. Up to 50 EANs can be specified in a single request.
Looking for a number of manufacturer item numbers:
In this example, we are looking for the following manufacturer item numbers: 0553C001AA, N9J71AE#301, CLT-P406B/ELS. Up to 50 manufacturer item numbers can be specified in one request.
For example, the character ‘#’ as %23 -> %2523, or the character ‘/’ as %2F -> %252F
Examples – filter combinations
Looking for all products that match a manufacturer and their manufacturer item number:
e.g.: Samsung as the manufacturer (ID: 1015, this can be found via the manufacturer API call) and manufacturer item number MZ-75E250B/EU
https://api.itscope.com/2.1/products/search/hstpid=MZ-75E250B%252FEU;manufacturer=1015/standard.xml
Additionally, in this example with manufacturer item number ‘MZ-75E250B/EU’, the / sign was masked by ‘%2F’ as the ‘/’ sign has a special meaning in the URL and cannot be unmasked.
Searching all products that match a manufacturer’s item number:
https://api.itscope.com/2.1/products/search/hstpid=A7E34AA%2523ABB/standard.xml
Additionally, in this example with manufacturer item number ‘A7E34AA#ABB’, the ‘#’ character was masked using a ‘%23’ as the ‘#’ character has a special meaning in the URL and cannot be unmasked.
Searching for all products that fit a category, a manufacturer, and specific property clusters:
https://api.itscope.com/2.1/products/search/producttype=114;manufacturer=1032;cluster=2404144;cluster=1061/standard.xml
This example looks for products in the ‘disk’ category (producttype = 114), from Seagate (manufacturer ID = 1032), ‘size 2.5″‘ as the property cluster (cluster = 1061) and 4TB storage capacity (cluster = 2404144).
The ITscope IDs of the manufacturers can be retrieved via the manufacturer metadata API.
The ITscope IDs of the categories can be loaded via the categories metadata API.
The ITscope IDs of the property clusters can, with the appropriate authorisation, be retrieved via an export or product request. However, only property clusters that correspond to the products in the retrieval result are output. There is currently no way to get a complete list of property clusters via API.
Searching for all products that match a category, manufacturer, and specific entry date period:
https://api.itscope.com/2.1/products/search/producttype=114;manufacturer=1032/standard.xml?productEntryFrom=2019-11-01
This example looks for products in the ‘disk’ category (producttype = 114), from Seagate (manufacturer = 1032) and an entry date between 01.11.2019 and the current date of the request.
https://api.itscope.com/2.1/products/search/producttype=114;manufacturer=1032/standard.xml?productEntryFrom=2019-11-01&productEntryTo=2019-12-01
This example looks for products in the ‘disk’ category (producttype = 114), from Seagate (manufacturer = 1032), and an entry date between 01.11.2019T00:00:00 and 01.12.2019T00:00:00.
The ITscope IDs of the manufacturers can be retrieved via the manufacturer metadata API.
The ITscope IDs of the categories can be loaded via the categories metadata API.
Examples – free text search
Carrying out a free text search
https://api.itscope.com/2.1/products/search/keywords=lenovo%20thinkpad%20i5/standard.xml
The example above carries out a search for a Lenovo Thinkpad I5.
Combine a category search with a free text search
https://api.itscope.com/2.1/products/search/producttype=114;keywords=SATA-600/standard.xml
Combining filters provides the overlapping results of the individual filters. In the example above, hard-drives with SATA-600 interface are specified.