Technical Documentation

Content

• Purpose
• Getting Started
• Introduction
• XML Data Feed Ad Example
• Import Types
• Feed Fields
• Frequently Asked Questions
• Kleinanzeigen Category Tree

Purpose

The purpose of this document is to assist Kleinanzeigen Advertising Partners during the Technical Onboarding phase and post technical onboarding. It serves as a guide in feed set-up and management.

Getting Started

This guide provides you with a step-by-step guide on how to get started with your technical onboarding process. It includes information on setting up your feed, accessing essential resource reference, and getting acquainted with our Retail Media Advertising platform.

Introduction

Dear Valued Customer,

Congratulations on choosing Kleinanzeigen. We are thrilled to partner with you and assist you in showcasing your products to our extensive network of users. Our commitment to your success starts right here with this comprehensive onboarding guide.

As you embark on this exciting journey with us, we want to make your transition as smooth and efficient as possible. This guide is designed to walk you through the process of importing your product feeds into our Ad Server, so you can get your ads up and running quickly. Here's what you need to know:

1. XML Feed: In the past, creating an XML feed was a customer responsibility. However, to streamline the process and ensure accuracy, our dedicated Technical Account Manager will now handle the creation of the XML feed for you. Details on how to proceed with this option are provided in the guide.

2. TSV (Tab-Separated Values) Feed: If you prefer, you can utilize TSV format to import your product feeds. This option offers flexibility and simplicity, and this guide includes step-by-step instructions to get you started.

3. API Connection (Beta Phase): For those interested in cutting-edge solutions, we are excited to offer an API connection. This option is currently in Beta testing phase, and we invite you to be part of this innovative integration. Please note that as this is a Beta feature, you'll have direct support from our technical team to ensure a seamless experience. Our Customer Success team is always here to support you, and we encourage you to reach out with any questions or concerns. Your success is our success, and we are committed to providing you with the tools, resources, and personalized support you need to thrive on our platform.

XML Data Feed Ad Example

<?xml version="1.0" encoding="UTF-8"?>
<ads xmlns:admarkt="http://admarkt.marktplaats.nl/schemas/1.0">
    <ad>
        <vendorId>42</vendorId>
        <title>Bally 1992 Adams Family</title>
        <description>Best pinball machine ever made</description>
        <categoryId>999</categoryId>
        <url>https://pinball.com/game/bally-adams-family/</url>
        <vanityUrl>https://pinball.com</vanityUrl>
        <price>875000</price>
        <originalPrice>875000</originalPrice>
        <priceType>FIXED_PRICE</priceType>
        <phoneNumber>16123456789</phoneNumber>
        <emailAdvertiser>true</emailAdvertiser>
        <sellerName>Pinball King</sellerName>
        <status>ACTIVE</status>
        <media>
            <image url="https://pinball.com/game/bally-adams-family/1.jpg"/>
        </media>
        <budget>
            <totalBudget>10000</totalBudget>
            <dailyBudget>1000</dailyBudget>
            <autobid>true</autobid>
        </budget>
        <shippingOptions>
            <shippingOption>
                <shippingType>PICKUP</shippingType>
                <location>1097DN</location>
            </shippingOption>
            <shippingOption>
                <shippingType>PICKUP</shippingType>
                <location>1055AB</location>
            </shippingOption>
            <shippingOption>
                <shippingType>SHIP</shippingType>
                <cost>695</cost>
                <time>2d-5d;</time>
            </shippingOption>
            <shippingOption>
                <shippingType>SHIP</shippingType>
                <cost>1195</cost>
                <time>1d-2d</time>
            </shippingOption>
        </shippingOptions>
        <attributes>
            <attribute>
                <attributeName>model</attributeName>
                <attributeValue>Adams Family</attributeValue>
            </attribute>
            <attribute>
                <attributeName>multiball</attributeName>
                <attributeValue>TRUE</attributeValue>
            </attribute>
            <attribute>
                <attributeName>screen size</attributeName>
                <attributeValue>32"</attributeValue>
            </attribute>
            <attribute>
                <attributeName>resolutions</attributeName>
                <attributeValue>1024x768:24dpi</attributeValue>
                <attributeValue>800x600:18dpi</attributeValue>
            </attribute>
        </attributes>
        <gtin>93845278905</gtin>
        <productType>Hobby &amp; Games &gt; Arcade Games &gt; Pinball Machines</productType>
        <googleProductCategory>Electronics &gt; Arcade Equipment &gt; Pinball Machines</googleProductCategory>
        <brand>Bally</brand>
        <condition>refurbished</condition>
        <energyEfficiencyClass>E</energyEfficiencyClass>
        <minEnergyEfficiencyClass>F</minEnergyEfficiencyClass>
        <maxEnergyEfficiencyClass>D</maxEnergyEfficiencyClass>
        <color>black/white/green</color>
        <gender>unisex</gender>
        <ageGroup>adult</ageGroup>
        <itemGroupId>BC23456</itemGroupId>
    </ad>
