@carapis/api
Version:
Universal TypeScript/JavaScript client for CARAPIS Vehicles API - Access automotive data from 25+ global marketplaces including Cars.com, AutoScout24, Encar, Auto.ru, and more. Enterprise-grade automotive data extraction with real-time vehicle listings, p
335 lines (257 loc) • 11.6 kB
Markdown
# 🚗 CARAPIS Vehicles API Client
[](https://badge.fury.io/js/@carapis%2Fvehicles-api-client)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/carapis/vehicles-api-client)
**Universal TypeScript/JavaScript client for the CARAPIS Vehicles API - Access automotive data from 25+ global marketplaces with enterprise-grade reliability.**
> 🌐 **Developed by [CARAPIS](https://carapis.com)** - The leading automotive data extraction platform serving Fortune 500 companies and automotive professionals worldwide.
## 🌟 Why Choose CARAPIS Vehicles API?
- **🌍 Global Coverage**: Access 25+ automotive marketplaces across Asia, Europe, Americas, and Middle East
- **⚡ Real-time Data**: Live vehicle listings, pricing, and market intelligence
- **🛡️ Enterprise-Grade**: 99.9% uptime, advanced anti-detection, residential proxies
- **🔧 Developer-Friendly**: Full TypeScript support, comprehensive documentation, SSR ready
- **📊 Market Intelligence**: Advanced analytics, price trends, and market insights
- **🚀 Production Ready**: Used by automotive dealers, marketplaces, and data companies globally
## 🌐 Supported Automotive Platforms
### 🇰🇷 **Asia-Pacific**
- **[Encar.com](https://docs.carapis.com/parsers/encar.com/quick-start)** - South Korea's largest automotive marketplace (2M+ listings)
- **[Che168.com](https://docs.carapis.com/parsers/che168.com/quick-start)** - China's premier automotive platform
- **[Guazi.com](https://docs.carapis.com/parsers/guazi.com/quick-start)** - Leading Chinese used car marketplace
- **[Goo-net.com](https://docs.carapis.com/parsers/goo-net.com/quick-start)** - Japan's automotive marketplace
- **[BeForward.jp](https://docs.carapis.com/parsers/beforward.jp/quick-start)** - Japanese automotive exporter
- **[Carsome.com](https://docs.carapis.com/parsers/carsome.com/quick-start)** - Southeast Asian automotive platform
- **[One2Car.com](https://docs.carapis.com/parsers/one2car.com/quick-start)** - Thailand's automotive marketplace
- **[CarDekho.com](https://docs.carapis.com/parsers/cardekho.com/quick-start)** - India's automotive platform
- **[Spinny.com](https://docs.carapis.com/parsers/spinny.com/quick-start)** - Indian automotive marketplace
### 🇺🇸 **North America**
- **[Cars.com](https://docs.carapis.com/parsers/cars.com/quick-start)** - Leading US automotive platform (2M+ listings)
- **[CarGurus.com](https://docs.carapis.com/parsers/cargurus.com/quick-start)** - US automotive marketplace and analytics
- **[Carvana.com](https://docs.carapis.com/parsers/carvana.com/quick-start)** - US online car retailer
- **[Vroom.com](https://docs.carapis.com/parsers/vroom.com/quick-start)** - US online automotive marketplace
- **[AutoTrader.com](https://docs.carapis.com/parsers/autotrader.com/quick-start)** - Premier automotive marketplace
### 🇪🇺 **Europe**
- **[AutoScout24.com](https://docs.carapis.com/parsers/autoscout24.com/quick-start)** - Europe's largest automotive marketplace
- **[Mobile.de](https://docs.carapis.com/parsers/mobile.de/quick-start)** - Germany's leading automotive platform
- **[Auto.ru](https://docs.carapis.com/parsers/auto.ru/quick-start)** - Russia's premier automotive marketplace (2M+ listings)
- **[Avito.ru](https://docs.carapis.com/parsers/avito.ru/quick-start)** - Russian classifieds platform
- **[Arabam.com](https://docs.carapis.com/parsers/arabam.com/quick-start)** - Turkey's automotive marketplace
### 🌍 **Global & Regional**
- **[OLX.com](https://docs.carapis.com/parsers/olx.com/quick-start)** - Global classifieds platform
- **[Dubizzle.com](https://docs.carapis.com/parsers/dubizzle.com/quick-start)** - UAE automotive marketplace
- **[Webmotors.com.br](https://docs.carapis.com/parsers/webmotors.com.br/quick-start)** - Brazilian automotive platform
## 🚀 Quick Start
### Installation
```bash
# npm
npm install @carapis/api
# yarn
yarn add @carapis/api
# pnpm
pnpm add @carapis/api
```
### Basic Usage
```typescript
import { VehiclesAPIClient } from '@carapis/api';
// Initialize client
const client = new VehiclesAPIClient('https://api.carapis.com');
client.setApiKey('your-api-key');
// Get vehicles with filters
const vehicles = await client.vehicles.getVehicles({
brand_code: 'toyota',
price_min: 10000,
price_max: 50000,
page_size: 20
});
console.log(`Found ${vehicles.count} vehicles`);
vehicles.results.forEach(vehicle => {
console.log(`${vehicle.year} ${vehicle.brand_name} ${vehicle.model_name} - $${vehicle.price}`);
});
```
### Advanced Filtering
```typescript
// Advanced search with multiple filters
const searchResults = await client.vehicles.getVehicles({
search: 'BMW X5',
year_min: 2020,
body_type: 'suv',
fuel_type: 'gasoline',
transmission: 'automatic',
mileage_max: 50000,
ordering: '-price' // Sort by price descending
});
// Get vehicle details
const vehicleDetail = await client.vehicles.getVehicle('vehicle-id');
console.log('Vehicle details:', vehicleDetail);
```
### Server-Side Rendering (SSR)
```typescript
import { VehiclesSSRService } from '@carapis/api';
// Perfect for Next.js, Nuxt.js, SvelteKit
export async function getServerSideProps() {
const catalogData = await VehiclesSSRService.getVehiclesForCatalog({
brand_code: 'toyota',
page_size: 20
});
return {
props: {
vehicles: catalogData.vehicles,
totalCount: catalogData.totalCount,
seo: VehiclesSSRService.generateVehicleSEO(catalogData.vehicles[0])
}
};
}
```
### Brand and Market Data
```typescript
// Get all brands
const brands = await client.brands.getBrands();
// Get brand-specific data
const brandData = await VehiclesSSRService.getBrandPageData('toyota');
console.log(`Toyota has ${brandData.totalCount} vehicles available`);
console.log(`Average price: $${brandData.stats.averagePrice}`);
// Market statistics
const stats = await client.statistics.getVehicleStats();
console.log('Market overview:', stats);
```
## 🛠️ API Reference
### Core Services
- **`VehiclesService`** - Vehicle listings, search, and details
- **`BrandsService`** - Brand information and brand-specific vehicles
- **`SourcesService`** - Data source management and statistics
- **`StatisticsService`** - Market analytics and insights
- **`VehiclesSSRService`** - Server-side rendering utilities
### TypeScript Support
Full TypeScript support with comprehensive type definitions:
```typescript
import type {
CatalogVehicle,
CatalogBrand,
CatalogFilters,
V1VehicleDetail,
PaginatedV1VehicleListList
} from '@carapis/api';
// Type-safe filtering
const filters: CatalogFilters = {
brand_code: 'toyota',
price_min: 15000,
price_max: 45000,
body_type: 'sedan',
fuel_type: 'hybrid'
};
const vehicles: PaginatedV1VehicleListList = await client.vehicles.getVehicles(filters);
```
## 🏗️ Framework Integration
### React/Next.js
```tsx
import { VehiclesAPIClient, VehiclesSSRService } from '@carapis/api';
function VehicleCatalog({ vehicles }) {
return (
<div>
{vehicles.map(vehicle => (
<div key={vehicle.id}>
<h3>{vehicle.displayName}</h3>
<p>{vehicle.formattedPrice}</p>
<img src={vehicle.primaryImageUrl} alt={vehicle.displayName} />
</div>
))}
</div>
);
}
// SSR/SSG support
export async function getStaticProps() {
const data = await VehiclesSSRService.getVehiclesForCatalog();
return { props: { vehicles: data.vehicles } };
}
```
### Vue.js/Nuxt.js
```vue
<template>
<div>
<div v-for="vehicle in vehicles" :key="vehicle.id">
<h3>{{ vehicle.displayName }}</h3>
<p>{{ vehicle.formattedPrice }}</p>
</div>
</div>
</template>
<script setup>
import { VehiclesAPIClient } from '@carapis/api';
const client = new VehiclesAPIClient();
client.setApiKey(process.env.CARAPIS_API_KEY);
const { data: vehicles } = await client.vehicles.getVehicles({
page_size: 20
});
</script>
```
## 🔧 Configuration
### Environment Variables
```bash
# .env
CARAPIS_API_URL=https://api.carapis.com
CARAPIS_API_KEY=your-api-key-here
```
### Client Configuration
```typescript
const client = new VehiclesAPIClient('https://api.carapis.com');
// Set API key
client.setApiKey('your-api-key');
// Custom headers
client.setHeaders({
'User-Agent': 'MyApp/1.0',
'Accept-Language': 'en-US,en;q=0.9'
});
// Check authentication
if (client.isAuthenticated()) {
console.log('Client is authenticated');
}
```
## 📊 Use Cases
### 🏪 **Automotive Marketplaces**
- Build comprehensive vehicle catalogs
- Real-time inventory management
- Competitive pricing analysis
- Market trend monitoring
### 🏢 **Dealerships & Dealers**
- Inventory optimization
- Pricing strategies
- Market research
- Lead generation
### 📈 **Data Analytics & Research**
- Market intelligence reports
- Price trend analysis
- Consumer behavior insights
- Regional market studies
### 🔧 **Automotive Apps & Platforms**
- Vehicle comparison tools
- Price estimation services
- Market analysis dashboards
- Automotive data enrichment
## 🌟 Enterprise Features
- **🔒 Secure Authentication** - API key and token-based auth
- **📊 Rate Limiting** - Intelligent request throttling
- **🛡️ Anti-Detection** - Advanced proxy rotation and headers
- **📈 Analytics** - Comprehensive usage statistics
- **🔧 Custom Integration** - Tailored solutions for enterprise needs
- **📞 24/7 Support** - Dedicated technical support team
## 📚 Documentation & Resources
- **[API Documentation](https://carapis.com/docs)** - Complete API reference
- **[Platform Guides](https://docs.carapis.com/parsers)** - Platform-specific documentation
- **[Market Analysis](https://carapis.com/market-analysis)** - Automotive market insights
- **[Developer Portal](https://carapis.com/developers)** - Tools and resources
- **[Status Page](https://status.carapis.com)** - Real-time API status
## 🤝 Support & Community
- **📧 Email**: [support@carapis.com](mailto:support@carapis.com)
- **📖 Documentation**: [docs.carapis.com](https://docs.carapis.com)
## 📄 License
MIT License - see the [LICENSE](LICENSE) file for details.
## 🏢 About CARAPIS
**[CARAPIS](https://carapis.com)** is the world's leading automotive data extraction platform, trusted by Fortune 500 companies, automotive dealers, and data-driven businesses globally. We provide real-time access to automotive data from 25+ international marketplaces with enterprise-grade reliability and advanced anti-detection technology.
### Why Choose CARAPIS?
- **🌍 Global Leader** - Serving 1000+ clients worldwide
- **🔒 Enterprise Security** - SOC 2 compliant, GDPR ready
- **⚡ High Performance** - 99.9% uptime, sub-second response times
- **🛡️ Anti-Detection** - Advanced proxy networks and rotation
- **📊 Market Intelligence** - Deep automotive market insights
- **🤝 Expert Support** - Dedicated technical and business support
---
**Ready to access global automotive data?** [Get your API key](https://carapis.com/auth) and start building with CARAPIS today!
[](https://carapis.com/auth)