Skip to main content

Quick Start Guide

Quick Start

Get started with Carsome.com parser in minutes. Extract Southeast Asian automotive data with just a few lines of code.

🚀 Prerequisites​

Before you begin, ensure you have:

  • API Key: Get your API key from the Carapis Dashboard
  • Programming Language: Choose your preferred language (JavaScript, Python, PHP, etc.)
  • Internet Connection: Stable connection for API requests
  • SEA Market Knowledge: Basic understanding of Southeast Asian automotive market

📋 Step 1: Get Your API Key​

  1. Sign up at Carapis Dashboard
  2. Navigate to the API Keys section
  3. Create a new API key for Carsome.com parser
  4. Copy your API key (keep it secure!)
# Your API key will look like this:
carsome_parser_sk_1234567890abcdef1234567890abcdef

🔧 Step 2: Install SDK (Optional)​

JavaScript/Node.js​

npm install @carapis/carsome-parser
# or
yarn add @carapis/carsome-parser

Python​

pip install carapis-carsome-parser

PHP​

composer require carapis/carsome-parser

📝 Step 3: Make Your First Request​

JavaScript Example​

// Using the SDK
const { CarsomeParser } = require('@carapis/carsome-parser');

const parser = new CarsomeParser({
  apiKey: 'carsome_parser_sk_1234567890abcdef1234567890abcdef',
  region: 'malaysia',
});

// Extract vehicle listings
async function getVehicles() {
  try {
    const vehicles = await parser.extractListings({
      filters: {
        make: 'Toyota',
        yearFrom: 2019,
        priceMax: 150000,
      },
      limit: 10,
    });

    console.log(`Found ${vehicles.length} Toyota vehicles from 2019+ under 150K MYR`);
    vehicles.forEach((vehicle) => {
      console.log(`${vehicle.year} ${vehicle.make} ${vehicle.model} - ${vehicle.price.currency} ${vehicle.price.current.toLocaleString()}`);
    });
  } catch (error) {
    console.error('Error:', error.message);
  }
}

getVehicles();

Python Example​

# Using the SDK
from carapis_carsome_parser import CarsomeParser

parser = CarsomeParser(
    api_key="carsome_parser_sk_1234567890abcdef1234567890abcdef",
    region="indonesia"
)

# Extract market data
try:
    vehicles = parser.extract_listings(
        filters={
            "make": "Honda",
            "body_type": "SUV",
            "price_min": 200000000
        },
        limit=10
    )

    print(f"Found {len(vehicles)} Honda SUVs above 200M IDR")
    for vehicle in vehicles:
        print(f"{vehicle['year']} {vehicle['make']} {vehicle['model']} - {vehicle['price']['currency']} {vehicle['price']['current']:,}")

except Exception as e:
    print(f"Error: {e}")

Direct API Call (cURL)​

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": "Honda",
      "yearFrom": 2019,
      "priceMax": 800000
    },
    "options": {
      "region": "thailand",
      "limit": 5,
      "dataFields": ["price", "specifications", "seller_info"]
    }
  }'

📊 Step 4: Understand the Response​

{
  "success": true,
  "data": {
    "vehicles": [
      {
        "id": "carsome_12345",
        "title": "2020 Honda City VX",
        "url": "https://www.carsome.com/car-details/12345",
        "price": {
          "current": 750000,
          "currency": "THB",
          "negotiable": true,
          "monthly_payment": 15000,
          "down_payment": 150000
        },
        "specifications": {
          "make": "Honda",
          "model": "City",
          "year": 2020,
          "engine": "1.5L i-VTEC",
          "transmission": "CVT",
          "mileage": 25000,
          "fuel_type": "Petrol",
          "body_type": "Sedan",
          "color": "White"
        },
        "location": {
          "city": "Bangkok",
          "country": "Thailand",
          "coordinates": [13.7563, 100.5018]
        },
        "seller": {
          "type": "dealer",
          "name": "Carsome Thailand",
          "rating": 4.6,
          "verified": true,
          "phone": "+66 2 XXXX XXXX"
        },
        "market_data": {
          "days_listed": 3,
          "views": 45,
          "price_trend": "stable",
          "market_position": "competitive"
        }
      }
    ],
    "pagination": {
      "total": 1800,
      "page": 1,
      "per_page": 5,
      "total_pages": 360
    },
    "metadata": {
      "extraction_time": "2024-01-15T10:30:00Z",
      "region": "thailand",
      "filters_applied": {
        "make": "Honda",
        "yearFrom": 2019,
        "priceMax": 800000
      }
    }
  }
}