</ads>

Import Types

• XML : See below examples
• TSV: Download sample file here
• API: TBD

Feed Fields

A set of required and optional fields defined by a feed for XML file formats are listed below.

XML

vendor Id

The vendor id field is the unique identifier of the ad. It is there to let us know, for consecutive imports, which ads are the same. This results is allowing us to track and update an existing ad with the same vendor id instead of creating a new ad. vendor id is mandatory and, unique for each ad in the feed.

        <vendorId>15839942</vendorId>

Restrictions: Any non-empty string with a maximum length of 64 characters.

title

Use the title title field to clearly identify the product you are selling. The title is one of the most prominent parts of your ad or free listing. A specific and accurate title will help us show your product to the right customer.

        <title>Goedkope A-merk herenfietsen</title>

Restrictions: Any string, with minimum and maximum length determined by the category, with a maximum cap of 120 characters. See Categories. URLs are not allowed as part of the title.

description

Use the description field to tell customers about the details of the product you are selling.

<description>
<![CDATA[
    <p><strong><u>De goedkoopste webshop</u></strong>
        <strong>voor tweedehands fietsen met garantie!
        Gratis en rijklaar thuisbezorgd!</strong>
    </p>
    <p><strong><br></strong>
    </p>
    <ul>
        <li><strong>Laagste prijsgarantie</strong></li>
        <li>Fietsen <strong>100% rijklaar</strong>
        gratis thuisbezorgd</li>
        <li><strong>Ruime voorraad</strong>, voor ieder wat wils</li>
        <li>Snelle <strong>customer service</strong>
        via Whatsapp, bellen en e-mail</li>
        <li>1 <strong>maand garantie</strong></li>
        <li>Aangesloten bij <strong>Webwinkelkeur</strong></li>
    </ul>
    <strong><br></strong>
    <p>Check dus snel onze website en vind de fiets die bij je past!<br>
    </p>
    <strong><br></strong>
    <p>WhatsApp, bel of mail ons voor verdere vragen.
    </p>
]]>
</description>
 

Restrictions: Any string, with minimum and maximum length determined by the category. See Categories. URLs are not allowed as part of the description. All HTML elements except for the ones below will be removed:

<u> <em> <ul> <li> <p> <strong> <br>

category id

Use category id to place your product in the Categories tree.

Each product belongs to one and only one category.

<categoryId>945</categoryId>

Restrictions: An integer value from the category list. Must be an id of a leaf category with a non-zero parent id.

status

Use status to change the state of your ad.

Must be one of the following:

The provided (desired) status may differ from the resulting one, depending on the other conditions. For instance, budget may be depleted, or you may have too many active ads already in the category.

Url

Utilize the url to establish a connection to your product page from the advertisement. This represents an external URL, which will be displayed on the ad detail page or search result page.

<url>https://www.bmw.de</url>

Restrictions: Must be a valid http(s) url.

vanityUrl

Use vanity url to provide the text for the url link

<vanityUrl>BMW</vanityUrl>

Price type

Use price type to define pricing model for your product.

<priceType>FIXED_PRICE</priceType>

<priceType>NOT_APPLICABLE</priceType>

Allowed Values: FIXED_PRICED, NOT_APPLICABLE. The Value NOT_APPLICABLE is used for products that do not specify price (example in Job category)

price

