REST API

Account Setup TOP ↑

Bilweb's Web Service (BWService) is a RESTful API which provides pragmatic access to upload and fetch vehicle objects from bilweb.se

API Key

Every call to BWService API requires a valid API-KEY to be present in request headers. To get your API key, please contact us at erik@bilweb.se.

API key must be sent in a custom request header as follows:

header BW-API-KEY
value YOUR_API_KEY
Example
POST /bwservice/api/vehicle HTTP/1.1
Host: bilweb.se
BW-API-KEY: YOUR_API_KEY

Endpoints

Here's a list of API endpoints/calls you can make:

Environments/Modes

You can use BWService API in both test and live modes at the same time.

Here are the URL prefixes to access the API:

Test Mode http://test.bilweb.se/bwservice/api
Live Mode https://bilweb.se/bwservice/api

Matching Car Dealer Locations

To be able to post vehicles to the correct car dealer we need to match car dealer locations. Bilweb's webservice provides two options on matching car dealers.

  • A: You can use Bilwebs location_id, in this case we will give you our locations ids and you need to send our id with the vehicle post.
  • B: You can use your own location ids, in this case you have to provide Bilweb your car dealers with ids and you'll send your ids with vehicle post

Upload Vehicle TOP ↑

Title Upload Vehicle
  • Add/Update a vehicle
  • Upload one vehicle at a time
URL /vehicle
Method POST
URL Params None
Data Params
location_id
required		 string A unique identifier for cardealer's location. There are two options for location_id as:
  • A. Internal location_id: Bilweb uses its own location_id internally. So using this option means supplier will be using Bilweb's location_id to refer a unique location.
  • B. External location_id: If supplier manages location_id externally in its own system and want to use that location_id instead of Bilweb's location_id then he should use this option.

For more details refer to Matching Car Dealer Locations
vehicle_id
required		 string A unique identifier of the vehicle from external system. vehicle_id will be used to refer to this vehicle later, to fetch the vehicle for example
registration_number
required		 string(6) Unique registration number of the vehicle in valid format.
  • FORMAT: A valid registration number starts with 3 alphabets following the 3 digits, making a total length equals 6
  • EXAMPLE: ABC123

Possible Errors:

  • 1000 Missing Required Field!
  • 1100 Invalid Field!
brand
required		 string Brand name of vehicle.

Possible Errors:

  • 1000 Missing Required Field!
model
required		 string Model name of vehicle.

Possible Errors:

  • 1000 Missing Required Field!
version
optional		 string Vehicle version (or model extra)
model_year
optional		 integer 4-digit Model year of vehicle
mileage
required		 integer Mileage value in mil
price
required		 float Vehicle price
discounted_price
optional		 float Discounted (or red) price
colour
required		 string colour can be any of the following comma separated values:

Blå, Lila, Röd, Orange, Gul, Grön, Brun, Svart, Grå, Silver, or Vit
gear_box
required		 string gear_box can be any of the following comma separated values:

Automatisk, Manuell, or Sekventiell
fuel
required		 string fuel can be any of the following comma separated values:

Bensin, Diesel, Bensin/etanol, El, Hybrid el/bensin, Bensin/gas, Naturgas
body
required		 string body can be any of the following comma separated values:

