API Reference for Guazi.com Parser

Complete technical documentation for accessing Guazi.com automotive data through our reliable API.

API Overview

Base URL: https://api.carapis.com/v1/parsers/guazi
Authentication: Bearer token required
Rate Limit: 1000 requests per hour
Response Format: JSON
Data Freshness: Real-time (15-minute updates)

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer guazi_parser_sk_1234567890abcdef1234567890abcdef

API Key Format

Your Guazi.com parser API key follows this format: guazi_parser_sk_ followed by a 32-character hexadecimal string.

Base URL and Headers

Base URL

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

Required Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Endpoints

Search Vehicles

Search for vehicles on Guazi.com with various filters and parameters.

Endpoint: GET /search

Parameters

Parameter	Type	Required	Description	Example
`keyword`	string	No	Search keyword (brand, model, etc.)	`"BMW 3 Series"`
`brand`	string	No	Vehicle brand	`"BMW"`
`model`	string	No	Vehicle model	`"3 Series"`
`min_price`	integer	No	Minimum price in CNY	`200000`
`max_price`	integer	No	Maximum price in CNY	`300000`
`min_year`	integer	No	Minimum year	`2019`
`max_year`	integer	No	Maximum year	`2023`
`min_mileage`	integer	No	Minimum mileage in km	`10000`
`max_mileage`	integer	No	Maximum mileage in km	`50000`
`fuel_type`	string	No	Fuel type	`"gasoline"`
`transmission`	string	No	Transmission type	`"automatic"`
`location`	string	No	City or region	`"Beijing"`
`seller_type`	string	No	Seller type	`"private"`
`sort`	string	No	Sort order	`"newest"`
`page`	integer	No	Page number (default: 1)	`1`
`limit`	integer	No	Results per page (max: 100)	`20`

Sort Options

newest - Newest listings first
oldest - Oldest listings first
price_low - Lowest price first
price_high - Highest price first
mileage_low - Lowest mileage first
mileage_high - Highest mileage first

Example Request

curl -X GET "https://api.carapis.com/v1/parsers/guazi/search?keyword=BMW&min_price=200000&max_price=300000&limit=10" \
  -H "Authorization: Bearer guazi_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "guazi_123456789",
      "title": "BMW 3 Series 320i 2019",
      "price": "280000",
      "currency": "CNY",
      "year": "2019",
      "month": "6",
      "mileage": "45000",
      "mileage_unit": "km",
      "fuel_type": "gasoline",
      "transmission": "automatic",
      "engine_size": "2.0",
      "engine_power": "156",
      "color": "white",
      "location": "Beijing",
      "seller_type": "private",
      "url": "https://www.guazi.com/vehicle/123456789",
      "image_url": "https://img.guazi.com/vehicle/123456789.jpg",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "page": 1,
    "limit": 10,
    "pages": 125
  }
}

Get Vehicle Details

Retrieve detailed information about a specific vehicle.

Endpoint: GET /vehicle/\{vehicle_id\}

Parameters

Parameter	Type	Required	Description
`vehicle_id`	string	Yes	Vehicle ID from search results

Example Request

curl -X GET "https://api.carapis.com/v1/parsers/guazi/vehicle/guazi_123456789" \
  -H "Authorization: Bearer guazi_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "id": "guazi_123456789",
    "title": "BMW 3 Series 320i 2019",
    "price": "280000",
    "currency": "CNY",
    "year": "2019",
    "month": "6",
    "mileage": "45000",
    "mileage_unit": "km",
    "fuel_type": "gasoline",
    "transmission": "automatic",
    "engine_size": "2.0",
    "engine_power": "156",
    "color": "white",
    "location": "Beijing",
    "seller": {
      "name": "Private Seller",
      "type": "private",
      "rating": "4.8",
      "response_time": "2 hours",
      "total_sales": "15"
    },
    "description": "Well-maintained BMW 3 Series with full service history. Single owner, no accidents. All original parts. Perfect condition for daily driving or weekend trips.",
    "features": ["Leather Seats", "Navigation System", "Bluetooth Connectivity", "Parking Sensors", "Sunroof", "Heated Seats"],
    "images": ["https://img.guazi.com/vehicle/123456789_1.jpg", "https://img.guazi.com/vehicle/123456789_2.jpg", "https://img.guazi.com/vehicle/123456789_3.jpg"],
    "url": "https://www.guazi.com/vehicle/123456789",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Get Brands

Retrieve list of available vehicle brands on Guazi.com.

Endpoint: GET /brands

Example Request

curl -X GET "https://api.carapis.com/v1/parsers/guazi/brands" \
  -H "Authorization: Bearer guazi_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "brand": "BMW",
      "count": 12500,
      "avg_price": "350000"
    },
    {
      "brand": "Mercedes-Benz",
      "count": 11800,
      "avg_price": "380000"
    },
    {
      "brand": "Audi",
      "count": 9800,
      "avg_price": "320000"
    }
  ]
}

Get Models

Retrieve list of models for a specific brand.

Endpoint: GET /models/\{brand\}

Parameters

Parameter	Type	Required	Description
`brand`	string	Yes	Brand name

Example Request

curl -X GET "https://api.carapis.com/v1/parsers/guazi/models/BMW" \
  -H "Authorization: Bearer guazi_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "model": "3 Series",
      "count": 4500,
      "avg_price": "280000"
    },
    {
      "model": "5 Series",
      "count": 3200,
      "avg_price": "420000"
    },
    {
      "model": "X3",
      "count": 2800,
      "avg_price": "380000"
    }
  ]
}

Get Statistics

Retrieve market statistics and analytics.

Endpoint: GET /statistics

Parameters

Parameter	Type	Required	Description
`brand`	string	No	Filter by brand
`location`	string	No	Filter by location
`period`	string	No	Time period (day, week, month)