Use price to tell customers the price of the product you are selling. The meaning of the value depends on the price type. Price should be in cent. In the example below, the price value is 15 EUR.

<price>1500</price>

Restrictions: The maximum allowed price value is 10000000000 given in cents of the local market currency. (100.000.000,00 EUR / CAD / … )

Images

You can provide multiple images for your product.

All images will be resized if necessary to a size of maximum 1024px height and 1024px width (preserving the aspect ratio) The system will download the images and, if they meet the requirements, store them on our servers in several sizes.

Use <media> tag for grouping your product images. <media> should contain from 0 to N <image> ordered elements, where the exact limit depends on the category in taxonomy. <image> elements must contain a complete URL link pointing to an image on a publicly available web server.

<media>
    <image url="https://images.pexels.com/photos/62289/62289.jpeg"/>
    <image url="https://images.pexels.com/photos/47547/47547.jpeg"/>
</media>

The images will be presented in the provided order. The first image is shown in search results and acts as the main image on the item page.

Allowed image formats: JPEG, JPG, PNG, GIF*, BMP.

*Please note that GIFs are not recommended format as they are only 256 colors or less. Also, animated GIFs and PNGs are not supported.

Attributes

Use attributes field to provide additional information on your product in a structured way.

attributes tag contains collection of product User-Defined Attributes (category-dependent), that can be used to influence the ad relevance.

<attributes>
    <attribute>
        <attributeName>color</attributeName>
        <attributeLocale>nl</attributeLocale>
        <attributeLabel>Kleur</attributeLabel>
        <attributeValue>Rood</attributeValue>
    </attribute>
    <attribute>
        <attributeName>color</attributeName>
        <attributeLocale>en</attributeLocale>
        <attributeLabel>Color</attributeLabel>
        <attributeValue>Red</attributeValue>
    </attribute>
    <attribute>
        <attributeName>Model</attributeName>
        <attributeValue>Slim</attributeValue>
        <attributeValue>Pro</attributeValue>
    </attribute>
</attributes>

attributes tag contains collection of product User-Defined Attributes (category-dependent), that can be used to influence the ad relevance.

shipping & pick-up

Provide the information on how your product can be delivered to customers.

You can provide multiple shipping/ pick-up options for each product. Each option can be described with the following information:

SHIP means the item can be delivered to the buyer in the provided time and for the provided cost. For shippingType ‘SHIP’ provide ‘cost’ in cents and ‘time’ in days. ‘location’ is ignored.

PICKUP means the item can be picked up at the provided location For shippingType ‘PICKUP’ provide ‘location’. Both ‘cost’ and ‘time’ are ignored.

<shippingOptions>
    <shippingOption>
        <shippingType>PICKUP</shippingType>
        <location>1097DN</location>
    </shippingOption>
</shippingOptions>

Restrictions: Shipping options can be disabled/optional/mandatory for an ad. It is configured per category, see Category Configuration.

MPN

Manufacturer Part Number (MPN), definition follows Google Merchant Center guidelines.

<mpn>AB12345R89TN6E</mpn>

Restrictions: String identifier max 70 characters long.

google product category

Use this field to describe your product category in Google’s product taxonomy. See Google Merchant Center

<googleProductCategory>
    Apparel &amp; Accessories &gt; Clothing &gt; Dresses
</googleProductCategory>

<googleProductCategory>2271</googleProductCategory>

Restrictions: Should be a valid category. You can provide it, either with identifier, or giving full category path.

brand

Use the brand field to help customers identify your product. Brand definition follows Google Merchant Center guidelines.

<brand>iPhone</brand>

Restrictions: Do not exceed 70 characters limit for your text.

product type

The product type field provides an opportunity for you to incorporate your unique product classification system into the dataset. Definition follows Google Merchant Center guidelines.

<productType>
    Home &gt; Women &gt; Dresses &gt; Maxi Dresses
</productType>

Restrictions: Do not exceed 70 characters limit for your text.

GTIN

GTIN (Your product’s Global Trade Item Number), definition follows Google Merchant Center guidelines.

<gtin>44320194113475</gtin>

Restrictions: String identifier max 50 chars.

item group id

Use this field to group product variants in your product data. Item group id definition follows Google Merchant Center guidelines.

