Car.gr API
基于非官方FastAPI的API和MCP服务器，用于从 car.gr希腊最大的汽车市场。
______________________________________________________________________
特性
- 🔍 搜索API：使用原生car.gr过滤器进行搜索
- 📋 汽车详细信息：获取详细的规格、定价和卖家信息
- 🚗 综合数据：发动机规格、欧洲级、KTEO等
- 🛡️ 隐形请求：撤退和隐形技术，以减少堵塞
- ⚡ 快速API：具有自动生成Swagger文档的高性能API
______________________________________________________________________
安装
先决条件
- python 3.13+
- 紫外线 （推荐）或 点
______________________________________________________________________
设置
- 克隆仓库
git clone
cd cargr-api- 安装依赖项
使用 紫外线 （推荐）：
uv pip install -e .使用 点:
pip install -e .______________________________________________________________________
码头工人
构建并运行容器化应用程序：
# Build image
docker build -t cargr-api .
# Run container
docker run -p 8000:8000 cargr-apiAPI将在以下网址提供：
http://localhost:8000______________________________________________________________________
用法
运行服务器
uvicorn main:app --reload或者，如果你运行 main.py 直接（如果提供）：
python main.py______________________________________________________________________
API文档
运行后，访问：
- Swagger用户界面: http://127.0.0.1:8000/docs
- ReDoc: http://127.0.0.1:8000/redoc
______________________________________________________________________
MCP服务器集成
这个API包括一个模型上下文协议（MCP）服务器，允许人工智能助手（如Claude Desktop、Cursor等）使用自然语言直接搜索汽车和检索细节。
通过SSE连接（推荐）
要将此API与MCP客户端一起使用，请将以下配置添加到您的客户端设置中（例如。， claude_desktop_config.json):
{
"mcpServers": {
"cargr-mcp": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}一旦连接，AI将可以访问以下工具：
search_car_listings：使用过滤器搜索汽车（需要先获取过滤器ID）。get_car_details_by_id：获取特定汽车列表的完整详细信息。get_available_filters：检索品牌、型号和其他分类字段的有效ID。
AI使用的重要注意事项
使用时 search 工具，AI必须 第一 使用 get_available_filters 查找以下参数的正确ID make, model, fuel_type等等。猜测ID可能会导致结果为空或不正确。
______________________________________________________________________
API终点
1.获取汽车详细信息
检索特定分类列表的完整详细信息。
GET /api/car/{car_id}例子：
curl http://127.0.0.1:8000/api/car/48949544答复：
{
"car_id": "48949544",
"title": "Fiat 2020 Fiorino Professional",
"price": 10200.0,
"make": "Fiat",
"model": "Fiorino",
"km": 97000.0,
"engine": 1300,
"bhp": 95,
"fueltype": "Diesel",
"transmission": "Manual",
"euro_class": "Euro 6",
"city": "Άγιος Δημήτριος, Ν. Αττικής",
"postal_code": "17341",
"is_dealer": true,
"seller_name": "Tolias Edition",
"url": "https://www.car.gr/classifieds/vans/view/48949544",
"images": ["https://.../1.jpg", "https://.../2.jpg"],
"features": ["air conditioning", "abs"],
"views": 120,
"modified_at": "2025-11-10T12:34:56Z",
"scraped_at": "2025-12-03T15:00:00Z"
}______________________________________________________________________
2.搜索汽车
搜索列表。此端点接受映射到car.gr搜索过滤器的查询参数。
GET /api/search?{query_params}例子：
curl "http://127.0.0.1:8000/api/search?make=13302&fuel_type=2&price-to=12000"常见参数（示例）：
| 参数 | 说明 | 示例 |
|---|---|---|
make | 制造商ID | 13301 （丰田） |
model | 型号ID | 14911 （Aygo） |
price-from | 最低价格（€） | 5000 |
price-to | 最高价格（€） | 15000 |
registration-from | 最小年份 | 2018 |
fuel_type | 燃料ID | 1 （汽油）， 2 （柴油机） |
gearbox_type | 变速器 | manual, automatic |
city | 城市名称或id | Athens 或id |
page | 页码 | 1 |
答复：
返回一个数组 Car 与查询匹配的对象以及分页元数据。
______________________________________________________________________
数据模型
API返回一个 Car 具有以下字段的对象：
- 识别
- car_id, title, url
- 分类
- make, model, category
- 规格
- release_date, engine （cc）， km, bhp, color, fueltype, transmission, doors, seats
- 监管
- euro_class, road_tax, kteo_expiry （MOT）
- 位置
- city, region, postal_code
- 卖家
- is_dealer （布尔）， seller_name, description, views, modified_at
- 媒体
- images （图像URL数组）
- 特性
- features （字符串数组）
- 元数据
- scraped_at （ISO 8601时间戳）
______________________________________________________________________
建筑
main.py：带有路由处理程序的FastAPI应用程序models.py：用于请求/响应验证的Pydantic模型parser.py：使用BeautifulSoup和隐形请求的网络抓取逻辑services/：模块化抓取、缓存和限速助手docker/：Dockerfile和辅助脚本
解析策略
- JSON-LD结构化数据（主数据，如果可用）
- 使用BeautifulSoup和目标选择器进行HTML解析
- 特定嵌入值的正则表达式回退
- 复杂布局的顺风网格/表格解析
______________________________________________________________________
利率限制和道德
该项目包括避免car.gr超载的防御措施：
- 请求之间的随机延迟
- 指数退避和重试逻辑
- 速率限制检测和尊重暂停
- 可选的缓存层，以减少重复请求
请负责任地使用，尊重汽车 robots.txt，并在抓取之前阅读他们的服务条款。未经许可，避免高频刮擦或商业使用。
______________________________________________________________________
依赖项
使用的关键Python包：
fastapiuvicornbeautifulsoup4stealth-requests（或类似的隐形HTTP客户端）pydanticrequests- 可选：
httpx,tenacity,cachetools
通过提供的安装 setup.py/pyproject.toml 或上面的可编辑安装命令。
______________________________________________________________________
例子
搜索价格低于20000欧元的丰田汽油：
curl "http://127.0.0.1:8000/api/search?make=13301&price-to=20000&fuel_type=1"获取特定列表的详细信息：
curl http://127.0.0.1:8000/api/car/48949544______________________________________________________________________
许可与免责声明
本项目提供 仅用于教育目的.使用本软件即表示您同意：
- 尊重汽车
robots.txt和服务条款 - 未经明确许可，不得将此工具用于滥用、高频或商业抓取
- 请理解，作者不对滥用或可能产生的任何法律后果负责
无保修，使用风险自负。
______________________________________________________________________
贡献
欢迎贡献、错误报告和拉取请求。请打开功能请求或问题的问题，并遵循项目的代码风格和测试指南。
______________________________________________________________________
联系
如有疑问或需要帮助，请在GitHub存储库上打开问题。