integration_documentation:request
This is an old revision of the document!
Request to FINDOLOGIC
In this article the request to FINDOLOGIC with all important parameters and information regarding the request is documented.
If any questions occur, please contact our technical support support@findologic.com.
Short overview
- The FINDOLOGIC search service is only available after the first succeeded import.
- Queries are sent to FINDOLOGIC by means of HTTP requests.
- Before each actual query, a so-called Alivetest must be performed.
- The Alivetest returns either
alive
ordead
. Ifdead
is the case, a fallback mechanism must take effect, and the conventional shop search must process the query.
Fallback mechanism
- Before each query, an Alivetest HTTP request is sent to FINDOLOGIC according to the following pattern:
http://service.findologic.com/ps/<SHOP_URL>/alivetest.php?shopkey=<SHOPKEY>
.
- In the case of a response from
alive
, the actual query is sent to the FINDOLOGIC service. - With all other responses other than
alive
, the query is processed by the conventional shop search.
If the fallback mechanism is not working properly, the FINDOLOGIC search may not be used in a productive shop. - Also, a timeout of 1 second must be set for the Alivetest. If the response time exceeds 1 second, the query is processed by the conventional shop search.
- A timeout of 3 seconds must be set for the actual query. If the response time exceeds 3 seconds, the query is processed by the conventional shop search.
Basic structure of the request
The request is composed of the following components:
-
shopkey
shopurl
userip
referer
revision
-
query
attrib[]
order
properties[]
-
count
first
identifier
group[]
Service-URL
The FINDOLOGIC search service must be addressed under the service URL.
You can find the URL in the customer account → Account → Master data. Or by clicking
here.
The request parameters in detail
Required parameters
Parameter | Brief description |
---|---|
shopkey | Identification number of the requesting shop, consisting of 32 hex digits (1-9/A-F). The shopkey can be found in the customer account → Account → Master data. |
shopurl | Absolute URL of the requesting shop (e.g. shop.de or sub.shop.de). |
userip | IP address of the searching user. This data is used for billing and for the user identifier. The data remains under lock and key! |
referer | The referer URL of the searching user. To track the search history. These data remain under lock and key! |
revision | Version of the shop plugin. It is used to identify the version of the plugin. |
Search parameter
Parameter | Brief description |
---|---|
query | The searched query parameter. |
attrib[<name>][]1) | List of discrete attributes to be applied 2) Filter |
attrib[<name>][min] | Minimum value of a constant attribute3) |
attrib[<name>][max] | Minimum value of a constant attribute. |
order | Sorting of the results see below. |
properties[] | Name of the additional optional export columns, whose contents are to be output (only relevant for XML output). |
Values of the ''order'' parameter
No value can be set as a default.
Value | Description | Frontend response |
---|---|---|
<empty> 4) | Relevance calculated by FINDOLOGIC | Best hits |
price ASC | Most inexpensive products first | Most inexpensive first |
label ASC | Alphabetic sorting | A-Z |
salesfrequency DESC | Sales rank / most-sold items | Top sellers first |
dateadded DESC | Newest products | New products first |
Limiting / paging parameters
Parameter | Brief description | Default value |
---|---|---|
count | Number of items to be displayed (page size - max. 32767, higher values will get set to this) | 10 |
first | First item to be displayed on the page, 0-based (NOT page number, but rather the index of the item, the page with the 1st item starts with 0, the page with the 2nd with 1, first=count indicates the second page; the page number is thus equal to first/count+1 ). | 0 |
identifier | ID of an item, only this item is returned (query is ignored) | null |
group[]5) | Customer groups to be searched 6) | empty list |
Applying filters
Filters of the query output are performed using the attrib
parameter.
The name and value of the filter are case-sensitive.
Category filter
As a rule, the cat
key is used for categories.
attrib[cat][]=Men
Hierarchical categories
Hierarchies are interlinked by means of underscores (“_”) in accordance with the shop hierarchy.
attrib[cat][]=Men_Trousers
Vendor filter
As a rule, the vendor
key is used for categories.
attrib[vendor][]=FINDOLOGIC
Price filter
The price range is limited by min
and max
values.
attrib[price][min]=10.5&attrib[price][max]=200.0
Attribute filter
If the color
attribute is stored for shop items, a color
filter can be applied as follows.
attrib[color][]=red
Multiple values of one filter type
Multiple values are (currently) “AND-ed” exclusively. This means that only those products are output that meet satisfy all filters in the event of multiple values for one filter type.
attrib[color][]=red&attrib[color][]=blue
In the above example, only those products are output that are red and blue.
Generating the request URL
All parameters keys and their values must be submitted UTF-8 and URL encoded.
attrib[Färbung][]=grün => attrib[F%C3%A4rbung][]=gr%C3%BCn
To build the request URL, use existing functions if possible. The request is automatically correctly coded with these. In PHP for example, the function is http_build_query:
$parameters = array( 'shopkey' => 'ABCDABCDABCDABCDABCDABCDABCDABCD', 'attrib' => array( 'cat' => array( 'Cars' ), ... ), ); $requestUrl = 'http://service.findologic.com/ps/my-shop.com/index.php?' . http_build_query($parameters);
Examples
The following are examples of queries:
Search | Request |
---|---|
“green car” | <Service-URL>?query=green%20car |
“green car”, “new items first” | <Service-URL>?query=green%20car&order=dateadded+DESC |
“green car”, page 2 (with 24 items per page) | <Service-URL>?query=green%20car&first=24 |
“green car”, limited by the “Cars” category | <Service-URL>?query=green%20car&attrib[cat][]=Cars |
“green car”, all items of the “Cars” category in green colour | <Service-URL>?query=green%20car&attrib[cat][]=Cars&attrib[Colour][]=green |
“t-shirt”, limited to those that are available in the colour red and blue | <Service-URL>?query=t-shirt&attrib[Colour][]=red&attrib[Colour][]=blue |
rank
value can also be given or the order
parameter completely omitted