<itemGroupId>BC23456</itemGroupId>

Restrictions: Text max. length 50 characters.

condition

Use this field to inform customers about the condition of your product. Condition definition follows Google Merchant Center guidelines.

<condition>used</condition>

Accepted values: new, refurbished, used

material

Material field describes the main fabric or material that your product is made of. Material definition follows Google Merchant Center guidelines.

    <material>Cotton/Silk</material>

Restrictions: Use human readable material names. Provide up to 3 materials. Separate materials with a slash (“/”) character when there are multiple. Do not exceed 200 characters limit for your text.

energy efficiency class

Use this field to tell customers how your product rates on a given energy efficiency range. See Google Merchant Center

Allowed values: A+++, A++, A+, A++, B, C, B, E, F, G

min energy efficiency class

Used in combination with max energy efficiency class to describe the product energy efficiency label. Possible values defined in energy efficiency class

<energyEfficiencyClass>A+</energyEfficiencyClass>

max energy efficiency class

Used in combination with min energy efficiency class to describe the product energy efficiency label. Possible values defined in energy efficiency class

<minEnergyEfficiencyClass>G</minEnergyEfficiencyClass>

color

Use color field to tell customers about the dominant colors of your product. Color definition follows Google Merchant Center guidelines.

<color>Black/Grey</color>

Restrictions: Use human readable color names. Provide up to 3 colors. Separate colors with / if more than one. Do not exceed 100 characters limit for your text.

gender

Use gender field to describe the gender your product is designed for. Gender definition follows Google Merchant Center guidelines.

<gender>unisex</gender>

age group

Use age group field to describe the age group your product is targeted at. Definition follows Google Merchant Center guidelines.

<ageGroup>adult</ageGroup>

Allowed values: newborn, infant, toddler, kids, adult

size

Use size field to describe standardized size of your product. Size definition follows Google Merchant Center guidelines.

<unitPricingBaseMeasure>1kg</unitPricingBaseMeasure>

Restrictions: String identifier max 1-100 chars.

unit pricing base measure

The denominator for product unit price. See Google Merchant Center. This field attribute tells the customer how the price of your product translates per unit.

<unitPricingBaseMeasure>unitPricingBaseMeasure>1kg</unitPricingBaseMeasure>

Restrictions: Value should be an integer number with unit.

Supported unit values:

• Weight: oz, lb, mg, g, kg

• Volume: floz, pt, qt, gal, ml, cl, l, cbm

• Length: in, ft, yd, cm, m

• Area: sqft, sqm

• Per unit: ct

unit pricing measure

Defines the measure and dimension of the product. That value helps the customers to understand the exact price per unit for your product. Example 125ml, 100g. See Google Merchant Center.

<unitPricingMeasure>15kg</unitPricingMeasure>

Restrictions: Value should be an integer number with a unit.

Supported unit values:

• Weight: oz, lb, mg, g, kg

• Volume: floz, pt, qt, gal, ml, cl, l, cbm

• Length: in, ft, yd, cm, m

• Area: sqft, sqm

• Per unit: ct

Frequently Asked Questions

Below are some common scenarios and questions with their explanations/answers.

<attributes>
  <attribute>
    <attributeName>shipment_cost_visible</attributeName>
    <attributeLabel>Versandkosten anzeigen</attributeLabel>
    <attributeLocale>de_DE</attributeLocale>
    <attributeValue>true</attributeValue>
  </attribute>
  <attribute>
    <attributeName>shipment_cost_desc</attributeName>
    <attributeLabel>Versandkosten</attributeLabel>
    <attributeLocale>de_DE</attributeLocale>
    <attributeValue>Versandkostenfrei</attributeValue>
  </attribute>
</attributes>

Feed Debugging and Validation

All data feeds must be validated before importing to the EBK platform. The command line script below can be used in any terminal to identify errors.

When an error is reached, the script will terminate and output the error to the console.

When the file passes the validation process, the script will output to the console:

fileName.xml validates

Validation Script:

xmllint --nonet --nowarning --noout --encode "UTF-8" --dropdtd --noent fileName.xml --schema Admarkt.xsd

Replace filename.xml with your XML file name.

Kleinanzeigen Category Tree