Dubizzle Motors API Reference

Complete API documentation for extracting real-time automotive data from the Middle East's leading marketplace.

Quick Navigation

Authentication - API key setup and usage
Search Endpoints - Vehicle search and filtering
Vehicle Details - Individual vehicle information
Market Data - Market trends and analytics
Error Handling - Common errors and solutions

Authentication

API Key Setup

All requests to the Dubizzle Motors API require authentication using an API key.

API Key Format

dubizzle_parser_sk_1234567890abcdef1234567890abcdef

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
User-Agent: YourApp/1.0

Base URL

https://api.carapis.com/v1/dubizzle

Search Endpoints

Search Vehicles

Search for vehicles with various filters and criteria.

Endpoint: GET /search

Request Parameters

Parameter	Type	Required	Description
`make`	string	No	Vehicle make (e.g., "Toyota", "BMW")
`model`	string	No	Vehicle model (e.g., "Camry", "X5")
`year_min`	integer	No	Minimum year (e.g., 2020)
`year_max`	integer	No	Maximum year (e.g., 2023)
`price_min`	integer	No	Minimum price in local currency
`price_max`	integer	No	Maximum price in local currency
`country`	string	No	Country code (e.g., "UAE", "SA")
`city`	string	No	City name (e.g., "Dubai", "Riyadh")
`vehicle_type`	string	No	Vehicle type (sedan, suv, truck, etc.)
`transmission`	string	No	Transmission type (automatic, manual)
`fuel_type`	string	No	Fuel type (gasoline, diesel, hybrid, electric)
`condition`	string	No	Vehicle condition (new, used, certified)
`mileage_min`	integer	No	Minimum mileage
`mileage_max`	integer	No	Maximum mileage
`features`	array	No	Array of features (e.g., ["leather_seats", "sunroof"])
`limit`	integer	No	Number of results (default: 10, max: 100)
`page`	integer	No	Page number (default: 1)
`sort_by`	string	No	Sort field (price_asc, price_desc, year_desc, mileage_asc)

Example Request:

curl -X GET "https://api.carapis.com/v1/dubizzle/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "make=Toyota" \
  -d "model=Camry" \
  -d "country=UAE" \
  -d "year_min=2020" \
  -d "price_max=100000" \
  -d "limit=20"

Example Response:

