shopping24 documentation

s is for shopping

Widget productsForUri

At the productsForUri endpoint you can request a list of products that match the content of a given web page.

GET /v3/:appid/widget/:widgetid/productsForUri?uri=:uri

For this endpoint to work, the domains of your web pages for which you are searching related products must be added to a whitelist in our system, otherwise we will not fetch the content of the web pages. Please contact us for details.

Parameters

Basic parameters

uri: Encoded URI to fetch the content from. The contents of the web page will be fetched by our servers. For the fetch to work, the web page must be reachable from the internet and the server must return the web page with a “200 OK” response status. Note that we currently do not follow redirects. We also do not execute any JavaScript, so the content must be included in the returned response.

minElements: The minimum number of products to return. If the number of products returned would be lower than this number of products, an empty response will be returned instead. Note: it is invalid to provide a minElements value that is greater than pageElements because pageElements is the maximum number of products that is returned.

Pagination parameters

Response of widget returns a paginated result. In order to customize a paged response just add the parameters listed below.

page: page index. Per default the page index is set to 1.

pageElements: number of elements returned on one page. The number of page elements is limited by the server side (max. number of page elements = 1000) per default the number of page elements is set to 40.

Response

The API returns a JSON response with the following fields:

field type description
results number The total number of products found for the web page. Note that this is not necessarily the number of products returned in this response, which is never larger than the number of pageElements requested.
mediaBase string The base URL for image resources.
links list of related links A list of related link objects. This element is optional.
products list of products The list of products (see below for details).

Products

A product element in the response has the following structure:

field type description
id string The product ID.
title string The title of the product.
brand object The brand of the product. This element is optonal.
brand.name string The brand name.
shop object The shop that offers the product.
shop.name string The name of the shop.
costs object Information about the price (see below for details).
clickoutLink string The URL to which the user should be linked for a clickout.
clickoutTrackingLink string A tracking URL which should be fetched when the user performs a clickout.
images list of strings A list of image IDs with product images.

Price Information

The costs element of a product contains price information with the following structure:

field type description
currency string The three-letter ISO currency code of the price, e.g. “EUR”.
priceInCents number The current price of the product in the smallest unit of its currency (cents).
oldPriceInCents number If the price of the product was recently reduced, this element contains the previous price of the product. This element is optional.
shippingInCents number The shipping costs of the product.
priceFrom boolean If the priceInCents is the lowest price at which the product is sold but it is also available at higher prices (for example, different package sizes), you may be required to display this to the user (e.g., “from 4.99€”). In that case, priceFrom is true. This element is optional (but it is always included if true).
referencePrice object If the product is a product where it is legally required to show a reference price per some base unit (e.g., the price per kilogram), this object contains the required information. This element is only included for products where a reference price must be shown.
referencePrice.priceInCents number The reference price.
referencePrice.portion number The amount of units for which the reference price was calculated.
referencePrice.unit string The unit of the reference price.

Constructing image URLs

Image URLs can be constructed from the mediaBase URL in the response and the image IDs. The pattern is:

{mediaBase}/{width}x{height}/{id}

For example, if the mediaBase is https://example.com, you want to retrieve the image in a size of 300x200 pixels, and the image ID is 123abc, the image URL is https://example.com/300x200/123abc. The image will be resized to the size that you requested. The aspect ratio of the image will be preserved by adding a white border if necessary.

Note: you should always treat the image ID as an opaque string. Many of our image IDs are numeric, but some contain alphanumeric characters and we might change the format of the IDs in the future.

Example

In this example, we request products that are relevant for the text of the article found at http://example.com/article?id=12345.

GET /v3/example/widget/123/productsForUri?uri=http%3A//example.com/article%3Fid%3D12345&pageElements=1

    {
        "results": 42,
        "mediaBase": "https://images.s24.com",
        "links": [
            {
                "href": "https://tracking.s24.com/...",
                "rel": "tracking"
            }
        ],
        "products": [
            {
                "id": "123",
                "title": "Example product",
                "brand": {
                    "name": "Example brand"
                },
                "shop": {
                    "name": "Example shop"
                },
                "costs": {
                    "currency": "EUR",
                    "priceInCents": 999,
                    "oldPriceInCents": 1299,
                    "shippingInCents": 499,
                    "priceFrom": true,
                    "referencePrice": {
                        "priceInCents": 1200,
                        "portion": 100,
                        "unit": "ml"
                    }
                },
                "clickoutLink": "https://tracking.s24.com/...",
                "clickoutTrackingLink": "https://tracking.s24.com/...",
                "images": [
                    "101112"
                ]
            }
        ]
    }