Table of Contents



Ad Stream is a push based interface that provides information about new and updated listings on the platform.

It eliminates the need to actively poll the rest interface in order to get the newest listings. As soon as a listing is created and it becomes visible on the platform the Ad Stream interface will send the notification to the connected clients.

The Ad Stream is an interface to allow the users getting information about the latest listings. It also could be used for synchronizing a copy of the inventory as it publishes events when listings are changed or deleted.

The interface uses the Web Socket protocol to send the events.

Endpoint and test environment

How to access the api.

Websocket endpoint url

The API is available at this url:


Please contact the Customer Support and refer to the Authentication and Authorization section in order to get access to the service.

Test Environment

Test environment is only available for API Users that are having an active live account.

The test endpoint is available at


It provides the same functionality as the live endpoint except the following:

  • the Delay is 60 seconds longer

  • it sends only 10% of all events

High Level Concepts

API User

An API user is an entity that has an API account and uses that account to connect to the interface. Please contact the Customer Support in order to set up the account and get the login credentials.


The ad represents a vehicle for sale that is published on the platform. It consists among the others of:

  • vehicle details

  • price

  • images


The seller represents information about the owner of the vehicle. It consists among the others of:

  • seller name

  • address

  • contact details

Ad Stream Event

Ad Stream event is a message published to the connected users. Events are triggered when a new listing is created, updated or deleted on the platform. The event payload contains full details about the relevant Ad and Seller.


The events are delivered to the client after a predefined delay. The actual delay depends on the contract. Please contact the Customer Support for more details.

Technical Overview

This section contains information how to use the Ad Stream from a technical perspective.

Web Socket

The interface uses the Web Socket protocol to send the events. Please refer to the following documents for more details

Once the connection is established the server starts publishing the events to the client. The connection is a long running communication channel and it could remain active for many days. Sometimes the connection gets terminated e.g. due to network problems or a new version of software installed on the site. The client must ensure that it has a mechanism to automatically establish a new connection in that case. Please refer to the Ensuring Consistency section to find out how to make sure that no messages are lost during the reconnecting process.

Authentication and Authorization

Access to the interface is only possible for the authenticated users. The user must be authenticated with a username and password using the HTTP basic authentication scheme. For detailed information on HTTP basic authentication please refer to:

During the activation process the Customer Support will set up an API User and provide you with instructions how to get the access credentials.


The amount of events can be limited by a predefined filter (only vehicles from private sellers). Please contact the Customer Support for filters activation and more details.

Multiple connections

The Adstream application is limited to one connection per user. Once the user tries to establish more concurrent connections the previous connections will be closed automatically. Because of the latency after reconnecting and closing connections, there is no advantage in terms of reliability or consistency.

Ensuring Consistency

The interface provides a mechanism to ensure that all events are delivered to a given user even though the user connection is not active for a while. When a connection is established, first the historical events are delivered starting at the point when the previous connection was terminated. The historical events are kept for 24 hours.

The consistency option is not enabled by default. In order to activate it please include the catchup=true query parameter in the url.


Please use the catchup=true option consistently across all active connections. Mixing the consistency option with regular connections at the same time will cause some unpredicted behavior of the interface.

Data Format

The events are delivered in the xml format that conforms to the schema.