4-hjuling, Båttrailer, Cab, Cross/Enduro/Trial, Halvkombi, Hästsläp, Husbil, Kombi, MC/Moped, Minibuss, Moped/EU-Moped, Offroad, Övrigt, Personbil, Personvagnssläp, Pickup, Scooter, Sedan, Sidovagn-Släp, Snöskoter, Sport, Sportkupé, SuperMotard, SUV, Transportbil, Trike
equipment
optional		 string Comma separated list of features, for example, Avdragbar moms, AC, PDC, Elhissar, Elspeglar, Elcab, Färddator, Läderratt, Antispin, Fjärrlås, Airbags, Servo, Original CD-stereo, ABS etc.
first_registration_date
optional		 string First registration date in the format yyyy/mm/dd
fuel_consumption
optional		 float Fuel consumption value in l / m
emission_co2
optional		 integer Emission CO2 value in g / km
horse_power
optional		 integer Engine horse power (hp)
engine_size
optional		 integer Engine Size ini ccm
doors
optional		 integer Number of doors
seats
optional		 integer Number of seats
description
optional		 string Selling description of the vehicle
sales_person_name
optional		 string Name of the sales person
sales_person_email
optional		 string Email address of the sales person
sales_person_phone
optional		 string Phone number of the sales person
is_green
optional		 boolean 1, if its a green vehicle, otherwise 0
is_deductible
optional		 boolean 1, if vehicle price is deductible, otherwise 0
supplier_gaurantee
optional		 string Supplier gaurantee if any
images
optional		 array Array of vehicle images either. An image can either be a URL or Base64-Encoded string
supplier_specific1
optional		 string Supplier specific custom data 1
supplier_specific2
optional		 string Supplier specific custom data 2
supplier_specific3
optional		 string Supplier specific custom data 3

Example:

{
 location_id: '123456',
 vehicle_id: '112233',
 registration_number: 'ABC123',
 brand: 'Volvo',
 model: 'V70',
 verson: 'D2 Momentum Värmare',
 model_year: 2010,
 mileage: 4000,
 price: 80000.5,
 discounted_price: 75000.5,
 colour: 'Blå metallic',
 gear_box: 'Automatisk',
 fuel: 'Bensin',
 body: 'Sedan',
 equipment: 'Avdragbar moms, AC, PDC, Elhissar, Elspeglar',
 first_registration_date: '2010/10/25',
 fuel_consumption: 10.5,
 emission_co2: 169,
 hp: 390,
 engine_size: '',
 doors: 4,
 seats: 4,
 description: 'selling description of the vehicle',
 sales_person_name: 'Abraham',
 sales_person_email: 'salesperson@xyz.com',
 sales_person_phone: '333-333-4444',
 is_green: 1,
 is_deductible: 0,
 supplier_gaurantee: 'Supplier gaurantee if any',
 images: {
  'http://yourserver.com/images/veh456_1.jpg',
  'http://yourserver.com/images/veh456_2.jpg',
  'http://yourserver.com/images/veh456_3.jpg'
 },
 supplier_specific1: 'Supplier specific custom data 1',
 supplier_specific2: 'Supplier specific custom data 2',
 supplier_specific3: 'Supplier specific custom data 3'
}
Success Response

Example:

HTTP Response Code: 200
Content: { status: 'Published', url: 'https://bilweb.se/VEHICLE_URL', warning(s): 'warning messages, if any'}
OR

Content: { status: 'Under Review', warning(s): 'warning messages, if any'}
Error Response

Example:

HTTP Response Code: 400 BAD REQUEST
Content: { errorCode: 1000, message: 'Missing Required Field!', field: 'brand', more_info: 'Required field is either missing or empty.' }

Possible errorCodes

errorCode HTTP Response Code messgae more_info
1003 403 Account Not Setup! Your account is not setup. Please contact us at erik@bilweb.se to check your account status.
1000 400 Missing Required Fields! Required field is either missing or empty.
1100 400 Invalid Field! doesn't match the correct format. Please check API documentation (https://bilweb.se/bwservice) to find the correct format.
1200 400 Field DOES NOT MATCH! No match found for provided field value.
Sample Call 
 $.ajax({
  url: "/vehicle",
  dataType: "json",
  data : { 
	location_id: 'LOC123',
	vehicle_id: 'veh456',
	registration_number: 'ABCXYZ',
	brand: 'Volvo',
	model: 'V70',
	verson: 'D2 Momentum Värmare',
	model_year: 2010,
	mileage: 4000,
	price: 80000.5,
	discounted_price: 75000.5,
	colour: 'Blå metallic',
	gear_box: 'Automatisk',
	fuel: 'Bensin',
	body: 'Sedan',
	equipment: 'Avdragbar moms, AC, PDC, Elhissar, Elspeglar',
	first_registration_date: '2010/10/25',
	fuel_consumption: 10.5,
	emission_co2: 169,
	hp: 390,
	engine_size: '',
	doors: 4,
	seats: 4,
	description: 'selling description of the vehicle',
	sales_person_name: 'Abraham',
	sales_person_email: 'salesperson@xyz.com',
	sales_person_phone: '333-333-4444',
	is_green: 1,
	is_deductible: 0,
	supplier_gaurantee: 'Supplier gaurantee if any',
	images: {
		'http://yourserver.com/images/veh456_1.jpg',
		'http://yourserver.com/images/veh456_2.jpg',
		'http://yourserver.com/images/veh456_3.jpg'
	},
	supplier_specific1: 'Supplier specific custom data 1',
	supplier_specific2: 'Supplier specific custom data 2',
	supplier_specific3: 'Supplier specific custom data 3'
 },
  type : "POST",
  success : function(r) {
  console.log(r);
 }
});
Notes
  • All parameters flagged with Must Be Matched, if they don't match their corresponding values on Bilweb.se then vehicle object will be put Under Review and it will not be Published until we manually review match it with a correct value.
  • You can always check the status and URL of vehicle using Fetch Single Vehicle to see if your vehicle review is completed and its status is changed to Published