{
  "results": [
    {
      "id": "dubizzle_12345",
      "title": "2022 Toyota Camry XSE",
      "make": "Toyota",
      "model": "Camry",
      "year": 2022,
      "trim": "XSE",
      "price": 85000,
      "currency": "AED",
      "mileage": 15000,
      "location": {
        "country": "UAE",
        "city": "Dubai",
        "area": "Dubai Marina"
      },
      "specifications": {
        "engine": "2.5L 4-Cylinder",
        "transmission": "Automatic",
        "fuel_type": "Gasoline",
        "color": "Pearl White"
      },
      "features": ["Leather Seats", "Navigation", "Bluetooth"],
      "images": ["https://example.com/image1.jpg"],
      "seller": {
        "name": "Dubai Auto Gallery",
        "type": "dealer",
        "rating": 4.8
      },
      "url": "https://dubizzle.com/vehicle/12345",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "has_more": true
}

Advanced Search

Perform complex searches with multiple criteria.

Endpoint: POST /search/advanced

Request Body

{
  "filters": {
    "make": ["Toyota", "Honda"],
    "model": ["Camry", "Accord"],
    "year_range": { "min": 2020, "max": 2023 },
    "price_range": { "min": 50000, "max": 150000 },
    "location": {
      "countries": ["UAE", "Saudi Arabia"],
      "cities": ["Dubai", "Riyadh"]
    },
    "features": ["leather_seats", "sunroof", "navigation"],
    "condition": "used"
  },
  "sorting": {
    "field": "price",
    "order": "asc"
  },
  "pagination": {
    "page": 1,
    "limit": 50
  }
}

Vehicle Details

Get Vehicle Details

Retrieve detailed information for a specific vehicle.

Endpoint: GET /vehicle/\{vehicle_id\}

Example Request:

curl -X GET "https://api.carapis.com/v1/dubizzle/vehicle/dubizzle_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "id": "dubizzle_12345",
  "title": "2022 Toyota Camry XSE",
  "make": "Toyota",
  "model": "Camry",
  "year": 2022,
  "trim": "XSE",
  "vin": "1HGBH41JXMN109186",
  "price": 85000,
  "currency": "AED",
  "original_price": 95000,
  "price_history": [
    { "date": "2024-01-01", "price": 95000 },
    { "date": "2024-01-15", "price": 85000 }
  ],
  "mileage": 15000,
  "mileage_unit": "km",
  "location": {
    "country": "UAE",
    "city": "Dubai",
    "area": "Dubai Marina",
    "coordinates": { "lat": 25.0921, "lng": 55.1381 }
  },
  "specifications": {
    "engine": {
      "size": "2.5L",
      "cylinders": 4,
      "type": "Gasoline",
      "power": "203 hp",
      "torque": "184 lb-ft"
    },
    "transmission": {
      "type": "Automatic",
      "speeds": 8
    },
    "fuel_type": "Gasoline",
    "fuel_economy": {
      "city": "8.5 L/100km",
      "highway": "6.2 L/100km"
    },
    "exterior": {
      "color": "Pearl White",
      "body_style": "Sedan",
      "doors": 4
    },
    "interior": {
      "color": "Black",
      "seats": 5,
      "upholstery": "Leather"
    }
  },
  "features": ["Leather Seats", "Navigation System", "Bluetooth Connectivity", "Sunroof", "Backup Camera", "Blind Spot Monitor", "Lane Departure Warning"],
  "safety_features": ["ABS", "Traction Control", "Stability Control", "Airbags", "Child Safety Locks"],
  "images": [
    {
      "url": "https://example.com/image1.jpg",
      "type": "exterior",
      "alt": "Front view"
    },
    {
      "url": "https://example.com/image2.jpg",
      "type": "interior",
      "alt": "Dashboard"
    }
  ],
  "seller": {
    "id": "seller_123",
    "name": "Dubai Auto Gallery",
    "type": "dealer",
    "rating": 4.8,
    "reviews_count": 125,
    "contact": {
      "phone": "+971-50-123-4567",
      "email": "info@dubaiautogallery.com"
    },
    "location": {
      "address": "Sheikh Zayed Road, Dubai",
      "coordinates": { "lat": 25.0921, "lng": 55.1381 }
    }
  },
  "description": "Excellent condition 2022 Toyota Camry XSE...",
  "url": "https://dubizzle.com/vehicle/12345",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Market Data

Get Market Trends

Retrieve market trends and analytics data.

Endpoint: GET /market/trends

Request Parameters

Parameter	Type	Required	Description
`country`	string	No	Country code for regional trends
`make`	string	No	Vehicle make for brand-specific trends
`model`	string	No	Vehicle model for model-specific trends
`period`	string	No	Time period (week, month, quarter, year)
`metric`	string	No	Metric type (price, volume, demand)

Example Request:

curl -X GET "https://api.carapis.com/v1/dubizzle/market/trends" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "country=UAE" \
  -d "make=Toyota" \
  -d "period=month"

Example Response:

{
  "country": "UAE",
  "make": "Toyota",
  "period": "month",
  "trends": {
    "price_trends": [
      {
        "date": "2024-01-01",
        "average_price": 75000,
        "median_price": 72000,
        "volume": 150
      },
      {
        "date": "2024-01-15",
        "average_price": 78000,
        "median_price": 75000,
        "volume": 165
      }
    ],
    "popular_models": [
      { "model": "Camry", "volume": 45, "avg_price": 82000 },
      { "model": "Land Cruiser", "volume": 32, "avg_price": 280000 },
      { "model": "Corolla", "volume": 28, "avg_price": 65000 }
    ],
    "market_summary": {
      "total_listings": 1250,
      "average_price": 78000,
      "price_change": 4.0,
      "volume_change": 10.0
    }
  }
}

Get Popular Vehicles

Get the most popular vehicles in a region.

Endpoint: GET /market/popular

Example Request:

curl -X GET "https://api.carapis.com/v1/dubizzle/market/popular" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "country=UAE" \
  -d "limit=10"

Example Response:

{
  "country": "UAE",
  "period": "last_30_days",
  "popular_vehicles": [
    {
      "make": "Toyota",
      "model": "Camry",
      "volume": 245,
      "average_price": 82000,
      "trend": "increasing"
    },
    {
      "make": "BMW",
      "model": "X5",
      "volume": 189,
      "average_price": 320000,
      "trend": "stable"
    }
  ]
}

Utility Endpoints

Get Available Makes

Retrieve list of available vehicle makes.

Endpoint: GET /makes

Example Request:

curl -X GET "https://api.carapis.com/v1/dubizzle/makes" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "makes": [
    {
      "name": "Toyota",
      "count": 1250,
      "popular_models": ["Camry", "Land Cruiser", "Corolla"]
    },
    {
      "name": "BMW",
      "count": 890,
      "popular_models": ["X5", "3 Series", "5 Series"]
    }
  ]
}

Get Available Models

Retrieve models for a specific make.

Endpoint: GET /makes/\{make\}/models

Example Request:

curl -X GET "https://api.carapis.com/v1/dubizzle/makes/Toyota/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "make": "Toyota",
  "models": [
    {
      "name": "Camry",
      "count": 245,
      "years": [2018, 2019, 2020, 2021, 2022, 2023]
    },
    {
      "name": "Land Cruiser",
      "count": 156,
      "years": [2019, 2020, 2021, 2022, 2023]
    }
  ]
}

