Carsome.com API Reference - Complete Endpoint Documentation

Complete API documentation for Carsome.com parser with detailed endpoint specifications, parameters, and response formats.

What You'll Find

Complete endpoint documentation with all available API methods
Detailed parameter specifications for each request type
Comprehensive response formats with example data structures
Code examples in multiple languages (JavaScript, Python, cURL)
Error handling and troubleshooting information
Rate limiting and best practices

API Reference

Base URL

https://api.carapis.com/v1/parsers/carsome.com

Authentication

All API requests require authentication using your API key in the Authorization header:

Authentication Format

Authorization: Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef

Security Best Practices

Never expose your API key in client-side code
Use environment variables to store API keys securely
Rotate keys regularly for enhanced security
Monitor usage to prevent unauthorized access

Core Endpoints

Extract Vehicle Listings

POST /extract

Extract vehicle listings from Carsome.com based on specified filters and options.

Use Cases

Search vehicles by make, model, year, and price range
Filter by location across Southeast Asian countries
Get detailed specifications and seller information
Access market data and pricing insights

Request Parameters

Parameter Overview

Parameter	Type	Required	Description
`filters`	object	No	Filter criteria for vehicle search
`options`	object	No	Extraction options and configuration
`limit`	integer	No	Maximum number of results (default: 50, max: 1000)

Filters Object

Available Filters

Field	Type	Description	Example
`make`	string	Vehicle make/brand	"Toyota", "Honda"
`model`	string	Vehicle model	"Vios", "City"
`yearFrom`	integer	Minimum year	2019
`yearTo`	integer	Maximum year	2023
`priceMin`	number	Minimum price	50000
`priceMax`	number	Maximum price	200000
`bodyType`	string	Vehicle body type	"Sedan", "SUV", "Hatchback"
`fuelType`	string	Fuel type	"Petrol", "Diesel", "Hybrid"
`transmission`	string	Transmission type	"Manual", "Automatic", "CVT"
`city`	string	City location	"kuala_lumpur", "jakarta"
`country`	string	Country	"malaysia", "indonesia", "thailand", "singapore"
`sellerType`	string	Seller type	"dealer", "private"
`mileageMax`	integer	Maximum mileage	100000

Options Object

Configuration Options

Field	Type	Description	Default
`region`	string	Target region	"malaysia"
`dataFields`	array	Specific data fields to extract	All fields
`includeImages`	boolean	Include vehicle images	true
`includeMarketData`	boolean	Include market insights	true
`sortBy`	string	Sort order	"relevance"
`sortOrder`	string	Sort direction	"desc"

Example Request

curl -X POST "https://api.carapis.com/v1/parsers/carsome.com/extract" \
  -H "Authorization: Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "make": "Toyota",
      "yearFrom": 2019,
      "priceMax": 150000,
      "country": "malaysia"
    },
    "options": {
      "region": "malaysia",
      "limit": 50,
      "dataFields": ["price", "specifications", "location", "seller_info"]
    }
  }'

JavaScript Example

const response = await fetch('https://api.carapis.com/v1/parsers/carsome.com/extract', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filters: {
      make: 'Toyota',
      yearFrom: 2019,
      priceMax: 150000,
      country: 'malaysia',
    },
    options: {
      region: 'malaysia',
      limit: 50,
      dataFields: ['price', 'specifications', 'location', 'seller_info'],
    },
  }),
});

const data = await response.json();
console.log(`Found ${data.data.vehicles.length} vehicles`);

Python Example

import requests