Fetch Single Vehicle TOP ↑

Title Fetch Vehicle
  • Fetches vehicle object by id if it exists, otherwise gives an error
URL /vehicle/id/:id or /vehicle?id=:id
Method GET
URL Params
id
required		 string Unique vehicle id that was used while uploading the vehicle. For example id=veh456
Data Params None
Success Response HTTP Response Code: 200
Content:
{
 location_id: '123456',
 vehicle_id: '112233',
 registration_number: 'ABC123',
 brand: 'Volvo',
 model: 'V70',
 verson: 'D2 Momentum Värmare',
 model_year: 2010,
 mileage: 4000,
 price: 80000.5,
 discounted_price: 75000.5,
 colour: 'Blå metallic',
 gear_box: 'Automatisk',
 fuel: 'Bensin',
 body: 'Sedan',
 equipment: 'Avdragbar moms, AC, PDC, Elhissar, Elspeglar',
 first_registration_date: '2010/10/25',
 fuel_consumption: 10.5,
 emission_co2: 169,
 hp: 390,
 engine_size: '',
 doors: 4,
 seats: 4,
 description: 'selling description of the vehicle',
 sales_person_name: 'Abraham',
 sales_person_email: 'salesperson@xyz.com',
 sales_person_phone: '333-333-4444',
 is_green: 1,
 is_deductible: 0,
 supplier_gaurantee: 'Supplier gaurantee if any',
 images: {
  'https://bilweb.se/image_1.jpg',
  'https://bilweb.se/image_2.jpg',
  'https://bilweb.se/image_3.jpg',
 },
 supplier_specific1: 'Supplier specific custom data 1',
 supplier_specific2: 'Supplier specific custom data 2',
 supplier_specific3: 'Supplier specific custom data 3'
 status: 'Published',
 url: 'https://bilweb.se/VEHICLE_URL_ON_BILWEB'
}
Error Response HTTP Response Code: 400 BAD REQUEST
Content: { errorCode: 1000, message: 'Missing Required Parameter!', more_info: 'Required Parameter is either missing or its empty' }

OR

