mobileLogo

Search API description

The Search-API is also known as Ad-Integration (german: Inserats-Einbindung).

Introduction

We offer a search API for...

Please note that a search result has a lower data coverage than a direct ad download by an ad-key.
Thus some ad properties obtainable via a direct download (using ad-key) are not gettable in a search result containing that ad.

REST

The design of the API is based on the REST principle (Representational State Transfer).
You can find more information about this software architecture here: http://en.wikipedia.org/wiki/Representational_State_Transfer

Language support

Numerous ad properties provide a translated description.
Default language is English, yet sending an HTTP header field Accept-Language enriched by the appropriate value enables the requester to get a translated description in all supported languages at mobile.de.

Authentication

You must authenticate yourself with a username and password using the HTTP basic authentication scheme.
For detailed information on HTTP basic authentication see http://en.wikipedia.org/wiki/Basic_access_authentication or http://tools.ietf.org/html/rfc1945#section-10.2.

HTTP header fields

HTTP header field Possible values Description
Accept application/xml Selects XML as output format. JSON is no longer supported. You must send this header.
Accept-Encoding gzip Sending this field allows you to receive a zipped result file.
Accept-Language cz, de, en, es, fr, it, pl, ro or ru Sending this field allows you to control the result language.
Authorization Username and password are joined together using a colon and then being encoded using Base64. HTTP basic authentication - You must send this header.

Reference data

Some search parameters and parts of the returned XML refer to our reference data. Here you find reference tables for the enumerated fields, like features, colors, makes, models and others.

XML schema files

Resource data type (parent for many other types) resource-1.0.xsd
Search result search-1.0.xsd
Ad data (standalone or part of a search result) ad-1.0.xsd
Seller data (part of an ad) seller-1.0.xsd

Downloading single ads by an ad-key

Fetch details of an ad

Request

Resource path Method Content-Type / Accept header
https://services.mobile.de/search-api/ad/{ad-key} GET application/xml

Example request-line and headers

GET /search-api/ad/456 HTTP/1.0
Host: services.mobile.de
Authorization: QWxhZGluOnNlc2FtIG9wZW4=
Accept: application/xml

Response

Response status Explanation
200 (OK) success
404 (not found) You provided a wrong ad-key.

Finding ads

Search for ads by various criteria

Request

Resource path Method Content-Type / Accept header
https://services.mobile.de/search-api/search?{search-parameters} GET application/xml

Example request-line and headers

GET /search-api/search?exteriorColor=BLACK&modificationTime.min=2012-05-04T18:13:51.0Z HTTP/1.0
Host: services.mobile.de
Authorization: QWxhZGluOnNlc2FtIG9wZW4=
Accept: application/xml

Response

Response status Explanation
200 (OK) success
400 (bad request) This code is returned when there is something wrong with the query that you have sent.
In such cases the api tries to include in the error response as much details as possible to help the user to identify the problem.

Number of search results and paginating

Due to technical reasons the number of of ads that can be retrieved via paginating through the result pages is limited to 2000. Meaning when your search query is matching more then 2000 ads and your page.size is 20 you will have ads on the first 100 result pages (20 pages for page.size 100). The following pages will be empty.

This is reflected on top of the search result:
<search:total>1813062</search:total>
<search:page-size>100</search:page-size>
<search:current-page>1</search:current-page>
<search:max-pages>20</search:max-pages>
If your search result is containing more ads than 2000 and you need to have the ad data please try to ad some more parameters to the search query to split the results, for example using the price parameter.

Error response

The Search API responds with HTTP status 400 (bad request) in case of user caused errors.

To find out what the exact error is, have a look at the returned XML content which is sent in the message body. It contains a list of error elements, each with an error key. There may also be an optional message attribute which is a localized description of the error key.

Exampe:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <error:errors xmlns:error="http://services.mobile.de/schema/common/error-1.0">
    <error:error key="invalid-search-parameter" message="Invalid search parameter">
      <error:args key="field">exteriorColor</error:args>
      <error:args key="code">typeMismatch</error:args>
      <error:args key="rejected-value">BLACK11,RED</error:args>
    </error:error>
</error:errors>

Other examples

Search parameters