url = 'https://api.carapis.com/v1/parsers/carsome.com/extract'
headers = {
    'Authorization': 'Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef',
    'Content-Type': 'application/json'
}
payload = {
    'filters': {
        'make': 'Toyota',
        'yearFrom': 2019,
        'priceMax': 150000,
        'country': 'malaysia'
    },
    'options': {
        'region': 'malaysia',
        'limit': 50,
        'dataFields': ['price', 'specifications', 'location', 'seller_info']
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"Found {len(data['data']['vehicles'])} vehicles")

Response Format

{
  "success": true,
  "data": {
    "vehicles": [
      {
        "id": "carsome_12345",
        "title": "2020 Toyota Vios 1.5G",
        "url": "https://www.carsome.com/car-details/12345",
        "price": {
          "current": 85000,
          "currency": "MYR",
          "negotiable": true,
          "monthly_payment": 1200,
          "down_payment": 17000
        },
        "specifications": {
          "make": "Toyota",
          "model": "Vios",
          "year": 2020,
          "trim": "1.5G",
          "engine": "1.5L Dual VVT-i",
          "transmission": "CVT",
          "mileage": 35000,
          "fuel_type": "Petrol",
          "body_type": "Sedan",
          "color": "White",
          "doors": 4,
          "seats": 5
        },
        "location": {
          "city": "Kuala Lumpur",
          "state": "Selangor",
          "country": "Malaysia",
          "coordinates": [3.139, 101.6869]
        },
        "seller": {
          "type": "dealer",
          "name": "Carsome KL",
          "rating": 4.7,
          "verified": true,
          "phone": "+60 3 XXXX XXXX",
          "address": "Kuala Lumpur, Malaysia"
        },
        "market_data": {
          "days_listed": 5,
          "views": 75,
          "price_trend": "stable",
          "market_position": "competitive",
          "similar_listings": 12
        },
        "images": ["https://images.carsome.com/12345_1.jpg", "https://images.carsome.com/12345_2.jpg"],
        "extraction_time": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 2800,
      "page": 1,
      "per_page": 50,
      "total_pages": 56
    },
    "metadata": {
      "extraction_time": "2024-01-15T10:30:00Z",
      "region": "malaysia",
      "filters_applied": {
        "make": "Toyota",
        "yearFrom": 2019,
        "priceMax": 150000,
        "country": "malaysia"
      }
    }
  }
}

Get Market Analysis

POST /market-analysis

Get comprehensive market analysis and insights for Southeast Asian automotive markets.

Analysis Features

Price trend analysis with historical data
Inventory level monitoring across regions
Demand pattern analysis by vehicle type
Regional market comparisons and insights

Request Parameters

Analysis Parameters

Parameter	Type	Required	Description
`region`	string	Yes	Target region for analysis
`make`	string	No	Specific make for analysis
`period`	string	No	Analysis period (7d, 30d, 90d, 1y)
`metrics`	array	No	Specific metrics to include

Example Request

curl -X POST "https://api.carapis.com/v1/parsers/carsome.com/market-analysis" \
  -H "Authorization: Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "malaysia",
    "make": "Toyota",
    "period": "30d",
    "metrics": ["price_trends", "inventory_levels", "demand_analysis"]
  }'

Response Format

{
  "success": true,
  "data": {
    "region": "malaysia",
    "period": "30d",
    "make": "Toyota",
    "analysis": {
      "price_trends": {
        "average_price": 95000,
        "price_change": 2.5,
        "trend_direction": "increasing",
        "price_distribution": {
          "under_50k": 15,
          "50k_100k": 45,
          "100k_150k": 30,
          "over_150k": 10
        }
      },
      "inventory_levels": {
        "total_listings": 2800,
        "new_listings": 150,
        "sold_listings": 120,
        "inventory_turnover": 4.2
      },
      "demand_analysis": {
        "most_popular_models": ["Vios", "Hilux", "Innova"],
        "search_trends": {
          "vios": 25,
          "hilux": 20,
          "innova": 15
        },
        "market_segments": {
          "sedan": 40,
          "suv": 35,
          "pickup": 25
        }
      }
    },
    "generated_at": "2024-01-15T10:30:00Z"
  }
}

Get Vehicle Details

GET /vehicle/\{vehicle_id\}

Get detailed information for a specific vehicle by ID.

Use Cases

Get complete vehicle details for a specific listing
Access high-resolution images and specifications
View seller information and contact details
Check market positioning and similar listings

Path Parameters

Parameter	Type	Required	Description
`vehicle_id`	string	Yes	Unique vehicle ID

Example Request

curl -X GET "https://api.carapis.com/v1/parsers/carsome.com/vehicle/carsome_12345" \
  -H "Authorization: Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef"

Response Format

{
  "success": true,
  "data": {
    "id": "carsome_12345",
    "title": "2020 Toyota Vios 1.5G",
    "url": "https://www.carsome.com/car-details/12345",
    "price": {
      "current": 85000,
      "currency": "MYR",
      "negotiable": true,
      "monthly_payment": 1200,
      "down_payment": 17000,
      "price_history": [
        {
          "date": "2024-01-01",
          "price": 87000
        },
        {
          "date": "2024-01-15",
          "price": 85000
        }
      ]
    },
    "specifications": {
      "make": "Toyota",
      "model": "Vios",
      "year": 2020,
      "trim": "1.5G",
      "engine": "1.5L Dual VVT-i",
      "transmission": "CVT",
      "mileage": 35000,
      "fuel_type": "Petrol",
      "body_type": "Sedan",
      "color": "White",
      "interior_color": "Black",
      "doors": 4,
      "seats": 5,
      "power": "107 hp",
      "torque": "140 Nm",
      "fuel_consumption": "6.1L/100km"
    },
    "features": ["Keyless Entry", "Push Start", "Bluetooth Connectivity", "Reverse Camera", "ABS", "Airbags"],
    "location": {
      "city": "Kuala Lumpur",
      "state": "Selangor",
      "country": "Malaysia",
      "coordinates": [3.139, 101.6869],
      "address": "Kuala Lumpur, Malaysia"
    },
    "seller": {
      "type": "dealer",
      "name": "Carsome KL",
      "rating": 4.7,
      "verified": true,
      "phone": "+60 3 XXXX XXXX",
      "email": "contact@carsomekl.com",
      "address": "Kuala Lumpur, Malaysia",
      "business_hours": "Mon-Fri: 9AM-6PM",
      "dealer_since": "2018"
    },
    "market_data": {
      "days_listed": 5,
      "views": 75,
      "price_trend": "stable",
      "market_position": "competitive",
      "similar_listings": 12,
      "price_comparison": {
        "market_average": 88000,
        "price_difference": -3000,
        "price_percentile": 45
      }
    },
    "images": [
      {
        "url": "https://images.carsome.com/12345_1.jpg",
        "alt": "Front view",
        "primary": true
      },
      {
        "url": "https://images.carsome.com/12345_2.jpg",
        "alt": "Interior view",
        "primary": false
      }
    ],
    "history": {
      "accident_free": true,
      "owners_count": 1,
      "service_history": "Full service history available",
      "warranty": "Manufacturer warranty until 2025"
    },
    "extraction_time": "2024-01-15T10:30:00Z"
  }
}

Advanced Endpoints

Get Inventory Statistics

POST /inventory-stats

Get comprehensive inventory statistics and analytics.

Statistics Available

Total listings by region and make
Price distribution across segments
Inventory turnover rates
Market saturation analysis

Request Parameters

Parameter	Type	Required	Description
`region`	string	Yes	Target region for statistics
`make`	string	No	Specific make for analysis
`period`	string	No	Time period (7d, 30d, 90d, 1y)

Example Request

curl -X POST "https://api.carapis.com/v1/parsers/carsome.com/inventory-stats" \
  -H "Authorization: Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "malaysia",
    "make": "Toyota",
    "period": "30d"
  }'

