Breadcrumbs

Offer search - Request


Endpoint: /search/offers

Authentication

See JWT details

Meta

The meta information on fields guide the usage of the API. On each field, the service provide

  • which action can be done on the field: sort, filter or provide a facet

  • the distribution: either discrete (like codeEan) or continuous (like price). Depending on the distribution, the filter should be handled differently. See filter the result.

  • information if

    • the field is optional or not.

    • the service can provide statistics or not.

Parameter

Type

Domain

Default

Description

Example

fieldsMeta

string

fields list or 'all'


List of fields that will have meta information. Use 'all' to get all metas.

fieldsMeta=price,rebatePercentage

  • See exhaustive and accurate field list with meta information

  • See examples

  • See possible error messages

Fields

Choose which offer fields will be returned.

Parameter

Type

Domain

Default

Description

Example

fieldsAlias

string

{'none','minimal','all'}

'minimal'

Pre defined list of fields. If not defined, the most useful fields will be provided: the fields behind the alias 'minimal'.

fieldsAlias=minimal

additionalFields

string

fields list


List of fields that should be returned in addition to the fields selected by fieldsAlias. The field names are expected in camelCase. See all the field names. If a field is requested but not available for the offer, the null value will be used.

additionalFields=brandId,featureType

Tip: use the fieldsAlias minimal and add only the extra fields you need with additionalFields. It's not recommended to use fieldsAlias all unless you really need all fields: taking only the fields you need will speed up the process on our side and yours as well.

  • See examples

  • See possible error messages

Result

Pagination of the result.

Parameter

Type

Domain

Default

Description

Example

pageSize

int

1 <= pageSize < 100

20

Number of offers per page

pageSize=20

page

int

page >= 1 and pageSize * page <= 500

1

Number of page to request. The first page is 1.

page=20

Note: the limit of 500 can be increased by requesting this from your Kelkoo account contact. However, if a large number of offers are required, this may be an indicator that you should consider using offer feeds.

  • See examples

  • See possible error messages

Sort

Sort the result on a specific field. Check in the meta which field can be sorted.

Parameter

Type

Domain

Default

Description

Example

sortBy

string

{'totalPrice', 'price', ...} : check the value canSort in the meta or facet object

not defined

Field to applied the sort. If not defined, the sort is done on the relevancy on query.

sortBy=price

sortDirection

string

{'asc', 'desc'}

'desc'

Sort direction

sortDirection=desc

  • See examples

  • See possible error messages

Top Offers

Return the top most performant offers.

Parameter

Type

Domain

Default

Description

Example

topOffers

int

1 <= topOffers < 500

None

Returns at most topOffers offers sorted according to their performance score in descending order (1)

topOffers=10

(1) : this feature is conflicting with and cannot be used at the same time as sort and pagination. Moreover, as topOffers overrides offers relevancy relative to the query, use of query parameter should be avoided when requesting top offers.

  • See usage and examples

Facets

A facet is linked to a field of the offer. With the facet values, the client will be able to filter the result of the initial query.

Check in the meta which field can provide a facet.

Parameter

Type

Domain

Default

Description

Example

facets

string

fields list or 'all'


List of facets that should be built. Use 'all' to get all facets on chosen fields.

facets=merchantId,price,featureType

facetValues

int

1 <= facetValues

10

Number of facet values returned. There is no max value, so if you need all possible values, provide here the max number of values your UI can handle.

facetValues=15

facetValuesOn=[field]:

string

1 <= facetValuesOn=[field]


Override the facetValues attribute for a specific field. (1)

facetValuesOn=featureColor:12

(1): facetValuesOn=[field]: can be applied on several fields if needed, for instance: facetValuesOn=featureColor:12&facetValuesOn=featureType:20

  • See usage and examples

  • See possible error messages

Facets on discrete distribution

On discrete distribution (for instance merchantId, categoryId, featureColor... ), we can put the offers in buckets corresponding to the different values of the field.

How it's working ? See details

Facets on continuous distribution

On continuous distribution (for instance price, rebatePercentage... ), we can put the offers in dynamic buckets according to the field value, and the result set.

How it's working ? See details

Filters

Filter the offers returned.

How it's working ? See details

Custom parameters

Name

Type

Domain

Description

custom1

string

Up to 511 characters (1)

Larger parameter, it can handle a url for example

custom2

string

Up to 127 characters (1)

Smaller parameter, it can handle an id or a keyword for example

custom3

string

Up to 127 characters (1)