Parameter Type Description/Example
page.number int page number of result set - it starts with 1
page.size int default: 20, max size 100
sort.field String The name of the field to sort. Must be combined with sort.order.
Example: https://services.mobile.de/search-api/search?country=DE&sort.field=modificationTime&sort.order=DESCENDING

Sorting by make and model: There is a special sort order field name which has no similar search parameter equivalent called "makeModel". This results in a combined order of make and model.
Example: https://services.mobile.de/search-api/search?country=DE&sort.field=makeModel&sort.order=ASCENDING
sort.order ASCENDING, DESCENDING Example:
sort.order=ASCENDING
customerNumber Set(Long) Search for vehicles of specific sellers defined by customerNumber.

Example: https://services.mobile.de/search-api/search?customerNumber=514508,540951
  • What is a customer number? A customer number identifies a dealer seller (not private FSBO seller). The customerId is something else.
  • Some API user may only see ads of a defined set of delaer sellers. You do not need to add this search parameter to comply to this restrictions. It is done automatically.
  • If you specify both parameters (customerNumber and customerId) then the customerId parameter is ignored.
customerId Set(Long) Search for vehicles of specific sellers defined by customer ID.

Example: https://services.mobile.de/search-api/search?customerId=471738
  • What is a customer ID? A customer ID identifies a dealer seller or a private FSBO seller. The customerNumber (only for dealers) is something else.
  • Some API user may only see ads of a defined set of delaer sellers. You do not need to add this search parameter to comply to this restrictions. It is done automatically.
  • If you specify both parameters (customerNumber and customerId) then the customerId parameter is ignored.
classification Set(String) Classification is used to define the make/model or make/modelgroup combination for cars. It is also possible to use this parameter to specify a certain vehicle class. The definition of a make is possible for all vehicles with this parameter.
For vehicle classes other than Car, please use "modelDescription" instead of "classification" and "model"

Example search for AUDI A8:
https://services.mobile.de/search-api/search?classification=refdata/classes/Car/makes/AUDI/models/A8

Example search for BMW X-Reihe:
https://services.mobile.de/search-api/search?classification=refdata/classes/Car/makes/BMW/modelgroups/X__BMW_SERIES

Example search for Motorbikes with the String "Classic" in model description:
https://services.mobile.de/search-api/search?classification=refdata/classes/Motorbike&modelDescription=Classic
category Set(enum) Example:
https://services.mobile.de/search-api/search?category=Limousine,OffRoad

Possible values for cars:
https://services.mobile.de/refdata/classes/Car/categories

Possible values for bikes:
https://services.mobile.de/refdata/classes/Motorbike/categories

Possible values for motorhomes:
https://services.mobile.de/refdata/classes/Motorhome/categories
feature Set(enum) Example search for vehicles with sunroof and central locking:
https://services.mobile.de/search-api/search?feature=SUNROOF,CENTRAL_LOCKING

Possible values:
https://services.mobile.de/refdata/classes/Car/features
excludeFeature Set(enum) Example exclude export vehicles from the search result:
https://services.mobile.de/search-api/search?classification=refdata/classes/Car&excludeFeature=EXPORT

Possible values:
https://services.mobile.de/refdata/classes/Car/features
condition Set(enum) USED, NEW
Example for usage: https://services.mobile.de/search-api/search?condition=NEW
exteriorColor Set(enum) Example search for black and red vehicles:
https://services.mobile.de/search-api/search?exteriorColor=BLACK,RED

Possible values:
https://services.mobile.de/refdata/colors
emissionClass Set(enum) Example search for vehicles with emission class EURO3:
https://services.mobile.de/search-api/search?emissionClass=EURO3

Possible values:
https://services.mobile.de/refdata/emissionclasses
fuel Set(enum) Example search for hybrid fuel vehicles:
https://services.mobile.de/search-api/search?fuel=HYBRID

Possible values:
https://services.mobile.de/refdata/fuels
climatisation Set(enum) Example search for vehicles with any climatisation:
https://services.mobile.de/search-api/search?climatisation=MANUAL_CLIMATISATION,AUTOMATIC_CLIMATISATION

Possible values:
https://services.mobile.de/refdata/climatisations
emissionSticker Set(enum) Example search for vehicles with green emissionsticker (Germany only):
https://services.mobile.de/search-api/search?emissionSticker=EMISSIONSSTICKER_GREEN

