Publish an API for Carsales Data (Used to Import Vehicle)

API for Carsales Data Overview

We will publish the API for Carsales to post their data. When Carsales get an update on a vehicle, they call us and we get the new data. We want to process directly into the data tables, not use a CSV file.

We also need to understand how images are handled. We want the images on our server, not linking to images on Carsales.

Import vehicle via JSON files

As we know, we already have a feature to import vehicles via files (CSV, TSV). With the current import function, we process the files (import files and image files) imported by User via FTP. Regarding the new request from Carsales, they will be using our publish API to POST the Vehicle-Json files, our system will process these JSON files to get Vehicle Information and Vehicle Images.

I went through the original Import Vehicle function to get the workflow and check if we can reuse the original function. The answer here's, we cannot reuse the original functions because of these things:

  • Structure objects are different: Original functions is using files and process line by line. Vehicle-Json is an object and it's included child objects.
  • Vehicle's Images: Original functions handler manual upload by User. Vehicle-JSON, we need to download the image via URL in a JSON file
  • We don't want to affect the original function which using on live sites.

New function Import vehicle via JSON files

Based on the idea above, I would like to suggest the new import functions which will handle JSON files (vehicle information and Images).

  • Define API, log request, log response
  • Define security API (basic authentication, spam,...)
  • Mapping JSON data to WebEd object for import vehicles
  • Handler import functions (need to create the new function for import)
  • Handler downloads images and Mapping with vehicle (download and convert to WebP)

We separate the import function, but we still keep the same goal "Vehicle Import Correctly and Vehicle's Image correctly"

Summary of the Original Import Workflow:

  • Write log import
  • Get vehicle site setting
  • Move file upload to process
  • Get dealer name
  • Get dealer state
  • Import vehicle from file to VehicleLogs tables
    • Loop all file
    • Read line by line
    • Check stocknumber exist
    • Update/insert VehicleLogs
    • Check and update vehicle images
    • Output total records, start index - end index
  • Move vehicles from VehicleLogs to Vehicles
  • Clean up the VehicleLogs
  • Convert WebP for all uploaded images

New function Import Vehicle Flowchart

Content to follow.

Vehicle-JSON mapping files

When I compared the vehicle-json with Import CSV/TSV fields, I found that's many fields that have not been included on the JSON. Here's a summary, the field with a question mark does not exist on JSON

StockNo - Identification- StockNumber
DealerCode - Seller- Identification - LegacyId
ManuYear → BuildDate → Year
Make - Specification.Make
Model - Specification.Model
Series - Specification.Series
Badge - Specification.Attributes.Badge
Body - Specification.Attributes.Body
Doors - Specification.Attributes.Doors
Seats - Specification.Attributes.Seats
BodyColour - see Colours Exterior
TrimColour - see Colours Interior
Gears - Specification.Attributes.Gears
Gearbox - Specification.Attributes.Transmission
FuelType - Specification.Attributes.FuelType
Retail - SaleType? see ListingType, SaleStatus & SaleType
Rego - see Registration
Odometer - OdometerReadings
Cylinders - see Specification Attributes Cylinders
EngineCapacity - see Specification Attributes EngineSize
VINNumber - see Identification VIN
EngineNumber - n/a. Not a value we have to provide
ManuMonth - BuildDate → Month
Options - Detailed vehicle options are only provided to RedBook subscribers
Comments - see Description
NVIC - We only use RedBook data, see Specification SpecificationCode
IsDemo - see ListingType, if the vehicle is an applicable selected demonstrator, it will be sent with "Demo".
DriveAwayPrice - see PriceList DAP
PorscheCertification - if applicable see Certifications
NUD - n/a
OriginalPrice - n/a. we only supply the vehicles listed price, ee PriceList EGC&DAP

IsApproved → With regards to the approved certification, if the vehicle is flagged, it will be included within the "Certifications" fields, the example provided notes "Porsche Approved Vehicle".


Based on the breakdown list above, I would like to update the estimation:

  • Define API, log request, and log response (3 hours)
  • Define security API (basic authentication, spam,...) (2 hours)
  • Mapping JSON data to WebEd object for import vehicles: define model objects for mapping (2.5 hours)
  • Handler import functions (need to create the new function for import) (10 hours)
  • Handler downloads images and Mapping with vehicle (download and convert to webp) (8 hours)
  • Test and deployment to the test site ( 1.5 hours)
  • Create task document: requirement, flowchart, mapping,... on confluence page (2.5 hours)
  • Create APIs Document (2.5 hours)
  • Create APIs test plan, and test video (3 hours)

Clarifications and Questions

Send an email to Carsales for these things:

1- Need confirmation with Carsales. Are there any changes on the JSON file (10 months ago) that they send us?

2- Every dealer will have a published API URL base on that dealer.


3- Request Carsales for more Vehicle-Json. We need more JSON for testing.

Update from Carsales (21 Jul 21): "Vehicles are sent individually per transaction"

APIs Documentation

Please find attached the documentation of one of our APIs

We are using postman to call API. Please download and install postman, then use the account below:


Password: gpz110000