Skip to main content

Quick Start Guide

A programmer harnesses the power of Carapis automotive data extraction, surrounded by a futuristic interface of car models and market analytics.

Professional automotive technology illustration

Get up and running with Carapis automotive data extraction in minutes with our step-by-step guide.

This quick start guide will help you extract your first automotive data from global markets using the Carapis API. Follow these simple steps to begin accessing vehicle listings, pricing information, and market insights.

🚀 Prerequisites​

Before you begin, ensure you have:

  • Carapis Account: Sign up at dashboard.carapis.com
  • API Key: Get your API key from the dashboard
  • Basic Programming Knowledge: Familiarity with HTTP requests or our SDKs
Free Tier Available

Start with our free tier that includes 1,000 requests per day. No credit card required!

📋 Step 1: Create Your Account​

Sign Up for Carapis​

  1. Visit dashboard.carapis.com
  2. Click "Sign Up" and create your account
  3. Verify your email address
  4. Navigate to the API Keys section

Generate Your API Key​

# Your API key will look like this
carapis_sk_1234567890abcdef1234567890abcdef
API Key Security

Keep your API key secure and never share it publicly. You can regenerate it anytime from the dashboard.

🔧 Step 2: Choose Your Integration Method​

// Install the Carapis JavaScript SDK
npm install carapis

// Initialize the client
const Carapis = require('carapis');

const client = new Carapis('YOUR_API_KEY');

// Test the connection
async function testConnection() {
    try {
        // Get available markets
        const markets = await client.getMarkets();
        console.log(`Connected! Found ${markets.length} markets`);
    } catch (error) {
        console.error('Connection failed:', error);
    }
}

testConnection();

Option B: Python SDK​

# Install the Carapis Python SDK
pip install carapis

# Initialize the client
import carapis

client = carapis.Client(api_key="YOUR_API_KEY")

# Test the connection
try:
    # Get available markets
    markets = client.get_markets()
    print(f"Connected! Found {len(markets)} markets")
except Exception as e:
    print(f"Connection failed: {e}")

Option C: Direct HTTP API​

# Test the API with curl
curl -X GET "https://api.carapis.com/v1/markets" \
  -H "Authorization: Bearer YOUR_API_KEY"

🔍 Step 3: Your First Data Extraction​

Search for Vehicles​

// Search for Toyota Camry vehicles from 2020 onwards
const searchParams = {
  brand: 'Toyota',
  model: 'Camry',
  year: '2020-2023',
  markets: ['united_states', 'germany'],
  limit: 10,
};

// Execute the search
const response = await client.search(searchParams);

console.log(`Found ${response.data.length} Toyota Camry vehicles`);
response.data.forEach((vehicle) => {
  console.log(`- ${vehicle.title}: ${vehicle.price.formatted}`);
});

Get Detailed Vehicle Information​

// Get detailed information about a specific vehicle
const vehicleId = 'encar_123456789';
const vehicle = await client.getVehicle(vehicleId);

console.log(`Vehicle: ${vehicle.title}`);
console.log(`Price: ${vehicle.price.formatted}`);
console.log(`Mileage: ${vehicle.mileage} km`);
console.log(`Location: ${vehicle.location.city}, ${vehicle.location.country}`);

Extract Market Data​

// Get market analysis for BMW X5 vehicles
const marketData = await client.getMarketStats({
  brand: 'BMW',
  model: 'X5',
  market: 'germany',
  period: '30d',
});

console.log('Market Overview:');
console.log(`- Total Listings: ${marketData.total_listings}`);
console.log(`- Average Price: ${marketData.average_price.formatted}`);
console.log(`- Price Trend: ${marketData.price_trend}`);

📊 Step 4: Advanced Usage Examples​

// Search across multiple markets simultaneously
const multiMarketSearch = await client.search({
  brand: 'Hyundai',
  model: 'Tucson',
  year: '2020-2023',
  markets: ['south_korea', 'united_states', 'germany'],
  price_min: 20000,
  price_max: 50000,
  limit: 50,
});

console.log(`Found ${multiMarketSearch.data.length} vehicles across markets`);

Market-Specific Parsers​

// Use specific market parsers for detailed data
const encarClient = client.parsers.encar;
const koreanVehicles = await encarClient.search({
  brand: 'Hyundai',
  model: 'Tucson',
  year: '2020-2023',
  location: 'Seoul',
  limit: 20,
});

console.log(`Found ${koreanVehicles.length} Hyundai Tucson vehicles in Seoul`);

Real-time Notifications​

// Set up webhook for real-time notifications
const webhook = await client.setupWebhook({
  url: 'https://your-app.com/webhook',
  events: ['new_listing', 'price_change'],
  filters: {
    brand: 'Toyota',
    model: 'Camry',
  },
});

