Bid.Cars VIN Lookup API

A Flask-based REST API for looking up vehicle auction data from bid.cars using VIN (Vehicle Identification Number).

Features

• Single VIN lookup
• Batch VIN lookup (up to 100 VINs)
• Comprehensive vehicle data extraction including:
  • Vehicle specifications (year, make, model, engine, transmission, etc.)
  • Auction details (dates, location, seller)
  • Damage and condition information
  • Pricing (final bid, ACV, ERC)
  • Photo URLs

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation

1. Clone the repository:

git clone https://github.com/AhsanRiaz786/bid.cars-api
cd bid.cars-api

2. Create a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Usage

Starting the Server

python server.py

The API will start on http://0.0.0.0:8000 (accessible on http://127.0.0.1:8000 locally).

API Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "service": "VIN Lookup API",
  "version": "1.0"
}

Single VIN Lookup

GET /api/lookup?vin=4JGDA5HB8HA881503

Response (Success):

{
  "success": true,
  "vin": "4JGDA5HB8HA881503",
  "lookup_url": "https://bid.cars/en/lot/0-43890783/...",
  "data": {
    "url": "...",
    "lot": "0-43890783",
    "lot_id": 43890783,
    "auction": "iaai",
    "title": "2017 Mercedes-Benz GLE 350",
    "vin": "4JGDA5HB8HA881503",
    "year": 2017,
    "make": "Mercedes-Benz",
    "model": "GLE 350",
    ...
  }
}

Response (Error):

{
  "error": "vin_not_found",
  "message": "VIN not found in bid.cars database",
  "vin": "4JGDA5HB8HA881503"
}

Batch VIN Lookup

POST /api/batch
Content-Type: application/json

{
  "vins": ["VIN1", "VIN2", "VIN3"]
}

Response:

{
  "total": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "vin": "VIN1",
      "success": true,
      "url": "...",
      "data": {...}
    },
    ...
  ]
}

VIN Format

VINs must be 17 alphanumeric characters, excluding I, O, and Q (standard VIN format).

Deployment

Production Considerations

For production deployment, use a production WSGI server such as:

• Gunicorn:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 server:app

• uWSGI:

pip install uwsgi
uwsgi --http 0.0.0.0:8000 --wsgi-file server.py --callable app

Environment Variables

Currently, no environment variables are required. The API uses default configurations.

Docker (Optional)

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "server:app"]

Build and run:

docker build -t bid-cars-api .
docker run -p 8000:8000 bid-cars-api

Error Handling

The API returns appropriate HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid VIN format, missing parameters)
• 404 - Not Found (VIN not found in database)
• 500 - Server Error (scraping failed, parsing error)

Project Structure

bid.cars-api/
├── server.py          # Flask API server
├── parser.py          # HTML parser for bid.cars pages
├── requirements.txt   # Python dependencies
├── README.md         # This file
└── .gitignore        # Git ignore rules