🎯 Step 5: Common Use Cases​

Extract Toyota Vehicles in Malaysia​

const vehicles = await parser.extractListings({
  filters: {
    make: 'Toyota',
    city: 'kuala_lumpur',
    priceMax: 200000,
  },
  options: {
    limit: 100,
    dataFields: ['price', 'specifications', 'location'],
  },
});

Get SUV Market Analysis for Indonesia​

const vehicles = await parser.extractListings({
  filters: {
    bodyType: 'SUV',
    yearFrom: 2018,
    country: 'indonesia',
  },
  options: {
    limit: 50,
    dataFields: ['price', 'market_data', 'specifications'],
  },
});

// Calculate average SUV price in Indonesia
const avgPrice = vehicles.reduce((sum, v) => sum + v.price.current, 0) / vehicles.length;
console.log(`Average SUV price in Indonesia: IDR ${avgPrice.toLocaleString()}`);

Monitor Dealer Inventory Across SEA​

const dealerVehicles = await parser.extractListings({
  filters: {
    sellerType: 'dealer',
    countries: ['malaysia', 'indonesia', 'thailand', 'singapore'],
  },
  options: {
    limit: 200,
    dataFields: ['seller_info', 'price', 'specifications'],
  },
});

// Group by country
const countryInventory = {};
dealerVehicles.forEach((vehicle) => {
  const country = vehicle.location.country;
  if (!countryInventory[country]) {
    countryInventory[country] = [];
  }
  countryInventory[country].push(vehicle);
});

⚙️ Configuration Options​

Regional Settings​

const parser = new CarsomeParser({
  apiKey: 'your_api_key',
  region: 'malaysia', // Options: malaysia, indonesia, thailand, singapore
  language: 'en', // English language
  currency: 'MYR', // Malaysian Ringgit
});

Data Field Selection​

const vehicles = await parser.extractListings({
  filters: { make: 'Honda' },
  options: {
    dataFields: [
      'price', // Pricing information
      'specifications', // Vehicle specs
      'location', // Geographic data
      'seller_info', // Seller details
      'market_data', // Market insights
      'financing', // Payment options
    ],
  },
});

Rate Limiting​

const parser = new CarsomeParser({
  apiKey: 'your_api_key',
  rateLimit: {
    requestsPerMinute: 60,
    requestsPerHour: 1000,
  },
});

🔍 Error Handling​

try {
  const vehicles = await parser.extractListings({
    filters: { make: 'Toyota' },
  });
} catch (error) {
  switch (error.code) {
    case 'AUTHENTICATION_ERROR':
      console.error('Invalid API key');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      console.error('Rate limit exceeded. Please wait.');
      break;
    case 'INVALID_FILTERS':
      console.error('Invalid filter parameters');
      break;
    case 'EXTRACTION_FAILED':
      console.error('Data extraction failed. Please try again.');
      break;
    case 'REGION_NOT_SUPPORTED':
      console.error('Region not supported');
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

📈 Next Steps​

  1. Explore the API Reference for detailed endpoint documentation
  2. Check out Market Analysis for Southeast Asian automotive market insights
  3. Review the FAQ for common questions and troubleshooting
  4. Join our community for support and updates

🆘 Need Help?​

Ready to extract Southeast Asian automotive data? Start building with Carsome.com parser today!