Example Request

curl -X GET "https://api.carapis.com/v1/parsers/guazi/statistics?period=month" \
  -H "Authorization: Bearer guazi_parser_sk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "total_listings": 2500000,
    "new_listings_today": 8500,
    "avg_price": "280000",
    "price_trend": "+5.2%",
    "top_brands": [
      {
        "brand": "BMW",
        "count": 125000,
        "market_share": "5.0%"
      },
      {
        "brand": "Mercedes-Benz",
        "count": 118000,
        "market_share": "4.7%"
      }
    ],
    "top_locations": [
      {
        "location": "Beijing",
        "count": 450000,
        "market_share": "18.0%"
      },
      {
        "location": "Shanghai",
        "count": 375000,
        "market_share": "15.0%"
      }
    ]
  }
}

Response Format

Success Response

All successful API responses follow this format:

{
  "success": true,
  "data": {
    // Response data here
  },
  "pagination": {
    // Pagination info (if applicable)
  }
}

Error Response

Error responses follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details"
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Invalid or missing API key
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`INVALID_PARAMETERS`	400	Invalid request parameters
`VEHICLE_NOT_FOUND`	404	Vehicle not found
`INTERNAL_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

Rate Limiting

Rate Limits

Standard Plan: 1,000 requests per hour
Professional Plan: 10,000 requests per hour
Enterprise Plan: 100,000 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642233600

Data Types

Vehicle Object

{
  "id": "string",
  "title": "string",
  "price": "string",
  "currency": "string",
  "year": "integer",
  "month": "integer",
  "mileage": "integer",
  "mileage_unit": "string",
  "fuel_type": "string",
  "transmission": "string",
  "engine_size": "string",
  "engine_power": "string",
  "color": "string",
  "location": "string",
  "seller_type": "string",
  "url": "string",
  "image_url": "string",
  "created_at": "string (ISO 8601)",
  "updated_at": "string (ISO 8601)"
}

Seller Object

{
  "name": "string",
  "type": "string",
  "rating": "string",
  "response_time": "string",
  "total_sales": "string"
}

Pagination Object

{
  "total": "integer",
  "page": "integer",
  "limit": "integer",
  "pages": "integer"
}

Code Examples

Python

import requests
import json

class GuaziAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.carapis.com/v1/parsers/guazi"
        self.headers = {
            "Authorization": f"Bearer \{api_key\}",
            "Content-Type": "application/json"
        }

    def search_vehicles(self, **params):
        response = requests.get(f"{self.base_url}/search",
                              headers=self.headers, params=params)
        return response.json()

    def get_vehicle_details(self, vehicle_id):
        response = requests.get(f"{self.base_url}/vehicle/\{vehicle_id\}",
                              headers=self.headers)
        return response.json()

    def get_brands(self):
        response = requests.get(f"{self.base_url}/brands",
                              headers=self.headers)
        return response.json()

# Usage
api = GuaziAPI("guazi_parser_sk_1234567890abcdef1234567890abcdef")
vehicles = api.search_vehicles(keyword="BMW", limit=10)

JavaScript

class GuaziAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.carapis.com/v1/parsers/guazi';
    this.headers = {
      Authorization: `Bearer $\{apiKey\}`,
      'Content-Type': 'application/json',
    };
  }

  async searchVehicles(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseURL}/search?$\{queryString\}`, {
      headers: this.headers,
    });
    return response.json();
  }

  async getVehicleDetails(vehicleId) {
    const response = await fetch(`${this.baseURL}/vehicle/$\{vehicleId\}`, {
      headers: this.headers,
    });
    return response.json();
  }

  async getBrands() {
    const response = await fetch(`${this.baseURL}/brands`, {
      headers: this.headers,
    });
    return response.json();
  }
}

// Usage
const api = new GuaziAPI('guazi_parser_sk_1234567890abcdef1234567890abcdef');
api.searchVehicles({ keyword: 'BMW', limit: 10 }).then((data) => console.log(data));

Best Practices

API Usage Tips

Use pagination for large result sets
Implement caching for frequently accessed data
Handle rate limits with exponential backoff
Validate responses before processing
Use HTTPS for all requests

Error Handling

Check response status before processing data
Implement retry logic for transient errors
Log errors for debugging
Handle rate limits gracefully
Validate API key before making requests

Support

Need Help?

API Documentation - Complete technical docs
Support - Technical assistance
Community - Developer community
Status Page - Service status

Start integrating with Guazi.com automotive data today and unlock the Chinese C2C marketplace for your applications.

Get Your API Key →

Authentication​

Base URL and Headers​

Base URL​

Required Headers​

Endpoints​

Search Vehicles​

Parameters​

Sort Options​

Example Request​

Example Response​

Get Vehicle Details​

Parameters​

Example Request​

Example Response​

Get Brands​

Example Request​

Example Response​

Get Models​

Parameters​

Example Request​

Example Response​

Get Statistics​

Parameters​

Example Request​

Example Response​

Response Format​

Success Response​

Error Response​

Error Codes​

Rate Limiting​

Data Types​

Vehicle Object​

Seller Object​

Pagination Object​

Code Examples​

Python​

JavaScript​

Best Practices​

Support​

Authentication

Base URL and Headers

Base URL

Required Headers

Endpoints

Search Vehicles

Parameters

Sort Options

Example Request

Example Response

Get Vehicle Details

Parameters

Example Request

Example Response

Get Brands

Example Request

Example Response

Get Models

Parameters

Example Request

Example Response

Get Statistics

Parameters

Example Request

Example Response

Response Format

Success Response

Error Response

Error Codes

Rate Limiting

Data Types

Vehicle Object

Seller Object

Pagination Object

Code Examples

Python

JavaScript

Best Practices

Support