Response Format

{
  "success": true,
  "data": {
    "region": "malaysia",
    "period": "30d",
    "make": "Toyota",
    "statistics": {
      "total_listings": 2800,
      "new_listings": 150,
      "sold_listings": 120,
      "active_listings": 2680,
      "price_distribution": {
        "under_50k": 420,
        "50k_100k": 1260,
        "100k_150k": 840,
        "over_150k": 280
      },
      "body_type_distribution": {
        "sedan": 1120,
        "suv": 980,
        "hatchback": 420,
        "pickup": 280
      },
      "inventory_turnover": 4.2,
      "average_days_on_market": 25,
      "market_saturation": 0.65
    },
    "generated_at": "2024-01-15T10:30:00Z"
  }
}

Search Similar Vehicles

POST /similar-vehicles

Find vehicles similar to a specified vehicle based on various criteria.

Similarity Criteria

Same make and model with different years
Similar price range and specifications
Same body type and fuel type
Geographic proximity to original listing

Request Parameters

Parameter	Type	Required	Description
`vehicle_id`	string	Yes	ID of the reference vehicle
`limit`	number	No	Number of similar vehicles
`criteria`	object	No	Similarity matching criteria

Example Request

curl -X POST "https://api.carapis.com/v1/parsers/carsome.com/similar-vehicles" \
  -H "Authorization: Bearer carsome_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": "carsome_12345",
    "limit": 10,
    "criteria": {
      "price_range": 0.2,
      "year_range": 2,
      "same_make_model": true
    }
  }'