console.log('Webhook configured for Toyota Camry notifications');

🔧 Step 5: Error Handling​

Robust Error Handling​

// Implement proper error handling
async function safeApiCall(apiFunction, ...args) {
  try {
    return await apiFunction(...args);
  } catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      console.log('Rate limit exceeded. Waiting 60 seconds...');
      await new Promise((resolve) => setTimeout(resolve, 60000));
      return await apiFunction(...args); // Retry
    } else if (error.code === 'INVALID_API_KEY') {
      console.error('Invalid API key. Please check your credentials.');
    } else {
      console.error('API Error:', error.message);
    }
    throw error;
  }
}

// Use the safe wrapper
try {
  const vehicles = await safeApiCall(client.search, {
    brand: 'BMW',
    model: 'X5',
    limit: 50,
  });
  console.log(`Successfully retrieved ${vehicles.data.length} vehicles`);
} catch (error) {
  console.error('Failed to retrieve vehicles:', error);
}

📈 Step 6: Data Export and Analysis​

Export to CSV​

// Export search results to CSV
const fs = require('fs');

async function exportToCSV(searchParams, filename) {
  const response = await client.search(searchParams);

  const csvHeader = 'Title,Price,Brand,Model,Year,Location\n';
  const csvData = response.data.map((vehicle) => `"${vehicle.title}","${vehicle.price.formatted}","${vehicle.brand}","${vehicle.model}","${vehicle.year}","${vehicle.location.city}"`).join('\n');

  const csvContent = csvHeader + csvData;
  fs.writeFileSync(filename, csvContent);

  console.log(`Exported ${response.data.length} vehicles to ${filename}`);
}

// Export BMW X5 data
exportToCSV(
  {
    brand: 'BMW',
    model: 'X5',
    year: '2020-2023',
    limit: 1000,
  },
  'bmw_x5_data.csv',
);

Basic Market Analysis​

// Perform basic market analysis
async function analyzeMarket(brand, model, market) {
  const stats = await client.getMarketStats({
    brand: brand,
    model: model,
    market: market,
    period: '30d',
  });

  console.log(`Market Analysis for ${brand} ${model} in ${market}:`);
  console.log(`- Total Listings: ${stats.total_listings}`);
  console.log(`- Average Price: ${stats.average_price.formatted}`);
  console.log(`- Price Range: ${stats.price_range.min.formatted} - ${stats.price_range.max.formatted}`);
  console.log(`- Price Trend: ${stats.price_trend}`);
  console.log(`- Demand Level: ${stats.demand_level}`);
}

analyzeMarket('Toyota', 'Camry', 'united_states');

🚀 Step 7: Production Deployment​

Environment Variables​

# Set your API key as an environment variable
export CARAPIS_API_KEY="your_api_key_here"
// Use environment variable in your code
const client = new Carapis(process.env.CARAPIS_API_KEY);

Rate Limiting Best Practices​

// Implement rate limiting for production use
class RateLimitedClient {
  constructor(client, requestsPerMinute = 60) {
    this.client = client;
    this.requestsPerMinute = requestsPerMinute;
    this.requestTimes = [];
  }

  async makeRequest(apiFunction, ...args) {
    const now = Date.now();

    // Remove requests older than 1 minute
    this.requestTimes = this.requestTimes.filter((time) => now - time < 60000);

    if (this.requestTimes.length >= this.requestsPerMinute) {
      const waitTime = 60000 - (now - this.requestTimes[0]);
      if (waitTime > 0) {
        await new Promise((resolve) => setTimeout(resolve, waitTime));
      }
    }

    this.requestTimes.push(Date.now());
    return await apiFunction.apply(this.client, args);
  }
}

// Use the rate-limited client
const rateLimitedClient = new RateLimitedClient(client);

🔍 Troubleshooting​

Common Issues​

Rate Limiting

If you encounter rate limit errors, implement exponential backoff:

  • Wait 1 minute, then retry
  • If still limited, wait 2 minutes
  • Continue doubling wait time
Authentication Errors
  • Verify your API key is correct
  • Check that your account is active
  • Ensure you're using the correct endpoint
Performance Optimization
  • Use batch operations when possible
  • Implement caching for frequently accessed data
  • Monitor your request usage in the dashboard

📚 Next Steps​

Explore Advanced Features​

  1. API Reference - Complete endpoint documentation
  2. Parser Documentation - Market-specific guides
  3. Use Cases - Industry-specific implementations
  4. SDK Documentation - Client libraries and examples

Choose Your Market​

Support Resources​

Ready to start extracting automotive data? Get your API key now and begin building powerful automotive applications with real-time global market data.