Possible values:
https://services.mobile.de/refdata/emissionstickers
gearbox Set(enum) Example search for vehicles with semi-automatic gearshift:
https://services.mobile.de/search-api/search?gearbox=SEMIAUTOMATIC_GEAR

Possible values:
https://services.mobile.de/refdata/gearboxes
usageType Set(enum) Example search for classic cars:
https://services.mobile.de/search-api/search?usageType=CLASSIC

Possible values:
https://services.mobile.de/refdata/usagetypes
drivingMode Set(enum) Example search for motorbikes with belt transmission (only available for Motorbikes):
https://services.mobile.de/search-api/search?drivingMode=BELT_DRIVE

Possible values:
https://services.mobile.de/refdata/drivingmodes
modelDescription String Search for vehicles with "right hand drive" in model description:
https://services.mobile.de/search-api/search?modelDescription=right%20hand%20drive
price.min decimal Minimum price(gros price) in EUR

Search for vehicles over 5000 EUR:
https://services.mobile.de/search-api/search?price.min=5000&classification=refdata/classes/Car
price.max decimal Maximum price(gros price) in EUR

Search for vehicles under 10000 EUR:
https://services.mobile.de/search-api/search?price.max=10000&classification=refdata/classes/Car
vatable bool Use vatable=1 for get all vehicles where VAT is vatable

Search for vehicles under 10000 EUR with VAT vatable:
https://services.mobile.de/search-api/search?vatable=1&price.min=10000&classification=refdata/classes/Car
country ISO-3166-1 alpha-2 Example search for all vehicles from Austrian sellers:
https://services.mobile.de/search-api/search?country=AT

Possible values:
http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
firstRegistrationDate.min gYearMonth Example search for all vehicles with a first Registration in 01.2007 or later:
https://services.mobile.de/search-api/search?firstRegistrationDate.min=2007-01&classification=refdata/classes/Car
firstRegistrationDate.max gYearMonth Example search for all vehicles with a first Registration earlier than 01.1971:
https://services.mobile.de/search-api/search?firstRegistrationDate.max=1971-01&classification=refdata/classes/Car
constructionYear.min int, YYYY Example search for vehicles with a construction year 1988 or later:
https://services.mobile.de/search-api/search?constructionYear.min=1988&classification=refdata/classes/ConstructionMachine
constructionYear.max int, YYYY Example search for vehicles with a construction year 1971 or earlier:
https://services.mobile.de/search-api/search?constructionYear.max=1971&classification=refdata/classes/ConstructionMachine
modificationTime.min date and dateTime Example search for all vehicles/ads modified after a specific time:
modificationTime.min=2008-05-04T18:13:51%2B01:00&classification=refdata/classes/Car ormodificationTime.min=2008-05-04&classification=refdata/classes/Car

Note: If the time zone passed, the '+' character must be URL encoded. Pass "2008-05-04T18:13:51+01:00" as "2008-05-04T18:13:51%2B01:00"
modificationTime.max date and dateTime Example search for all vehicles/ads modified before a specific time:
modificationTime.max=2008-05-04T18:13:51%2B01:00&classification=refdata/classes/Car ormodificationTime.max=2008-05-04&classification=refdata/classes/Car

Note: If the time zone passed, the '+' character must be URL encoded. Pass "2008-05-04T18:13:51+01:00" as "2008-05-04T18:13:51%2B01:00"
creationTime.min date and dateTime Example search for all vehicles/ads created after a specific time:
creationTime.min=2008-05-04T18:13:51%2B01:00&classification=refdata/classes/Car orcreationTime.min=2008-05-04&classification=refdata/classes/Car

Note: If the time zone passed, the '+' character must be URL encoded. Pass "2008-05-04T18:13:51+01:00" as "2008-05-04T18:13:51%2B01:00"
creationTime.max date and dateTime Example search for all vehicles/ads created before a specific time:
creationTime.max=2008-05-04T18:13:51%2B01:00&classification=refdata/classes/Car orcreationTime.max=2008-05-04&classification=refdata/classes/Car

