Developer guide

Che168 API Python Tutorial: Search Chinese Used-Car Listings

Search Che168 listings with Python, filter CNY prices, paginate results, and retrieve vehicle photos using XAPI China's REST API.

XAPI China Team

8 minute read

All guidesXAPI field notes

To search Che168 listings from Python, call XAPI China's REST API with an HTTP client such as requests. This tutorial builds a small, bounded search job that saves listing data as JSON and retrieves details for one result.

XAPI China is an independent, unofficial service, not affiliated with Che168 or Autohome. The code below uses its documented endpoints. It does not require a dedicated Python SDK.

Create a key and prepare Python

Sign up, complete email verification if prompted, and create an API key in your dashboard. Save the secret when it is shown. Keep it in a server environment variable:

python -m pip install requests
export XAPICHINA_API_KEY="xcn_YOUR_KEY"

Do not paste the key into frontend JavaScript or commit it to source control. A browser application should call your own server, which makes the authenticated API requests.

Create search_cars.py with this complete example:

import json
import os
import time
import requests

BASE_URL = "https://api.xapichina.com"
session = requests.Session()
session.headers.update({
    "X-API-Key": os.environ["XAPICHINA_API_KEY"],
})


def get_json(path, params=None):
    response = session.get(
        BASE_URL + path,
        params=params,
        timeout=(5, 45),
    )
    response.raise_for_status()
    return response.json()


filters = {
    "brand": "BMW",
    "currency": "cny",
    "price_min": 100000,
    "price_max": 200000,
    "sort": "price_asc",
    "lang": "en",
}

cars_by_id = {}
page = 1
maximum_pages = 2

for request_index in range(maximum_pages):
    if request_index:
        time.sleep(12)
    result = get_json("/v1/search", {**filters, "page": page})
    for car in result["results"]:
        cars_by_id[car["id"]] = car
    page = result["next_page"]
    if page is None:
        break

cars = list(cars_by_id.values())
with open("che168-listings.json", "w", encoding="utf-8") as output:
    json.dump(cars, output, ensure_ascii=False, indent=2)

for car in cars:
    print(car["id"], car["title"], car["price_cny"])

if cars:
    time.sleep(12)
    detail = get_json(f"/v1/cars/{cars[0]['id']}", {"lang": "en"})
    print("Photo URLs:", detail["photos"])

Run it with python search_cars.py. It writes the returned listing objects to che168-listings.json. An empty file containing [] is a valid outcome when there are no matches. The script stops on HTTP errors so an unsuccessful request is not silently treated as an empty search.

The 12-second spacing illustrates a single worker making at most five requests per minute. Other workers share the account's rate limit, so a production application needs a shared request queue.

Understand the China search parameters

China's API uses its own filtering rules. Do not copy parameters from an Encar integration without checking them:

NeedParameter and behavior
Manufacturerbrand, using a supported name or catalog ID
Vehicle ageage_min and age_max, measured in years
Mileagemileage_min and mileage_max, in multiples of 10,000 km
CNY budgetprice_min and price_max, in multiples of ¥10,000
Electric and other new-energy listingsfuel_type=new_energy
Next set of resultspage; follow the response's next_page

Search has a fixed page size of 24. There is no adjustable search limit parameter. year_from and year_to are also not supported China search parameters. Discover current enum values with the public /v1/filters?lang=en endpoint and see filters and pagination.

The code keeps the same filters on every page and deduplicates by listing ID. Inventory can change while you paginate, so two requests do not represent one frozen snapshot of the market.

Keep original prices alongside conversions

price_cny is the normalized yuan price. price_eur can be null when a conversion is unavailable. Never turn a missing price into zero when sorting or displaying listings.

With currency=eur, the API converts budget boundaries inward to supported ¥10,000 steps. A narrow budget can have no valid source-price step. The response still exposes CNY and nullable EUR price fields. Read the currency rules before applying exact-budget assumptions.

Add details and reports deliberately

The example loads details for one listing and reuses the returned photos. Fetching every detail page consumes additional requests, so choose a page budget and a detail budget separately.

For inspection data, call /v1/cars/{id}/inspection?lang=en and check data_available and parse_status. An advertised report is not a guarantee of accessible findings. Our inspection guide covers those states and the limits of insurance evidence.

Handle failures before scheduling this job

A 422 response usually needs a corrected parameter, rather than a retry. For 429, inspect the error and Retry-After; a monthly allowance error will not be resolved by a tight retry loop. Temporary 502 or 503 failures can be retried with a bounded delay.

The Python integration documentation includes a reusable retry helper. Add logging and a shared rate limiter before running several workers. Keep the source URL and collection timestamp with saved records so users can see where and when the data was obtained.

Create your API key or continue with the full API reference.