integration_documentation:request

integration_documentation:request

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 or dead. If dead 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:


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] Maximum 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).
outputAttrib[] Name of the attributes which may be available in the template (only relevant for Direct Integration).
pushAttrib[<key>][<value>] Name and value of the filter which should be pushed.


Values of the ''order'' parameter

The values dynamic and ASC/DESC can be added to every value listed below, f.e.: salesfrequency dynamic DESC.

The values ASC/DESC are specifying whether to sort the results ascending (ASC) or descending (DESC).

The value dynamic is calculating the specified value in a dynamic way and does not sort the results hard. This means that the textual relevance is still influencing the sorting.

We strongly advise our customers to use a dynamic calculation for the default order.

Value Description
salesfrequency Sort by sales rank / most-sold items.
shopsort Sort by the values, that are exported via the feed in the field //sort//.
price Sort by price.
label Alphabetic sorting.
dateadded Sort by date.
<empty> or rank Sort by default order, that was specified (If the default order is empty, the sort order will be textual relevance only).


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[]4) Customer groups to be searched 5) 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.


Push attributes

It is also possible to push products within the request.

The pushing is done with the help of the attributes and is performed by using the pushAttrib parameter.

Pushing attributes can be used for a personalized search.
pushAttrib[color][red]=3

There can be more than one attribute pushed.

pushAttrib[color][blue]=0.5&pushAttrib[gender][woman]=1.5

More on this topic can be found in the manual for our personalization.


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
Use existing functions in order to avoid errors!

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
1)
The array brackets [] must always be included after the attribute name.
2)
Discrete attributes can, as opposed to constant attributes, only take on certain values. E.g. Size=XL,L,M,…
3)
constant attributes can, as opposed to discrete attributes, take on any numerical values. E.g. price
4)
For XML export, the parameter must be “usergrouphash”; note the following: Calculating the usergroup hash
5)
Can be given multiple times; Only those items are displayed that are assigned to at least one of these customer groups; Groups that do not exist in the export are ignored.