Note: If the time zone passed, the '+' character must be URL encoded. Pass "2008-05-04T18:13:51+01:00" as "2008-05-04T18:13:51%2B01:00"
damageUnrepaired bool Use damageUnrepaired=0 to suppress damaged and unrepaired vehicles. Please see Damaged, Accident, Roadworthy for more details.
Do not specify this parameter when you search for vehicle classes that do not have this information set (AgriculturalVehicle, ConstructionMachine, ForkliftTruck, SemiTrailer and Trailer).

Search for damaged and unrepaired vehicles under 1000 EUR:
https://services.mobile.de/search-api/search?damageUnrepaired=1&vatable=1&price.min=1000&classification=refdata/classes/Car
accidentDamaged bool The vehicle once had an accident which may be repaired or not. Please see Damaged, Accident, Roadworthy for more details.

Example search for cars that are accident free
https://services.mobile.de/search-api/search?accidentDamaged=1&classification=refdata/classes/Car
roadworthy bool The vehicle is ready to drive. Please see Damaged, Accident, Roadworthy for more details.

Example search for cars that are ready to drive
https://services.mobile.de/search-api/search?roadworthy=1&classification=refdata/classes/Car
mileage.min int Minimum mileage in kilometers
Example search for vehicles with mileage over 100.000 kilometers:
https://services.mobile.de/search-api/search?mileage.min=100000&classification=refdata/classes/Car
mileage.max int Maximum mileage in kilometers
Example search for vehicles with mileage under 40.000 kilometers:
https://services.mobile.de/search-api/search?mileage.max=40000&classification=refdata/classes/Car
power.min decimal Minimum power in kilowatt (kW)
Example search for vehicles with power over 75kW:
https://services.mobile.de/search-api/search?power.min=75&classification=refdata/classes/Car
power.max decimal Maximum power in kilowatt (kW)
Example search for vehicles with power less than 30kW:
https://services.mobile.de/search-api/search?power.max=30&classification=refdata/classes/Car
liftingCapacity.min int Minimum lifting capacity for commercial vehicles in kilogramm (kg)

Example search for vehicles with a minimum lifting capacity of 500kg:
https://services.mobile.de/search-api/search?liftingCapacity.min=500&classification=refdata/classes/Car
liftingCapacity.max int Maximum lifting capacity for commercial vehicles in kilogramm (kg)

Example search for vehicles with a maximum lifting capacity of 1000kg:
https://services.mobile.de/search-api/search?liftingCapacity.max=1000&classification=refdata/classes/ForkliftTruck
installationHeight.min int Minimum installation height for forklift trucks in mm

Example search for vehicles with a minimum installation height of 2m (2000mm):
https://services.mobile.de/search-api/search?installationHeight.min=2000&classification=refdata/classes/ForkliftTruck
installationHeight.max int Maximum installation height for forklift trucks in mm

Example search for vehicles with a maximum installation height of 3m (3000mm):
https://services.mobile.de/search-api/search?installationHeight.max=3000&classification=refdata/classes/ForkliftTruck
operatingHours.min int Minimum value of operating hours for construction machines in h

Example search for vehicles with a minimum of 300 operating hours:
https://services.mobile.de/search-api/search?operatingHours.min=300&classification=refdata/classes/ConstructionMachine
operatingHours.max int Maximum value of operating hours for construction machines in h

Example search for vehicles with a minimum of 500 operating hours:
https://services.mobile.de/search-api/search?operatingHours.max=500&classification=refdata/classes/ConstructionMachine
liftingHeight.min int Minimum lifting height for forklift trucks in mm

Example search for vehicles with a minimum lifting height of 5m (5000mm):
https://services.mobile.de/search-api/search?liftingHeight.min=5000&classification=refdata/classes/ForkliftTruck
liftingHeight.max int Maximum lifting height for forklift trucks in mm

Example search for vehicles with a maximum lifting height of 3m (3000mm):
https://services.mobile.de/search-api/search?liftingHeight.max=3000&classification=refdata/classes/ForkliftTruck
axles.min int Minimum number of axles for commercial vehicles

Example search for vehicles with a minimum of 4 axles:
https://services.mobile.de/search-api/search?axles.min=4&classification=refdata/classes/TruckOver7500
axles.max int Maximum number of axles for commercial vehicles

