{ "openapi" : "3.1.0", "info" : { "title" : "Insights-API", "description" : "Insights API for mobile.de", "termsOfService" : "", "license" : { "name" : "Proprietary Software", "url" : "http://www.mobile.de/" }, "version" : "1.0.0" }, "servers" : [ { "url" : "https://services.sandbox.mobile.de/insights-api", "description" : "Sandbox" } ], "paths" : { "/search-result-position/sellers/{mobileSellerId}/ads" : { "get" : { "tags" : [ "search-result-position-controller" ], "summary" : "Retrieve search result position for multiple mobileAdIds", "operationId" : "getSearchResultPositionBulk", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdIds", "in" : "query", "required" : true, "schema" : { "type" : "array", "items" : { "type" : "string" }, "uniqueItems" : true } } ], "responses" : { "200" : { "description" : "Successfully retrieved search result positions", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiBulkAdSearchResultPositionResponse" }, "example" : { "mobileSellerId" : "123", "searchResultPositions" : [ { "mobileAdId" : "123456789", "searchResultPosition" : { "page" : 1, "position" : 2, "ranked" : true, "calculatedAt" : "2026-02-24T15:24:16.024Z" } }, { "mobileAdId" : "987654321", "searchResultPosition" : { "page" : 1, "position" : 5, "ranked" : true, "calculatedAt" : "2026-02-24T15:24:16.024Z" } } ] } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdIds is missing or invalid" } } } }, "403" : { "description" : "Forbidden – the client does not have permission to access this resource", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested ads not found for the seller", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "NOT_FOUND", "message" : "No ads found for seller: 123" } } } }, "500" : { "description" : "Something went wrong when fetching search result positions", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/search-result-position/sellers/{mobileSellerId}/ads/{mobileAdId}" : { "get" : { "tags" : [ "search-result-position-controller" ], "summary" : "Retrieve search result position for one mobileAdId", "operationId" : "getSearchResultPosition", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Successfully retrieved search result position", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiAdSearchResultPositionResponse" }, "example" : { "mobileAdId" : "123456789", "searchResultPosition" : { "page" : 1, "position" : 1, "ranked" : true, "calculatedAt" : "2026-02-24T15:24:16.024Z" } } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdId is missing or invalid" } } } }, "403" : { "description" : "Forbidden – the client does not have permission to access this resource", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested ad not found for the seller or search result position data not available" }, "500" : { "description" : "Something went wrong when fetching search result position", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/sales-probability/sellers/{mobileSellerId}" : { "get" : { "tags" : [ "sales-probability-controller" ], "summary" : "Retrieve multiple sales probabilities for mobileAdIds", "operationId" : "getSalesProbabilities", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdIds", "in" : "query", "required" : true, "schema" : { "type" : "array", "items" : { "type" : "string" }, "uniqueItems" : true } } ], "responses" : { "200" : { "description" : "Successfully retrieved sales probabilities", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiAdsSalesProbabilities" }, "example" : { "mobileSellerId" : "123", "adsSalesProbabilities" : [ { "mobileAdId" : "1", "salesProbabilityLabel" : "HIGH" }, { "mobileAdId" : "2", "salesProbabilityLabel" : "MEDIUM" }, { "mobileAdId" : "3", "salesProbabilityLabel" : "LOW" }, { "mobileAdId" : "4", "salesProbabilityLabel" : "NO_RATING", "errorCodes" : [ "AD_HAS_DAMAGED_VEHICLE", "AD_IS_NOT_ACTIVE" ] } ] } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdIds are missing or invalid" } } } }, "403" : { "description" : "Unauthorized request", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested Listings not found for the seller" }, "500" : { "description" : "Something went wrong when fetching sales probabilities", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/sales-probability/sellers/{mobileSellerId}/ads/{mobileAdId}" : { "get" : { "tags" : [ "sales-probability-controller" ], "summary" : "Retrieve single sales probability for one mobileAdId", "operationId" : "getSalesProbability", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Successfully retrieved sales probability", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiAdSalesProbability" }, "example" : { "mobileAdId" : "1", "salesProbabilityLabel" : "HIGH" } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdId is missing or invalid" } } } }, "403" : { "description" : "Unauthorized request", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested Listing not found for the seller" }, "422" : { "description" : "Validation error occurred when processing the ad", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "VALIDATION_ERROR", "message" : "The ad could not be processed due to validation errors.", "errorExplanations" : [ "AD_IS_MISSING_REQUIRED_FIELD_MODEL", "AD_IS_NOT_ACTIVE" ] } } } }, "500" : { "description" : "Something went wrong when fetching sales probability", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/popular-search-criteria/sellers/{mobileSellerId}" : { "get" : { "tags" : [ "popular-search-criteria-controller" ], "summary" : "Retrieve popular search criteria for multiple ads", "operationId" : "getPopularSearchCriteriaBulk", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdIds", "in" : "query", "required" : true, "schema" : { "type" : "array", "items" : { "type" : "string" }, "uniqueItems" : true } } ], "responses" : { "200" : { "description" : "Successfully retrieved popular search criteria", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiPopularSearchCriteriaBulkResponse" }, "example" : { "mobileSellerId" : 123, "popularSearchCriteria" : [ { "mobileAdId" : 456, "make" : "BMW", "model" : "X3", "fuel" : "DIESEL", "condition" : "NEW", "popularSearchCriteria" : { "coreFilters" : [ { "filter" : "mileage", "attribute" : "mileage", "filterType" : "RANGE", "rank" : 1, "max" : 80000, "unit" : "km" }, { "filter" : "price", "attribute" : "price", "filterType" : "RANGE", "rank" : 2, "min" : 15000, "max" : 25000, "unit" : "EUR" }, { "filter" : "transmission", "attribute" : "gearbox", "filterType" : "VALUE_STRING", "rank" : 3, "value" : "AUTOMATIC_GEAR" }, { "filter" : "power", "attribute" : "power", "filterType" : "RANGE", "rank" : 4, "min" : 110, "max" : 147, "unit" : "kW" }, { "filter" : "category", "attribute" : "category", "filterType" : "VALUE_STRING", "rank" : 5, "value" : "Limousine" }, { "filter" : "exterior_color", "attribute" : "exteriorColor", "filterType" : "VALUE_STRING", "rank" : 6, "value" : "WHITE" }, { "filter" : "emission_class", "attribute" : "emissionClass", "filterType" : "VALUE_STRING", "rank" : 7, "value" : "EURO2" }, { "filter" : "interior_color", "attribute" : "interiorColor", "filterType" : "VALUE_STRING", "rank" : 8, "value" : "BROWN" }, { "filter" : "door_count", "attribute" : "doors", "filterType" : "VALUE_STRING", "rank" : 9, "value" : "FOUR_OR_FIVE" }, { "filter" : "days_online", "attribute" : "creationDate", "filterType" : "VALUE_STRING", "rank" : 10, "value" : "1" } ], "featureFilters" : [ { "filter" : "FRONT_SENSORS", "attribute" : "parkingAssistants", "rank" : 1 }, { "filter" : "REAR_VIEW_CAM", "attribute" : "parkingAssistants", "rank" : 2 }, { "filter" : "ELECTRIC_HEATED_SEATS", "attribute" : "electricHeatedSeats", "rank" : 3 }, { "filter" : "NONSMOKER_VEHICLE", "attribute" : "nonSmokerVehicle", "rank" : 4 }, { "filter" : "WARRANTY", "attribute" : "warranty", "rank" : 5 }, { "filter" : "ALL_WHEEL", "attribute" : "driveType", "rank" : 6 }, { "filter" : "REAR_SENSORS", "attribute" : "parkingAssistants", "rank" : 7 }, { "filter" : "NEW_SERVICE", "attribute" : "newService", "rank" : 8 }, { "filter" : "FULL_SERVICE_HISTORY", "attribute" : "fullServiceHistory", "rank" : 9 }, { "filter" : "CARPLAY", "attribute" : "carplay", "rank" : 10 } ] } }, { "mobileAdId" : 789, "make" : "BMW", "model" : "X3", "fuel" : "DIESEL", "condition" : "NEW", "popularSearchCriteria" : { "coreFilters" : [ { "filter" : "mileage", "attribute" : "mileage", "filterType" : "RANGE", "rank" : 1, "max" : 80000, "unit" : "km" }, { "filter" : "price", "attribute" : "price", "filterType" : "RANGE", "rank" : 2, "min" : 15000, "max" : 25000, "unit" : "EUR" }, { "filter" : "transmission", "attribute" : "gearbox", "filterType" : "VALUE_STRING", "rank" : 3, "value" : "AUTOMATIC_GEAR" }, { "filter" : "power", "attribute" : "power", "filterType" : "RANGE", "rank" : 4, "min" : 110, "max" : 147, "unit" : "kW" }, { "filter" : "category", "attribute" : "category", "filterType" : "VALUE_STRING", "rank" : 5, "value" : "Limousine" }, { "filter" : "exterior_color", "attribute" : "exteriorColor", "filterType" : "VALUE_STRING", "rank" : 6, "value" : "WHITE" }, { "filter" : "emission_class", "attribute" : "emissionClass", "filterType" : "VALUE_STRING", "rank" : 7, "value" : "EURO2" }, { "filter" : "interior_color", "attribute" : "interiorColor", "filterType" : "VALUE_STRING", "rank" : 8, "value" : "BROWN" }, { "filter" : "door_count", "attribute" : "doors", "filterType" : "VALUE_STRING", "rank" : 9, "value" : "FOUR_OR_FIVE" }, { "filter" : "days_online", "attribute" : "creationDate", "filterType" : "VALUE_STRING", "rank" : 10, "value" : "1" } ], "featureFilters" : [ { "filter" : "FRONT_SENSORS", "attribute" : "parkingAssistants", "rank" : 1 }, { "filter" : "REAR_VIEW_CAM", "attribute" : "parkingAssistants", "rank" : 2 }, { "filter" : "ELECTRIC_HEATED_SEATS", "attribute" : "electricHeatedSeats", "rank" : 3 }, { "filter" : "NONSMOKER_VEHICLE", "attribute" : "nonSmokerVehicle", "rank" : 4 }, { "filter" : "WARRANTY", "attribute" : "warranty", "rank" : 5 }, { "filter" : "ALL_WHEEL", "attribute" : "driveType", "rank" : 6 }, { "filter" : "REAR_SENSORS", "attribute" : "parkingAssistants", "rank" : 7 }, { "filter" : "NEW_SERVICE", "attribute" : "newService", "rank" : 8 }, { "filter" : "FULL_SERVICE_HISTORY", "attribute" : "fullServiceHistory", "rank" : 9 }, { "filter" : "CARPLAY", "attribute" : "carplay", "rank" : 10 } ] } } ] } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdIds are missing or invalid" } } } }, "404" : { "description" : "Requested Listings not found for the seller" }, "403" : { "description" : "Unauthorized request", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "500" : { "description" : "Something went wrong when fetching popular search criteria", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/popular-search-criteria/sellers/{mobileSellerId}/ads/{mobileAdId}" : { "get" : { "tags" : [ "popular-search-criteria-controller" ], "summary" : "Retrieve insights for popular search criteria", "operationId" : "getPopularSearchCriteria", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdId", "in" : "path", "required" : true, "schema" : { "type" : "string", "minLength" : 1 } } ], "responses" : { "200" : { "description" : "Insights for popular search criteria", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiPopularSearchCriteriaResponse" }, "example" : { "mobileAdId" : 456, "make" : "BMW", "model" : "X3", "fuel" : "DIESEL", "condition" : "NEW", "popularSearchCriteria" : { "coreFilters" : [ { "filter" : "mileage", "attribute" : "mileage", "filterType" : "RANGE", "rank" : 1, "max" : 80000, "unit" : "km" }, { "filter" : "price", "attribute" : "price", "filterType" : "RANGE", "rank" : 2, "min" : 15000, "max" : 25000, "unit" : "EUR" }, { "filter" : "transmission", "attribute" : "gearbox", "filterType" : "VALUE_STRING", "rank" : 3, "value" : "AUTOMATIC_GEAR" }, { "filter" : "power", "attribute" : "power", "filterType" : "RANGE", "rank" : 4, "min" : 110, "max" : 147, "unit" : "kW" }, { "filter" : "category", "attribute" : "category", "filterType" : "VALUE_STRING", "rank" : 5, "value" : "Limousine" }, { "filter" : "exterior_color", "attribute" : "exteriorColor", "filterType" : "VALUE_STRING", "rank" : 6, "value" : "WHITE" }, { "filter" : "emission_class", "attribute" : "emissionClass", "filterType" : "VALUE_STRING", "rank" : 7, "value" : "EURO2" }, { "filter" : "interior_color", "attribute" : "interiorColor", "filterType" : "VALUE_STRING", "rank" : 8, "value" : "BROWN" }, { "filter" : "door_count", "attribute" : "doors", "filterType" : "VALUE_STRING", "rank" : 9, "value" : "FOUR_OR_FIVE" }, { "filter" : "days_online", "attribute" : "creationDate", "filterType" : "VALUE_STRING", "rank" : 10, "value" : "1" } ], "featureFilters" : [ { "filter" : "FRONT_SENSORS", "attribute" : "parkingAssistants", "rank" : 1 }, { "filter" : "REAR_VIEW_CAM", "attribute" : "parkingAssistants", "rank" : 2 }, { "filter" : "ELECTRIC_HEATED_SEATS", "attribute" : "electricHeatedSeats", "rank" : 3 }, { "filter" : "NONSMOKER_VEHICLE", "attribute" : "nonSmokerVehicle", "rank" : 4 }, { "filter" : "WARRANTY", "attribute" : "warranty", "rank" : 5 }, { "filter" : "ALL_WHEEL", "attribute" : "driveType", "rank" : 6 }, { "filter" : "REAR_SENSORS", "attribute" : "parkingAssistants", "rank" : 7 }, { "filter" : "NEW_SERVICE", "attribute" : "newService", "rank" : 8 }, { "filter" : "FULL_SERVICE_HISTORY", "attribute" : "fullServiceHistory", "rank" : 9 }, { "filter" : "CARPLAY", "attribute" : "carplay", "rank" : 10 } ] } } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdIds are missing or invalid" } } } }, "403" : { "description" : "Access is forbidden", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested Listing not found for the seller" }, "500" : { "description" : "Something goes wrong when fetching insights for popular search criteria.", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/performance-comparison/sellers/{mobileSellerId}" : { "get" : { "tags" : [ "performance-comparison-controller" ], "summary" : "Retrieve multiple performance comparison for mobileAdIds", "operationId" : "getPerformanceComparisons", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdIds", "in" : "query", "required" : true, "schema" : { "type" : "array", "items" : { "type" : "string" }, "uniqueItems" : true } } ], "responses" : { "200" : { "description" : "Successfully retrieved performance comparisons", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiAdsPerformanceComparisons" }, "example" : { "mobileSellerId" : "123", "adsPerformanceComparisons" : [ { "mobileAdId" : "1", "performanceComparisons" : { "impressionComparison" : { "label" : "GOOD" }, "viewComparison" : { "label" : "GOOD" }, "leadAndParkComparison" : { "label" : "GOOD" }, "overallComparison" : { "label" : "GOOD" } } }, { "mobileAdId" : "2", "performanceComparisons" : { "impressionComparison" : { "label" : "LOW" }, "viewComparison" : { "label" : "LOW" }, "leadAndParkComparison" : { "label" : "LOW" }, "overallComparison" : { "label" : "LOW" } } } ] } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdIds are missing or invalid" } } } }, "404" : { "description" : "Requested Listings not found for the seller" }, "403" : { "description" : "Unauthorized request", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "500" : { "description" : "Something went wrong when fetching performance comparisons", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/performance-comparison/sellers/{mobileSellerId}/ads/{mobileAdId}" : { "get" : { "tags" : [ "performance-comparison-controller" ], "summary" : "Retrieve single performance comparison for one mobileAdId", "operationId" : "getPerformanceComparison", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Successfully retrieved performance comparison", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiAdPerformanceComparison" }, "example" : { "mobileAdId" : "1", "performanceComparisons" : { "impressionComparison" : { "label" : "GOOD" }, "viewComparison" : { "label" : "GOOD" }, "leadAndParkComparison" : { "label" : "GOOD" }, "overallComparison" : { "label" : "GOOD" } } } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdId is missing or invalid" } } } }, "403" : { "description" : "Unauthorized request", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested Listing not found for the seller" }, "500" : { "description" : "Something went wrong when fetching performance comparison", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/market-health/sellers/{mobileSellerId}" : { "get" : { "tags" : [ "market-health-controller" ], "summary" : "Retrieve market health for multiple mobileAdIds", "operationId" : "getMarketHealthBulk", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdIds", "in" : "query", "required" : true, "schema" : { "type" : "array", "items" : { "type" : "string" }, "uniqueItems" : true } } ], "responses" : { "200" : { "description" : "Successfully retrieved market health", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiBulkAdMarketHealthResponse" }, "example" : { "mobileSellerId" : "123", "results" : [ { "adId" : "987654321", "successContent" : { "mobileAdId" : "987654321", "marketHealthSegment" : { "make" : "VW", "model" : "Golf", "category" : "EstateCar", "fuel" : "DIESEL", "doors" : "FOUR_OR_FIVE", "power" : 110, "gearbox" : "AUTOMATIC_GEAR", "ageBand" : "FIVE_TO_TEN" }, "weeklyMarketHealth" : [ { "weekNumber" : 1, "weekStartDate" : "2024-12-30", "year" : 2025, "priorYearWeekStartDate" : "2024-01-01", "supplyCurrentYear" : 25, "supplyPriorYear" : 7, "yoySupplyGrowth" : 257.14, "yoyDemandGrowth" : 151.63, "scaledDemandCurrentYear" : 13.26, "scaledDemandPriorYear" : 5.27, "marketHealthLabel" : "COOLING", "noLabelReason" : null } ] } }, { "adId" : "123456789", "errorContent" : { "message" : "Market health data not available", "errors" : [ { "errorcode" : "MARKET_HEALTH_NOT_FOUND", "message" : "No market health data found for this ad" } ] } } ] } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdIds is missing or invalid" } } } }, "403" : { "description" : "Forbidden – the client does not have permission to access this resource", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested Listings not found for the seller" }, "500" : { "description" : "Something went wrong when fetching market health", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } }, "/market-health/sellers/{mobileSellerId}/ads/{mobileAdId}" : { "get" : { "tags" : [ "market-health-controller" ], "summary" : "Retrieve market health for one mobileAdId", "operationId" : "getMarketHealth", "parameters" : [ { "name" : "mobileSellerId", "in" : "path", "required" : true, "schema" : { "type" : "integer", "format" : "int64" } }, { "name" : "mobileAdId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "Successfully retrieved market health", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiAdMarketHealthResponse" }, "example" : { "mobileAdId" : "987654321", "marketHealthSegment" : { "make" : "VW", "model" : "Golf", "category" : "EstateCar", "fuel" : "DIESEL", "doors" : "FOUR_OR_FIVE", "power" : 110, "gearbox" : "AUTOMATIC_GEAR", "ageBand" : "FIVE_TO_TEN" }, "weeklyMarketHealth" : [ { "weekNumber" : 1, "weekStartDate" : "2024-12-30", "year" : 2025, "priorYearWeekStartDate" : "2024-01-01", "supplyCurrentYear" : 25, "supplyPriorYear" : 7, "yoySupplyGrowth" : 257.14, "yoyDemandGrowth" : 151.63, "scaledDemandCurrentYear" : 13.26, "scaledDemandPriorYear" : 5.27, "marketHealthLabel" : "COOLING", "noLabelReason" : null }, { "weekNumber" : 2, "weekStartDate" : "2025-01-06", "year" : 2025, "priorYearWeekStartDate" : "2024-01-08", "supplyCurrentYear" : 0, "supplyPriorYear" : 7, "yoySupplyGrowth" : 257.14, "yoyDemandGrowth" : 151.63, "scaledDemandCurrentYear" : 13.26, "scaledDemandPriorYear" : 5.27, "marketHealthLabel" : null, "noLabelReason" : "TOO_FEW_COMPARABLE_CARS_IN_CURRENT_YEAR" } ] } } } }, "400" : { "description" : "Some mandatory parameters are missing or invalid", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "BAD_REQUEST", "message" : "mobileAdId is missing or invalid" } } } }, "403" : { "description" : "Forbidden – the client does not have permission to access this resource", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "FORBIDDEN", "message" : "Access Denied" } } } }, "404" : { "description" : "Requested Listing not found for the seller" }, "422" : { "description" : "The ad could not be processed due to validation errors", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "VALIDATION_ERROR", "message" : "The ad could not be processed due to validation errors.", "errorExplanations" : [ "AD_MISSING_MANDATORY_ATTRIBUTES" ] } } } }, "500" : { "description" : "Something went wrong when fetching market health", "content" : { "application/vnd.de.mobile.api+json" : { "schema" : { "$ref" : "#/components/schemas/ApiErrorResponse" }, "example" : { "errorCode" : "INTERNAL_ERROR", "message" : "Internal Server Error Occurred" } } } } } } } }, "components" : { "schemas" : { "ApiAdSearchResultPositionResponse" : { "type" : "object", "properties" : { "mobileAdId" : { "type" : "string" }, "searchResultPosition" : { "$ref" : "#/components/schemas/ApiSearchResultPosition" } }, "xml" : { "name" : "adSearchResultPositionResponse" } }, "ApiBulkAdSearchResultPositionResponse" : { "type" : "object", "properties" : { "mobileSellerId" : { "type" : "string" }, "searchResultPositions" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiAdSearchResultPositionResponse" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "bulkAdSearchResultPositionResponse" } }, "ApiSearchResultPosition" : { "type" : "object", "properties" : { "page" : { "type" : "integer", "format" : "int32" }, "position" : { "type" : "integer", "format" : "int32" }, "ranked" : { "type" : "boolean" }, "calculatedAt" : { "type" : "string" } }, "xml" : { "name" : "searchResultPosition" } }, "ApiErrorResponse" : { "type" : "object", "properties" : { "errorCode" : { "type" : "string", "enum" : [ "INTERNAL_ERROR", "FORBIDDEN", "BAD_REQUEST", "VALIDATION_ERROR", "NOT_FOUND" ] }, "message" : { "type" : "string" }, "errorExplanations" : { "type" : "array", "items" : { "type" : "string", "xml" : { "name" : "value" } }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "errorResponse" } }, "ApiAdsSalesProbabilities" : { "type" : "object", "properties" : { "mobileSellerId" : { "type" : "string" }, "adsSalesProbabilities" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiBulkAdSalesProbability" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "adsSalesProbabilities" } }, "ApiBulkAdSalesProbability" : { "type" : "object", "properties" : { "mobileAdId" : { "type" : "string" }, "salesProbabilityLabel" : { "type" : "string" }, "noProbabilityRatingReason" : { "type" : "array", "items" : { "type" : "string", "enum" : [ "AD_HAS_DAMAGED_VEHICLE", "AD_IS_OLDER_THAN_60_DAYS", "AD_IS_RESERVED", "AD_HAS_NO_PRICE_INFORMATION", "AD_IS_NOT_ACTIVE", "AD_IS_MISSING_REQUIRED_FIELD_FUEL", "AD_IS_MISSING_REQUIRED_FIELD_GEARBOX", "AD_IS_MISSING_REQUIRED_FIELD_POWER", "AD_IS_MISSING_REQUIRED_FIELD_MODEL", "AD_IS_NOT_FROM_DEALER", "AD_NOT_FOUND" ], "xml" : { "name" : "noProbabilityRatingReason" } }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "bulkAdSalesProbability" } }, "ApiAdSalesProbability" : { "type" : "object", "properties" : { "mobileAdId" : { "type" : "string" }, "salesProbabilityLabel" : { "type" : "string" } }, "xml" : { "name" : "adSalesProbability" } }, "ApiCoreFilter" : { "type" : "object", "properties" : { "filter" : { "type" : "string" }, "attribute" : { "type" : "string" }, "filterType" : { "type" : "string" }, "rank" : { "type" : "integer", "format" : "int32" }, "min" : { "type" : "integer", "format" : "int32" }, "max" : { "type" : "integer", "format" : "int32" }, "value" : { "type" : "string" }, "unit" : { "type" : "string" } }, "xml" : { "name" : "coreFilter" } }, "ApiFeatureFilter" : { "type" : "object", "properties" : { "filter" : { "type" : "string" }, "attribute" : { "type" : "string" }, "rank" : { "type" : "integer", "format" : "int32" } }, "xml" : { "name" : "featureFilter" } }, "ApiPopularSearchCriteria" : { "type" : "object", "properties" : { "coreFilters" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiCoreFilter" }, "xml" : { "wrapped" : true } }, "featureFilters" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiFeatureFilter" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "popularSearchCriteria" } }, "ApiPopularSearchCriteriaBulkResponse" : { "type" : "object", "properties" : { "mobileSellerId" : { "type" : "string" }, "popularSearchCriteria" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiPopularSearchCriteriaResponse" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "popularSearchCriteriaBulkResponse" } }, "ApiPopularSearchCriteriaResponse" : { "type" : "object", "properties" : { "mobileAdId" : { "type" : "string" }, "make" : { "type" : "string" }, "model" : { "type" : "string" }, "fuel" : { "type" : "string" }, "firstRegistrationYearMin" : { "type" : "integer", "format" : "int32" }, "firstRegistrationYearMax" : { "type" : "integer", "format" : "int32" }, "condition" : { "type" : "string" }, "noPopularSearchCriteriaReason" : { "type" : "string", "enum" : [ "FIRST_REGISTRATION_MISSING", "NO_POPULAR_SEARCH_CRITERIA_FOUND", "MODEL_MISSING" ] }, "popularSearchCriteria" : { "$ref" : "#/components/schemas/ApiPopularSearchCriteria" } }, "xml" : { "name" : "popularSearchCriteriaResponse" } }, "ApiAdPerformanceComparison" : { "type" : "object", "properties" : { "mobileAdId" : { "type" : "string" }, "performanceComparisons" : { "$ref" : "#/components/schemas/ApiPerformanceComparisons" }, "noRatingReason" : { "type" : "string", "enum" : [ "TOO_FEW_COMPETITORS", "TOO_FEW_SIMILAR_ADS", "DEMAND_NOT_FOUND", "PERFORMANCE_RATING_NOT_FOUND" ] } }, "xml" : { "name" : "adPerformanceComparison" } }, "ApiAdsPerformanceComparisons" : { "type" : "object", "properties" : { "mobileSellerId" : { "type" : "string" }, "adsPerformanceComparisons" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiAdPerformanceComparison" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "adsPerformanceComparisons" } }, "ApiPerformanceComparison" : { "type" : "object", "properties" : { "label" : { "type" : "string" } }, "xml" : { "name" : "performanceComparison" } }, "ApiPerformanceComparisons" : { "type" : "object", "properties" : { "impressionComparison" : { "$ref" : "#/components/schemas/ApiPerformanceComparison" }, "viewComparison" : { "$ref" : "#/components/schemas/ApiPerformanceComparison" }, "leadAndParkComparison" : { "$ref" : "#/components/schemas/ApiPerformanceComparison" }, "overallComparison" : { "$ref" : "#/components/schemas/ApiPerformanceComparison" } }, "xml" : { "name" : "performanceComparisons" } }, "ApiAdMarketHealthResponse" : { "type" : "object", "properties" : { "mobileAdId" : { "type" : "string" }, "marketHealthSegment" : { "$ref" : "#/components/schemas/ApiMarketHealthSegment" }, "weeklyMarketHealth" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiWeeklyMarketHealth" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "adMarketHealthResponse" } }, "ApiBulkAdMarketHealth" : { "type" : "object", "properties" : { "adId" : { "type" : "string" }, "successContent" : { "$ref" : "#/components/schemas/ApiAdMarketHealthResponse" }, "errorContent" : { "$ref" : "#/components/schemas/ApiBulkAdMarketHealthError" } }, "xml" : { "name" : "bulkAdMarketHealth" } }, "ApiBulkAdMarketHealthError" : { "type" : "object", "properties" : { "message" : { "type" : "string" }, "errors" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiBulkAdMarketHealthValidationError" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "bulkAdMarketHealthError" } }, "ApiBulkAdMarketHealthResponse" : { "type" : "object", "properties" : { "mobileSellerId" : { "type" : "string" }, "results" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/ApiBulkAdMarketHealth" }, "xml" : { "wrapped" : true } } }, "xml" : { "name" : "bulkAdMarketHealthResponse" } }, "ApiBulkAdMarketHealthValidationError" : { "type" : "object", "properties" : { "errorcode" : { "type" : "string", "enum" : [ "AD_MISSING_MAKE_OR_MODEL", "AD_MISSING_CATEGORY", "AD_IS_NOT_A_CAR", "AD_MISSING_MANDATORY_ATTRIBUTES", "AD_DETAILS_MISSING", "MARKET_HEALTH_NOT_FOUND", "INTERNAL_SERVER_ERROR" ] }, "message" : { "type" : "string" } }, "xml" : { "name" : "bulkAdMarketHealthValidationError" } }, "ApiMarketHealthSegment" : { "type" : "object", "properties" : { "make" : { "type" : "string" }, "model" : { "type" : "string" }, "category" : { "type" : "string" }, "fuel" : { "type" : "string" }, "doors" : { "type" : "string" }, "power" : { "type" : "integer", "format" : "int32" }, "gearbox" : { "type" : "string" }, "ageBand" : { "type" : "string", "enum" : [ "UP_TO_ONE", "ONE_TO_THREE", "THREE_TO_FIVE", "FIVE_TO_TEN", "TEN_PLUS" ] } }, "xml" : { "name" : "marketHealthSegment" } }, "ApiWeeklyMarketHealth" : { "type" : "object", "properties" : { "weekNumber" : { "type" : "integer", "format" : "int32" }, "weekStartDate" : { "type" : "string" }, "year" : { "type" : "integer", "format" : "int32" }, "priorYearWeekStartDate" : { "type" : "string" }, "supplyCurrentYear" : { "type" : "integer", "format" : "int32" }, "supplyPriorYear" : { "type" : "integer", "format" : "int32" }, "yoySupplyGrowth" : { "type" : "number", "format" : "double" }, "yoyDemandGrowth" : { "type" : "number", "format" : "double" }, "scaledDemandCurrentYear" : { "type" : "number", "format" : "double" }, "scaledDemandPriorYear" : { "type" : "number", "format" : "double" }, "marketHealthLabel" : { "type" : "string", "enum" : [ "NO_LABEL", "COLD", "COOLING", "STABLE", "WARMING", "HOT" ] }, "noLabelReason" : { "type" : "string", "enum" : [ "TOO_FEW_COMPARABLE_CARS_IN_PREVIOUS_YEAR", "TOO_FEW_COMPARABLE_CARS_IN_CURRENT_YEAR" ] } }, "xml" : { "name" : "weeklyMarketHealth" } } }, "securitySchemes" : { "basicAuth" : { "type" : "http", "scheme" : "basic" } } }, "security" : [ { "basicAuth" : [ ] } ] }