Smaller parameter, it can handle an id or a keyword for example

(1) Please adhere to these maximums if you want to be confident in meaningful reporting as anything larger will be truncated.

Read details on custom parameters

See possible error messages

Publisher parameters

Name

Type

Domain

Description

publisherClickId

string

Up to 127 characters (1)

publisherClickID s are a way to track your leads in the Publisher at the finest granularity.

publisherSubId

string

Up to 127 characters (1)

It's for aggregation purpose, specific for affiliate networks who want to have visibility at subId granularity. Ideally one distinct publisherSubId per publisherSubname.

publisherSubName

string

Up to 127 characters (1)

It's for aggregation purpose, specific for affiliate networks who want to have visibility at subId granularity.

publisherTrafficType

string

Up to 127 characters (1)

To classify subID by their type. See table below

originReferer

string

Up to 511 characters (1)

Depending on the way the offer is published, the http header referer might not contain the information on where the click was actually initiated. Add, when it is known, the actual domain name on which the offer is actually published.

(1) Please adhere to these maximums if you want to be confident in meaningful reporting as anything larger will be truncated.

publisherTrafficType values

Value

Description

affiliation

Affiliate Platforms/Networks

bnpl

Buy Now Pay Later

browserui

Browser UI

browserextension

Browser Extension

cashback

Cashback

classified

Classified

content

Content

coupons

Coupons/Incentives

displaynative

Native Platforms

domain

Domain Parking

emailmarketing

Email Marketing

influencer

Influencer Platform

internal

Kelkoo Group Internal

mediabuyer

Media Buyer

other

Other

pcw

Price Comparison Website

placss

PLA CSS

programmaticplatforms

Programmatic Platforms

publishernetwork

Subnetwork

retargeting

Retargeting

searchengine

Search engine

socialmedia

Social Media

toolbar

Toolbar

Endpoints

See Request builder

Example

Request is represented in the response

  • Given  the input parameters are

name

value

query

nike air

queryMatchStrength

all

filterBy

codeEan:53255452354 25234

filterBy

categoryId:100564913

filterGreaterThan

price:100

filterLowerThan

price:1000

filterGreaterThan

rebatePercentage:20

fieldsAlias

minimal

additionalFields

categoryName,flagOffensiveContent,codeSku,merchantLogoUrl

fieldsMeta

brandId,price

sortBy

price

sortDirection

asc

pageSize

30

page

2

facets

brandId,merchantId,totalPrice

facetValues

15

facetValuesOn

merchantId:12

custom1

http%3A%2F%2Fwww.publisher.com%2FblackFriday.html

custom2

blackFriday

custom3

3594673925797

  • When  the client perform a GET on /api/search/offers with the input parameters

JSON
{
  "request": {
    "country": "fr",
    "query": {
      "keyword": "nike air",
      "matchStrength": "all"
    },
    "filterBy": [
      {
        "filterKey": "codeEan",
        "values": [
          {
            "value": "53255452354"
          },
          {
            "value": "25234"
          }
        ],
        "warnings": []
      },
      {
        "filterKey": "categoryId",
        "values": [
          {
            "value": "100564913"
          }
        ],
        "warnings": []
      }
    ],
    "filterGreaterThan": [
      {
        "filterKey": "price",
        "value": "100",
        "warnings": []
      },
      {
        "filterKey": "rebatePercentage",
        "value": "20",
        "warnings": []
      }
    ],
    "filterGreaterThanEqual": [],
    "filterLowerThan": [
      {
        "filterKey": "price",
        "value": "1000",
        "warnings": []
      }
    ],
    "filterLowerThanEqual": [],
    "filterValueExists": [],
    "fields": {
      "alias": "minimal",
      "additional": [
        "categoryName",
        "flagOffensiveContent",
        "codeSku",
        "merchantLogoUrl"
      ],
      "meta": [
        "brandId",
        "price"
      ]
    },
    "sort": {
      "field": "price",
      "direction": "asc"
    },
    "pagination": {
      "page": 2,
      "pageSize": 30
    },
    "facets": [
      {
        "field": "brandId",
        "values": 15
      },
      {
        "field": "merchantId",
        "values": 12
      },
      {
        "field": "totalPrice",
        "values": 15
      }
    ],
    "custom": {
      "param1": "http://www.publisher.com/blackFriday.html",
      "param2": "blackFriday",
      "param3": "3594673925797"
    }
  },
  "offers": [
    "..."
  ],
  "meta": [
    "..."
  ]
}