Example search for vehicles with a maximum of 8 axles:
https://services.mobile.de/search-api/search?axles.min=8&classification=refdata/classes/TruckOver7500
loadCapacity.min int Minimum load capacity for trailers and semi-trailers in kg

Example search for trailers with a minimum load capacity of 2.5t(2500kg):
https://services.mobile.de/search-api/search?loadCapacity.min=2500&classification=refdata/classes/Trailer
loadCapacity.max int Maximum load capacity for trailers and semi-trailers in kg

Example search for trailers and semi-trailers with a maximum load capacity of 20t(20.000kg):
https://services.mobile.de/search-api/search?loadCapacity.max=20000&classification=refdata/classes/Trailer
cubicCapacity.min int Minimum cubic capacity for motorbikes in ccm

Example search for bikes with a minimum cubic capacity of 125 ccm:
https://services.mobile.de/search-api/search?cubicCapacity.min=125&classification=refdata/classes/Motorbike
cubicCapacity.max int Maximum cubic capacity for motorbikes in ccm

Example search for bikes with a maximum cubic capacity of 1000ccm:
https://services.mobile.de/search-api/search?cubicCapacity.max=1000&classification=refdata/classes/Motorbike
numSeats.min int Number of min passenger seats

Example search for vehicles with 2-3 seats:
https://services.mobile.de/search-api/search?numSeats.min=2&numSeats.max=3&classification=refdata/classes/Car
numSeats.max int Number of max passenger seats

Example search for vehicles with 2-3 seats:
https://services.mobile.de/search-api/search?numSeats.min=2&numSeats.max=3&classification=refdata/classes/Car
deliveryPeriod.min int Minimum number of days until a vehicle is available

Example search for vehicles available in 3 days or later:
https://services.mobile.de/search-api/search?deliveryPeriod.min=3&classification=refdata/classes/Car
deliveryPeriod.max int Maximum number of days until a vehicle is available

Example search for vehicles available in 14 days or earlier:
https://services.mobile.de/search-api/search?deliveryPeriod.max=14&classification=refdata/classes/Car
sellerType FOR_SALE_BY_OWNER, DEALER Defines the type of seller
Example search for all Bentleys advertised by private sellers only: https://services.mobile.de/search-api/search?sellerType=FOR_SALE_BY_OWNER&classification=refdata/classes/Car/makes/Bentley
doorCount Set(enum) Example:
https://services.mobile.de/search-api/search?doorCount=TWO_OR_THREE,FOUR_OR_FIVE

Possible values:
https://services.mobile.de/refdata/doorcounts
drivingCab Set(enum) Example:
https://services.mobile.de/search-api/search?drivingCab=DOUBLE_CABIN

Possible values:
https://services.mobile.de/refdata/drivingcabs
licensedWeight.min int
licensedWeight.max int
wheelFormula Set(enum) Possible values:
https://services.mobile.de/refdata/wheelformulas
ambit.zipcode String Zipcode for regional search. Currently only available in Germany; only valid German zip codes are accepted.
Example: all cars within a 10 kilometer radius of zip code 14532 https://services.mobile.de/search-api/search?classification=refdata/classes/Car&ambit.zipcode=14532&ambit.radius=10
ambit.radius int Radius size in kilometers for regional search. Default value is 0.
ambit.country ISO-3166-1 alpha-2 Country code for regional search. Default is DE (currently, the only accepted value).
imageCount.min int Minimum number of images attached to the ad

Example search for car ads with a minimum of 1 images:
https://services.mobile.de/search-api/search?imageCount.min=1&classification=refdata/classes/Car
imageCount.max int Maximum number of images attached to the ad

Example search for car ads with a maximum of 4 images:
https://services.mobile.de/search-api/search?imageCount.max=4&classification=refdata/classes/Car
numberOfPreviousOwners.min int Minimum number of previous owners

Example search for car ads with a minimum of 1 previous owners:
https://services.mobile.de/search-api/search?numberOfPreviousOwners.min=1&classification=refdata/classes/Car
numberOfPreviousOwners.max int Maximum number of previous owners

