Offer search - Model | Kelkoo documentation

Offer model

The offer model is the same for :

Offer feeds
Offer search

Offer fields

Type:

primitive: integer, float, boolean, string
date: with the ISO-8601 compliant format (format String "yyyy-MM-dd'T'HH:mm:ss'Z'"). For instance: "2020-05-20T15:35:01Z"

Name: each field name is given with the camelCase format. For instance: offerId, lastUpdateDate, merchantId, image0Url, featureColor... This name will be used in the Offer Search to select fields, filter fields, get facets from fields and in Offer Feeds to select fields.

Format: depending on the format the field is not named the same way to respect the standard naming of the given format

On json, we use the camelCase. So the field offerId is named offerId.
On xml, we use the PascalCase. So the field offerId is named OfferId.
On csv, we use the snake_case. So the field offerId is named offer_id.

Access: to use the fields in filter, a facet, or in the fields' selection, the usage is the following :

on the root of the offer, use the field name. For instance: totalPrice, rebatePercentage.
on an internal structure also camelCase format is used. For instance: brandId for the id attribute of the brand structure.

Meta: on offer search, use the parameter fieldsMeta to dynamically know which action can be done on each field

sort
filter
facet

Here is the exhaustive list of fields with their properties:

Offer static fields

The static field doesn't depend on the category the offer is attached.

Meta data on all public static fields

Given the input parameters are

name	value
fieldsMeta	all

When the client perform a GET on /api/public/search/offers with the input parameters
Then the static fields meta data are