HTTP Response Code: 404 NOT FOUND
Content: { errorCode: 1004, message: 'Vehicle Not Found!', more_info: 'No vehicle found for given vehicle_id. Please verify if you're sending the correct vehicle_id' }
Sample Call GET
/vehicle/id/veh456
Notes This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.

Fetch Vehicle's List TOP ↑

Title Fetch Vehicle's List
  • Fetches list of vehicles if present, otherwise gives an error
  • Limit and offset parameters can be used to fetch the required vehciles
  • Vehicles can be sorted while fetching
  • 10 vehicles are fetched by default sorted by 'date' in descending order of their last updated date
URL /vehicles or /vehicles?limit=10&offset=20&sort_by=price&sort_direction=asc
Method GET
URL Params
limit
optional		 integer Number of vehicles to fetch
offset
optional		 integer Position of vehicle in the sorted vehicles list from where to start fetching
sort_by
optional		 string Name of sort by field. Vehicles can be sorted by vehicle_id, registration_number, model_year and price
sort_direction
optional		 string 'asc' or 'desc' accordingly as ascending and descending sort order
Data Params None
Success Response HTTP Response Code: 200
Content: 
{
	totalVehicles: 'TOTAL VEHICLES INVENTORY',
	offset: 'OFFSET VALUE',
	limit: 'NUMBER OF VEHICLES FETCHED',
	sort_by: 'SORT BY FIELD NAME',
	sort_direction: 'asc OR desc',
	vehciles: 'LIST OF VEHICLE OBJECTS'
}

See Vehicle Object
Error Response Code: 400 BAD REQUEST
Content: { errorCode: 1104, message: 'No Vehicle Inventory!', more_info: 'Sorry, we couldn't find any vehicle. It looks you have not uploaded a vehicle yet.' }
Sample Call GET
/vehicle/veh456
Notes This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.

Delete Vehicle TOP ↑

Title Delete Vehicle
  • Deletes vehicle object by id if it exists, otherwise gives an error
URL /vehicle/id/:id or /vehicle?id=:id
Method DELETE
URL Params
id
required		 string Unique vehicle id that was used while uploading the vehicle. For example id=veh456
Data Params None
Success Response HTTP Response Code: 200
Content:
{
 message: Vehicle (id) has been successfully deleted.
}
Error Response HTTP Response Code: 400 BAD REQUEST
Content: { errorCode: 1000, message: 'Missing Required Parameter!', more_info: 'Required Parameter is either missing or its empty' }

OR

HTTP Response Code: 404 NOT FOUND
Content: { errorCode: 1004, message: 'Vehicle Not Found!', more_info: 'No vehicle found for given vehicle_id. Please verify if you're sending the correct vehicle_id' }
Sample Call DELETE
/vehicle/id/veh456
Notes This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.

Fetch All Brands TOP ↑

Title Fetch Brands
  • Fetches all brands.
URL /brands
Method GET
URL Params None
Data Params None
Success Response HTTP Response Code: 200
Content:
{
  "brands": [
    {
      "name": "Alfa Romeo"
    },
    {
      "name": "Aston Martin"
    },
    {
      "name": "Audi"
    },
    {
      "name": "Bentley"
    },
    {
      "name": "BMW"
    },
    {
      "name": "Cadillac"
    },
    {
      "name": "Chevrolet"
    },
    {
      "name": "Chrysler"
    },
    {
      "name": "Citroen"
    },
    {
      "name": "Daewoo"
    },
    {
      "name": "Daihatsu"
    },
    {
      "name": "Dodge"
    },
    {
      "name": "Ferrari"
    },
    .....
  ]
}
Error Response None
Sample Call GET
/brands
Notes This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.

Fetch Models By Brand TOP ↑

Title Fetch Models By Brand
  • Fetches all models of brandname if it exists, otherwise gives an error
URL /models/brandname/:brandname
Method GET
URL Params
brandname
required		 string Unique brand name. For example brandname=Audi
Data Params None
Success Response HTTP Response Code: 200
Content:
{
  "models": [
    {
      "name": "A8"
    },
    {
      "name": "S3"
    },
    {
      "name": "S4"
    },
    {
      "name": "S8"
    },
    {
      "name": "S6"
    },
    {
      "name": "A2"
    },
    {
      "name": "RS4"
    },
    {
      "name": "90"
    },
    {
      "name": "V8"
    },
    {
      "name": "RS6"
    },
    {
      "name": "Q7"
    },
    {
      "name": "Allroad"
    },
    .....
  ]
}
Error Response None
Sample Call HTTP Response Code: 400 BAD REQUEST
Content: { errorCode: 1000, message: 'Missing Required Parameter!', more_info: 'Required Parameter is either missing or its empty' }

OR

HTTP Response Code: 404 NOT FOUND
Content: { errorCode: 1004, message: 'Models Not Found!', more_info: 'No Models found for given brand name. Please verify if you're sending the correct brand name' }
Notes This is where all uncertainties, commentary, discussion etc. can go. I recommend timestamping and identifying oneself when leaving comments here.