Example search for car ads with a maximum of 3 previous owners:
https://services.mobile.de/search-api/search?numberOfPreviousOwners.max=3&classification=refdata/classes/Car
monthsTillInspection int Minimum number of months till next inspection

Example search for car ads with an inspection not earlier than in 6 months:
https://services.mobile.de/search-api/search?monthsTillInspection=6&classification=refdata/classes/Car
interiorColor Set(enum) Example search for vehicles with brown interior:
https://services.mobile.de/search-api/search?interiorColor=BROWN

Possible values:
https://services.mobile.de/refdata/interiorcolors
interiorType Set(enum) Example search for vehicles with brown interior:
https://services.mobile.de/search-api/search?interiorType=ALCANTARA

Possible values:
https://services.mobile.de/refdata/interiortypes
airbag Set(enum) Example search for vehicles with front and side airbags:
https://services.mobile.de/search-api/search?airbag=FRONT_AND_SIDE_AIRBAGS

Possible values:
https://services.mobile.de/refdata/airbags
parkingAssistant Set(enum) Example search for vehicles in Germany with front parking sensors:
https://services.mobile.de/search-api/search?country=DE&parkingAssistant=FRONT_SENSORS

Possible values:
https://services.mobile.de/refdata/parkingassistants
countryVersion Set(enum) Example search for vehicles that were manufactured for German or French market:
https://services.mobile.de/search-api/search?countryVersion=DE,FR

Possible values:
http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
speedControl Set(enum) Example search for vehicles in Germany with cruise control
https://services.mobile.de/search-api/search?country=DE&speedControl=CRUISE_CONTROL,ADAPTIVE_CRUISE_CONTROL

Possible values:
https://services.mobile.de/refdata/speedcontrols
radio Set(enum) Example search for vehicles in Germany with DAB radio
https://services.mobile.de/search-api/search?country=DE&radio=DAB_RADIO

Possible values:
https://services.mobile.de/refdata/radiotypes
daytimeRunningLamps Set(enum) Example search for vehicles in Germany with daytime running lights
https://services.mobile.de/search-api/search?country=DE&daytimeRunningLamps=DAYTIME_RUNNING_LIGHTS

Possible values:
https://services.mobile.de/refdata/daytimerunninglamps
slidingDoor Set(enum) Example search for vehicles in Germany with sliding doors left
https://services.mobile.de/search-api/search?country=DE&slidingDoor=SLIDING_DOOR_LEFT

Possible values:
https://services.mobile.de/refdata/slidingdoortypes
headlightType Set(enum) Example search for vehicles in Germany with xenon headlights
https://services.mobile.de/search-api/search?country=DE&headlightType=XENON_HEADLIGHTS

Possible values:
https://services.mobile.de/refdata/headlighttypes
bendingLightsType Set(enum) Example search for vehicles in Germany with adaptive bending lights
https://services.mobile.de/search-api/search?country=DE&bendingLightsType=ADAPTIVE_BENDING_LIGHTS

Possible values:
https://services.mobile.de/refdata/bendinglightstypes
breakdownService Set(enum) Example search for vehicles in Germany with spare wheel
https://services.mobile.de/search-api/search?country=DE&breakdownService=SPARE_WHEEL

Possible values:
https://services.mobile.de/refdata/breakdownservices
battery Set(enum) Example search for vehicles in Germany with rented battery
https://services.mobile.de/search-api/search?country=DE&battery=BATTERY_RENTED

Possible values:
https://services.mobile.de/refdata/batteries
batteryCapacity.min int Minimum battery capacity for vehicles in kWh. (0 < x < 1000) kWh

Example search for electric vehicles with a minimum batterry capacity of 5 kWh:
https://services.mobile.de/search-api/search?batteryCapacity.min=500
batteryCapacity.max int Maximum battery capacity for vehicles in kWh. (0 < x < 1000) kWh

Example search for electric vehicles with a maximum batterry capacity of 50 kWh:
https://services.mobile.de/search-api/search?batteryCapacity.max=50
trailerCouplingType Set(enum) Example search for vehicles in Germany with a fixed trailer coupling type
https://services.mobile.de/search-api/search?country=DE&trailerCouplingType=TRAILER_COUPLING_FIX

Possible values:
https://services.mobile.de/refdata/trailercouplingtypes

Impressum / Imprint