Get Supported Countries

Retrieve list of supported countries and cities.

Endpoint: GET /locations

Example Response:

{
  "countries": [
    {
      "code": "UAE",
      "name": "United Arab Emirates",
      "cities": [
        { "name": "Dubai", "count": 4500 },
        { "name": "Abu Dhabi", "count": 3200 },
        { "name": "Sharjah", "count": 1800 }
      ]
    },
    {
      "code": "SA",
      "name": "Saudi Arabia",
      "cities": [
        { "name": "Riyadh", "count": 3800 },
        { "name": "Jeddah", "count": 2900 },
        { "name": "Dammam", "count": 2100 }
      ]
    }
  ]
}

Error Handling

HTTP Status Codes

Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 100,
      "reset_time": "2024-01-15T11:00:00Z"
    }
  }
}

Common Error Codes

Common Errors

Error Code	Description	Solution
`INVALID_API_KEY`	API key is invalid or expired	Check your API key
`RATE_LIMIT_EXCEEDED`	Too many requests	Implement rate limiting
`INVALID_PARAMETERS`	Request parameters are invalid	Check parameter values
`RESOURCE_NOT_FOUND`	Requested resource doesn't exist	Verify resource ID
`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry later

Rate Limiting

Rate Limits by Plan

Rate Limits

Plan	Requests/Second	Requests/Minute	Requests/Hour
Starter	5	100	1,000
Professional	10	500	5,000
Enterprise	50	2,000	20,000

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642233600

Code Examples

Python SDK

import requests

class DubizzleAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.carapis.com/v1/dubizzle"
        self.headers = {"Authorization": f"Bearer \{api_key\}"}

    def search_vehicles(self, **params):
        response = requests.get(f"{self.base_url}/search",
            params=params, headers=self.headers)
        return response.json()

    def get_vehicle(self, vehicle_id):
        response = requests.get(f"{self.base_url}/vehicle/\{vehicle_id\}",
            headers=self.headers)
        return response.json()

    def get_market_trends(self, **params):
        response = requests.get(f"{self.base_url}/market/trends",
            params=params, headers=self.headers)
        return response.json()

# Usage
api = DubizzleAPI("YOUR_API_KEY")
vehicles = api.search_vehicles(make="Toyota", country="UAE", limit=10)

JavaScript SDK

class DubizzleAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.carapis.com/v1/dubizzle';
    this.headers = {
      Authorization: `Bearer $\{apiKey\}`,
      'Content-Type': 'application/json',
    };
  }

  async searchVehicles(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseUrl}/search?$\{queryString\}`, {
      headers: this.headers,
    });
    return response.json();
  }

  async getVehicle(vehicleId) {
    const response = await fetch(`${this.baseUrl}/vehicle/$\{vehicleId\}`, {
      headers: this.headers,
    });
    return response.json();
  }

  async getMarketTrends(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseUrl}/market/trends?$\{queryString\}`, {
      headers: this.headers,
    });
    return response.json();
  }
}

// Usage
const api = new DubizzleAPI('YOUR_API_KEY');
const vehicles = await api.searchVehicles({ make: 'Toyota', country: 'UAE', limit: 10 });

Next Steps

Continue Learning

Quick Start Guide - Get started in minutes
Market Analysis - Regional insights
FAQ - Common questions and solutions
Examples - More code examples

Need Help?

Documentation - Complete setup guide
Support - Technical assistance
Community - Connect with other users
Status - Check service status

Ready to integrate the Dubizzle Motors API into your application? Start building with our comprehensive API reference and code examples.

Get Started Now →

Authentication​

API Key Setup​

Request Headers​

Base URL​

Search Endpoints​

Search Vehicles​

Advanced Search​

Vehicle Details​

Get Vehicle Details​

Market Data​

Get Market Trends​

Get Popular Vehicles​

Utility Endpoints​

Get Available Makes​

Get Available Models​

Get Supported Countries​

Error Handling​

HTTP Status Codes​

Error Response Format​

Common Error Codes​

Rate Limiting​

Rate Limits by Plan​

Rate Limit Headers​

Code Examples​

Python SDK​

JavaScript SDK​

Next Steps​

Authentication

API Key Setup

Request Headers

Base URL

Search Endpoints

Search Vehicles

Advanced Search

Vehicle Details

Get Vehicle Details

Market Data

Get Market Trends

Get Popular Vehicles

Utility Endpoints

Get Available Makes

Get Available Models

Get Supported Countries

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Rate Limiting

Rate Limits by Plan

Rate Limit Headers

Code Examples

Python SDK

JavaScript SDK

Next Steps