Skip to main content

Making Your First Request

Get started with our automotive parsers in minutes. This guide shows you how to make your first API request and start extracting vehicle data.

🚀 Quick Start​

1. Authentication​

First, you'll need to authenticate with your API key:

curl -X POST "https://api.carapis.com/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here"
  }'

2. Choose Your Parser​

Select the automotive platform you want to parse:

  • Encar.com - Korean market leader
  • Che168.com - Chinese automotive platform
  • AutoTrader - US marketplace
  • CarGurus - US/Canada/UK platform
  • Mobile.de - German automotive market
  • And 15+ more platforms...

3. Make Your First Request​

Here's a simple example to get vehicle listings:

import requests

# Authentication
auth_response = requests.post('https://api.carapis.com/auth', json={
    'api_key': 'your_api_key_here'
})

# Get vehicle listings from Encar
response = requests.get('https://api.carapis.com/parsers/encar/listings',
    headers={'Authorization': f'Bearer {auth_response.json()["token"]}'},
    params={
        'brand': 'Hyundai',
        'model': 'Sonata',
        'year_from': 2020,
        'limit': 10
    }
)

vehicles = response.json()
print(f"Found {len(vehicles)} vehicles")

📋 API Endpoints​

Vehicle Listings​

GET /parsers/{platform}/listings

Parameters:

  • brand - Vehicle brand (optional)
  • model - Vehicle model (optional)
  • year_from - Minimum year (optional)
  • year_to - Maximum year (optional)
  • price_from - Minimum price (optional)
  • price_to - Maximum price (optional)
  • limit - Number of results (default: 20)
  • offset - Pagination offset (default: 0)

Vehicle Details​

GET /parsers/{platform}/vehicle/{id}

Search Vehicles​

GET /parsers/{platform}/search

🔧 Code Examples​

Python SDK​

from carapis import CarapisClient

# Initialize client
client = CarapisClient(api_key='your_api_key')

# Get Korean vehicles
korean_vehicles = client.encar.get_listings(
    brand='Hyundai',
    model='Sonata',
    year_from=2020
)

# Get Chinese vehicles
chinese_vehicles = client.che168.get_listings(
    brand='Toyota',
    price_to=50000
)

JavaScript/Node.js​

const { CarapisClient } = require('@carapis/sdk');

const client = new CarapisClient('your_api_key');

// Get German vehicles
const germanVehicles = await client.mobile.getListings({
  brand: 'BMW',
  model: 'X5',
  yearFrom: 2019,
});

cURL Examples​

# Get US vehicles from AutoTrader
curl -X GET "https://api.carapis.com/parsers/autotrader/listings" \
  -H "Authorization: Bearer your_token" \
  -G \
  -d "brand=Ford" \
  -d "model=Mustang" \
  -d "year_from=2020"

# Get vehicle details
curl -X GET "https://api.carapis.com/parsers/encar/vehicle/12345" \
  -H "Authorization: Bearer your_token"

📊 Response Format​

All API responses follow a consistent JSON format:

{
  "success": true,
  "data": {
    "vehicles": [
      {
        "id": "12345",
        "title": "2021 Hyundai Sonata",
        "brand": "Hyundai",
        "model": "Sonata",
        "year": 2021,
        "price": 25000,
        "currency": "USD",
        "mileage": 15000,
        "location": "Seoul, Korea",
        "seller": "Hyundai Dealer",
        "images": ["url1", "url2"],
        "specifications": {
          "engine": "2.5L",
          "transmission": "Automatic",
          "fuel_type": "Gasoline"
        }
      }
    ],
    "total": 150,
    "page": 1,
    "limit": 20
  },
  "meta": {
    "request_id": "req_123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

⚡ Rate Limits​

  • Free Tier: 100 requests/hour
  • Pro Tier: 1,000 requests/hour
  • Enterprise: Custom limits

Monitor your usage:

curl -X GET "https://api.carapis.com/usage" \
  -H "Authorization: Bearer your_token"

🛠️ Error Handling​

Handle API errors gracefully:

try:
    response = client.encar.get_listings(brand='Hyundai')
except CarapisError as e:
    if e.code == 'RATE_LIMIT_EXCEEDED':
        print("Rate limit exceeded, wait before retrying")
    elif e.code == 'INVALID_API_KEY':
        print("Check your API key")
    else:
        print(f"Error: {e.message}")

📚 Next Steps​