name	type	distribution	value	possible actions	description
`offerId`	string	discrete	provided	filter	Offer id
`lastUpdateDate`	date	continuous	provided		Last update date of the offer. Format with an example: '2020-05-20T15:35:01Z'
`title`	string	discrete	provided		Offer title
`description`	string	discrete	optional		Offer description
`country`	string	discrete	provided		Country. 2 characters in lowercase
`price`	float	continuous	provided	facet, sort, filter, statistics	Price payed by the client. For example: 20.00
`priceWithoutRebate`	float	continuous	optional		Original price before the rebate is applied. For example: 40.00
`monthPrice`	float	continuous	optional		Price per month payed by the client (if buy with downpayment plan). For example: 40.00
`rebatePercentage`	int	continuous	optional	facet, filter, statistics	Rebate percentage applied on the priceWithoutRebate. For example: 50 means 50%
`rebateEndDate`	date	continuous	optional		End date of the rebate. Format with an example: '2020-05-20T15:35:01Z'
`deliveryCost`	float	continuous	optional	filter, statistics	Delivery cost of the offer. For example: 8.00
`priceDiscountText`	string	discrete	optional		Promotional text. For instance 'Free delivery in France'
`totalPrice`	float	continuous	provided	facet, sort, filter, statistics	Total price is price+deliveryCost. For example: 28.00
`currency`	string	discrete	optional		Price currency. 3 characters in uppercase
`availabilityStatus`	string	discrete	optional		Availability status: {'in_stock', 'stock_on_order', 'check_site', 'pre_order', 'available_on_order', 'not_in_stock', 'out_of_stock'}
`timeToDeliver`	string	discrete	optional		Time to deliver
`condition`	string	discrete	optional	facet, filter	Condition of the article: {'unknown', 'new', 'refurbished', 'used', 'download', 'offer_for_professional', 'preregistered'}
`warranty`	string	discrete	optional		Free text to display warranty information (deprecated)
`greenLabel`	string	discrete	optional		Green label. Available if flagGreenProduct
`ethicalType`	string	discrete	optional	facet, filter, statistics	Ethical type. {'Environmental Friendly','Recycled material','Refilable Product','Handmade','Organic'...}
`flagOffensiveContent`	boolean	discrete	optional		Is offensive content
`flagGreenProduct`	boolean	discrete	optional	facet, filter	Is a green product
`flagSaleEvent`	boolean	discrete	optional		Indicates if the offer is part of a promotional sales event.
`codeEan`	string	discrete	optional	filter, statistics	Code EAN
`codeMpn`	string	discrete	optional		Code MPN
`codeSku`	string	discrete	optional		Code SKU
`codeGtin`	string	discrete	optional	filter	Code GTIN
`goUrl`	string	discrete	provided		URL to be used by the publisher to monetize the offer.
`permanentUrl	string	discrete	optional		Permanent URL to be used by the publisher to monetize the offer.
`estimatedCpc`	string	continuous	optional		Estimated revenue the publisher can earn for a lead on the offer for a desktop device.
`estimatedMobileCpc`	string	continuous	optional		Estimated revenue the publisher can earn for a lead on the offer for a mobile device.
`brandId`	string	discrete	optional	facet, filter, statistics	Brand id
`brandName`	string	discrete	optional	filter	Brand name
`merchantId`	string	discrete	provided	facet, filter, statistics	Merchant id
`merchantName`	string	discrete	optional		Merchant name
`merchantLogoUrl`	string	discrete	optional		Url of the logo of the merchant
`websiteId`	string	discrete	optional	facet, filter	A unique ID for each merchant domain. Has a 1:n relationship with merchantId
`merchantProvidedCategory`	string	discrete	optional		Offer category defined by the merchant
`categoryId`	string	discrete	provided	facet, filter, statistics	Category id
`categoryName`	string	discrete	optional		Category name
`googleProductCategoryId`	string	discrete	optional
`googleProductCategoryName`	string	discrete	optional
`offerUrlLandingUrl`	string	discrete	optional		Offer url on the merchant site
`offerUrlMobileLandingUrl`	string	discrete	optional		Offer url on the merchant mobile site through a tracker
`offerUrlMobileTrackedUrl`	string	discrete	optional		Offer url on the merchant site
`offerUrlTrackedUrl`	string	discrete	provided		Offer url on the merchant mobile site through a tracker
`imageUrl`	string	discrete	optional		Url of the main image, standard size
`imageZoomUrl`	string	discrete	optional		Url of the main image, large size
`image2Url`	string	discrete	optional		Alternative images. Only 2 images has be put here.
`image2ZoomUrl`	string	discrete	optional		The number of images depends on the offer itself. They are stored in an array so the offer can provide more than 2 images.
`ecotax`	float	continuous	optional		Ecological taxation
`madeIn`	string	discrete	optional	facet, filter, statistics	Location where the product has been made
`efficiencyClass`	string	discrete	optional
`performanceScore`	float	discrete	optional	sort	Performance score
`productId`	string	discrete	optional	filter	Product id
`productPopularity`	long	discrete	optional		Product rank
`sellerName`	string	discrete	optional		Seller name

Notes :

The possible actions define above are available on Search Offer only, the Offer feeds do not propose those actions.

Offer dynamic fields

All fields under the features section depends on the category the offer is attached. To get the metadata on for those features on a specific category, you should use

filterBy=categoryId:<my category id>
fieldsMeta=all

Meta data with all features fields when the category is provided

Given the input parameters are

name	value
fieldsMeta	all
filterBy	categoryId:4000

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

Then I get a response with status 200

And the json response contains meta/fields with the following keys

key
featureFashionGender
featureFashionType
featureMaterial
featureColor

See details

Example

JSON

{
  "offers": [
    {
      "offerId": "7701b65469b409bcba9272e6be514c6d",
      "title": "PUMA Chaussure de course Flyer Runner, Noir, Taille 48.5, Chaussures",
      "lastUpdateDate": "2019-02-25T00:00:00Z",
      "description": "PUMA Chaussure de course Flyer Runner",
      "country": "fr",
      "price": 250,
      "priceWithoutRebate": 500,
      "monthPrice": 10,
      "rebatePercentage": 50,
      "deliveryCost": 50,
      "priceDiscountText": "Promo!",
      "totalPrice": 300,
      "currency": "€",
      "availabilityStatus": "available_on_order",
      "timeToDeliver": "3 days",
      "condition": "new",
      "greenLabel": "green",
      "ethicalType": "Recycled materials",
      "flag": {
        "offensiveContent": true,
        "greenProduct": true,
        "saleEvent": false
      },
      "code": {
        "ean": "ean1",
        "sku": "sku123",
        "mpn": "mpn123",
        "gtin": "00000123456789"
      },
      "images": [
        {
          "url": "http://r.kelkoo.com/resize.php?country=fr&merchantId=777&categoryId=4000&trackingId=1234&width=90&height=90&image=http%3A%2F%2Fwww.lequipe.fr%2Fgoaaaaal.jpg&sign=wvoKAr14OhTXzXNUUSROYX_X954vCV5cgavzuaMcXtg-",
          "zoomUrl": "http://r.kelkoo.com/resize.php?country=fr&merchantId=777&categoryId=4000&trackingId=1234&width=auto&height=auto&image=http%3A%2F%2Fwww.lequipe.fr%2Fgoaaaaal.jpg&sign=wvoKAr14OhTXzXNUUSROYX_X954vCV5cgavzuaMcXtg-"
        },
        {
          "url": "http://r.kelkoo.com/resize.php?country=fr&merchantId=777&categoryId=4000&trackingId=1234&width=90&height=90&image=http%3A%2F%2Fwww.dateam.us%2Fbuuut.jpg&sign=IOEsIaY5laeLFTOiaY50Ptv3BmC6aTbHYc6L9_gNp5c-",
          "zoomUrl": "http://r.kelkoo.com/resize.php?country=fr&merchantId=777&categoryId=4000&trackingId=1234&width=auto&height=auto&image=http%3A%2F%2Fwww.dateam.us%2Fbuuut.jpg&sign=IOEsIaY5laeLFTOiaY50Ptv3BmC6aTbHYc6L9_gNp5c-"
        }
      ],
      "features": {
        "color": {
          "label": "Couleur",
          "values": []
        },
        "gender": {
          "label": "Genre",
          "values": [
            {
              "label": "Homme",
              "value": "homme"
            }
          ]
        },
        "material": {
          "label": "Matériaux",
          "values": [
            {
              "label": "Synthétique",
              "value": "synthetique"
            }
          ]
        },
        "type": {
          "values": []
        }
      },
      "offerUrl": {
        "landingUrl": "http://fc.barcelona.es/leo"
      },
      "goUrl": "https://fr-go.kelkoogroup.net/sitesearchGo?.ts=1546300800000&.sig=6dmeuQZKV39lhcz2sETDp40dt6I-&affiliationId=1234&comId=777&country=fr&offerId=7701b65469b409bcba9272e6be514c6d&searchId=1076992041209_1556144897286_189200&service=36&tokenId=tokenId1234",
      "estimatedCpc": 0.1,
      "estimatedMobileCpc": 0.1,
      "brand": {
        "id": 5,
        "name": "Brandy"
      },
      "merchant": {
        "id": 777,
        "name": "Lionel Messi",
        "logoUrl": "https://r6.kelkoo.com/data/merchantlogos/777/logo.jpg",
        "websiteId": 9777
      },
      "merchantProvidedCategory": "Chaussures à crampons",
      "category": {
        "id": 4000,
        "name": "Gestes techniques"
      },
      "googleProductCategory": {
        "id": 4444
      },
      "ecotax": 0.3,
      "madeIn": "China",
      "efficiencyClass": "A+++",
      "product": {
        "id": "123456abcd",
        "popularity": 89
      },
      "performanceScore": 0.666,
      "sellerName": "some seller"
    }
  ]
}