Sample event
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<search:event xmlns:seller=""
    <ad:ad key="152229071" url="">
        <ad:creation-date value="2017-10-18T09:26:40+02:00"/>
        <ad:modification-date value="2017-10-18T09:26:42+02:00"/>
        <ad:detail-page url=""/>
        <ad:seller-inventory-key value="NFZ708645HND02"/>
            <ad:class key="Car" url=""/>
            <ad:category key="Van" url=""/>
            <ad:make key="MERCEDES-BENZ" url=""/>
            <ad:model key="Vito" url=""/>
            <ad:model-description value="Vito 116CDI L *Klima*Tempomat*Sitzheizung*PTS*"/>
            <ad:damage-and-unrepaired value="false"/>
                <ad:feature key="CENTRAL_LOCKING" url=""/>
                <ad:feature key="ELECTRIC_WINDOWS" url=""/>
                <ad:feature key="IMMOBILIZER" url=""/>
                <ad:feature key="POWER_ASSISTED_STEERING" url=""/>
                <ad:feature key="ABS" url=""/>
                <ad:feature key="ESP" url=""/>
                <ad:feature key="FULL_SERVICE_HISTORY" url=""/>
                <ad:feature key="CRUISE_CONTROL" url=""/>
                <ad:feature key="PARKING_SENSORS" url=""/>
                <ad:feature key="ELECTRIC_HEATED_SEATS" url=""/>
                <ad:feature key="PARTICULATE_FILTER_DIESEL" url=""/>
                <ad:feature key="HU_AU_NEU" url=""/>
                <ad:feature key="WARRANTY" url=""/>
                <ad:feature key="AUTOMATIC_RAIN_SENSOR" url=""/>
                <ad:feature key="BLUETOOTH" url=""/>
                <ad:feature key="ON_BOARD_COMPUTER" url=""/>
                <ad:feature key="HANDS_FREE_PHONE_SYSTEM" url=""/>
                <ad:feature key="MULTIFUNCTIONAL_WHEEL" url=""/>
                <ad:feature key="TUNER" url=""/>
                <ad:feature key="TRACTION_CONTROL_SYSTEM" url=""/>
                <ad:feature key="ROOF_RAILS" url=""/>
                <ad:exterior-color key="WHITE" url="">
                    <ad:manufacturer-color-name value="arktikweiß"/>
                <ad:mileage value="41562"/>
                <ad:door-count key="FOUR_OR_FIVE" url=""/>
                <ad:first-registration value="2016-03"/>
                <ad:emission-class key="EURO5" url=""/>
                <ad:emission-fuel-consumption envkv-compliant="false" co2-emission="163.0" inner="7.8" outer="5.2" combined="6.2" unit="LITER_PER_100_KM"/>
                <ad:emission-sticker key="EMISSIONSSTICKER_GREEN" url=""/>
                <ad:fuel key="DIESEL" url=""/>
                <ad:power value="120"/>
                <ad:kba hsn="1313" tsn="BQK"/>
                <ad:gearbox key="MANUAL_GEAR" url=""/>
                <ad:climatisation key="MANUAL_CLIMATISATION" url=""/>
                <ad:num-seats value="3"/>
                <ad:construction-date value="2016-02-11+01:00"/>
                <ad:cubic-capacity value="2143"/>
                <ad:condition key="USED" url=""/>
                <ad:interior-type key="FABRIC" url=""/>
                <ad:airbag key="FRONT_AIRBAGS" url=""/>
                <ad:countryVersion key="DE" url=""/>
                    <ad:parking-assistant key="FRONT_SENSORS" url=""/>
                    <ad:parking-assistant key="REAR_SENSORS" url=""/>
        <ad:description>- Klimaanlage TEMPMATIC, TEMPOMAT, Aktiver Park-Assistent, Radio Audio 10 ( Bluetooth, USB, AUX &amp; SD-Karte ), Multifunktionslenkrad mit Reiserechner, Lederlenkrad und Lederschalthebel, Komfort-Fahrersitz, Sitzheizung für Fahrer, Airbag Fahrer, Beifahrersitz Zweisitzer, Airbag Beifahrer, Stoff Tunja schwarz, 6-Gang-Schaltgetriebe TSG 380, Komfort-Öffnung u.Schließung mit IR-Fernbedienung, Fahrlichtassistent, Aufmerksamkeits-Assistent ATTENTION ASSIST, Berganfahrhilfe, Regensensor, Reifenluftdrucküberwachung an VA u. HA, drahtlos, Dachreling, Trennwand durchgehend mit 1 Fenster, Holzfußboden, Lastenverankerungsschienensystem, Innenverkleidung Laderaum bis Dachhöhe, LED-Lichtband im Laderaum, Hecktüren, zweiflügelig, Öffnung bis Seitenwand, Adaptives Bremslicht, Elektrik für Anhängersteckdose, Fahrzeug schadstoffarm Euro 5b+ Gr. III, Zulassung als LKW, Motor OM 651 DE 22 LA 120 kW (163 PS) 3800/min, Paket EASY CARGO, Inland - Code - - - Zubehörangaben ohne Gewähr, Änderungen, Zwischenverkauf und Irrtümer vorbehalten.</ad:description>
        <ad:enrichedDescription>* Klimaanlage TEMPMATIC\\* TEMPOMAT\\* Aktiver Park-Assistent\\* Radio Audio 10 ( Bluetooth, USB, AUX &amp; SD-Karte )\\* Multifunktionslenkrad mit Reiserechner\\* Lederlenkrad und Lederschalthebel\\* Komfort-Fahrersitz\\* Sitzheizung für Fahrer\\* Airbag Fahrer\\* Beifahrersitz Zweisitzer\\* Airbag Beifahrer\\* Stoff Tunja schwarz\\* 6-Gang-Schaltgetriebe TSG 380\\* Komfort-Öffnung u.Schließung mit IR-Fernbedienung\\* Fahrlichtassistent\\* Aufmerksamkeits-Assistent ATTENTION ASSIST\\* Berganfahrhilfe\\* Regensensor\\* Reifenluftdrucküberwachung an VA u. HA, drahtlos\\* Dachreling\\* Trennwand durchgehend mit 1 Fenster\\* Holzfußboden\\* Lastenverankerungsschienensystem\\* Innenverkleidung Laderaum bis Dachhöhe\\* LED-Lichtband im Laderaum\\* Hecktüren, zweiflügelig, Öffnung bis Seitenwand\\* Adaptives Bremslicht\\* Elektrik für Anhängersteckdose\\* Fahrzeug schadstoffarm Euro 5b+ Gr. III\\* Zulassung als LKW\\* Motor OM 651 DE 22 LA 120 kW (163 PS) 3800/min\\* Paket EASY CARGO\\* Inland - Code\\\\ \\ Zubehörangaben ohne Gewähr, Änderungen, Zwischenverkauf und Irrtümer vorbehalten.</ad:enrichedDescription>
        <ad:images count="3" gallery-url="$_23.JPG" url="">
                <ad:representation size="S" url="$_18.JPG"/>
                <ad:representation size="XL" url="$_27.JPG"/>
                <ad:representation size="ICON" url="$_23.JPG"/>
                <ad:representation size="L" url="$_1.JPG"/>
                <ad:representation size="M" url="$_24.JPG"/>
                <ad:representation size="S" url="$_18.JPG"/>
                <ad:representation size="XL" url="$_27.JPG"/>
                <ad:representation size="ICON" url="$_23.JPG"/>
                <ad:representation size="L" url="$_1.JPG"/>
                <ad:representation size="M" url="$_24.JPG"/>
                <ad:representation size="S" url="$_18.JPG"/>
                <ad:representation size="XL" url="$_27.JPG"/>
                <ad:representation size="ICON" url="$_23.JPG"/>
                <ad:representation size="L" url="$_1.JPG"/>
                <ad:representation size="M" url="$_24.JPG"/>
        <ad:price currency="EUR" type="FIXED">
            <ad:consumer-price-amount value="23193.10"/>
            <ad:vatable value="true"/>
            <ad:vat-rate value="0.19"/>
        <seller:seller key="1177" url="">
            <seller:type value="DEALER" commercial="true"/>
            <seller:company-name value="Herbrand GmbH"/>
                <seller:street value="Wettener Straße 18"/>
                <seller:zipcode value="20359"/>
                <seller:city value="Hamburg"/>
                <seller:country-code value="DE"/>
            <seller:phone type="FIXED" country-calling-code="49" area-code="01234" number="2222333"/>
            <seller:phone type="FAX" country-calling-code="49" area-code="01234" number="3333222"/>

Customer Support Contact

Please contact the Customer Support team if you need further assistance.

Country Contact Details


Phone: +49 (0) 30 81097500 or Contact Form


Phone: +39 02 30410311 or Contact Form


Phone: +33 (0) 810 000 220 or Contact Form