Error Handling

HTTP Status Codes

Common Error Codes

Status Code	Description	Solution
400	Bad Request	Check request parameters
401	Unauthorized	Verify API key
403	Forbidden	Check API key permissions
404	Not Found	Verify endpoint URL
429	Too Many Requests	Reduce request frequency
500	Internal Server Error	Contact support

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid filter parameter: yearFrom must be greater than 1900",
    "details": {
      "parameter": "yearFrom",
      "value": 1800,
      "constraint": "must be greater than 1900"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Rate Limiting

Rate Limits

Plan	Requests per minute	Requests per hour	Requests per day
Free	60	1,000	10,000
Basic	300	5,000	50,000
Professional	1,000	20,000	200,000
Enterprise	5,000	100,000	1,000,000

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1642234567

Best Practices

Performance Optimization

Optimization Tips

Use appropriate limits to avoid overwhelming the API
Implement caching for frequently requested data
Batch requests when possible for better efficiency
Monitor rate limits to stay within quotas

Error Handling

Implement retry logic for transient errors
Handle rate limiting gracefully with exponential backoff
Log errors for debugging and monitoring
Provide user-friendly error messages

Security

Security Guidelines

Store API keys securely in environment variables
Never expose keys in client-side code
Use HTTPS for all API communications
Monitor usage for suspicious activity

Next Steps

Ready to Integrate?

Get Your API Key - Sign up for Carsome.com parser access
Quick Start Guide - Set up in minutes
View Features - See all available capabilities
Market Analysis - Southeast Asian market insights

Need Help?

Support - Technical assistance and troubleshooting
Examples - Live API examples and demos
Community - Connect with other developers
Documentation - Complete parser guide

Access comprehensive Southeast Asian automotive data with enterprise-grade API reliability.

Get Started with Carsome.com API →

Base URL​

Authentication​

Core Endpoints​

Extract Vehicle Listings​

Request Parameters​

Filters Object​

Options Object​

Example Request​

JavaScript Example​

Python Example​

Response Format​

Get Market Analysis​

Request Parameters​

Example Request​

Response Format​

Get Vehicle Details​

Path Parameters​

Example Request​

Response Format​

Advanced Endpoints​

Get Inventory Statistics​

Request Parameters​

Example Request​

Response Format​

Search Similar Vehicles​

Request Parameters​

Example Request​

Error Handling​

HTTP Status Codes​

Error Response Format​

Rate Limiting​

Best Practices​

Performance Optimization​

Error Handling​

Security​

Next Steps​

Base URL

Authentication

Core Endpoints

Extract Vehicle Listings

Request Parameters

Filters Object

Options Object

Example Request

JavaScript Example

Python Example

Response Format

Get Market Analysis

Request Parameters

Example Request

Response Format

Get Vehicle Details

Path Parameters

Example Request

Response Format

Advanced Endpoints

Get Inventory Statistics

Request Parameters

Example Request

Response Format

Search Similar Vehicles

Request Parameters

Example Request

Error Handling

HTTP Status Codes

Error Response Format

Rate Limiting

Best Practices

Performance Optimization

Error Handling

Security

Next Steps