AI导哈

汽车列表API

一个基于FastAPI的非官方API和MCP服务器，用于从希腊最大的汽车市场car.gr抓取和访问汽车列表。

  • by eliac7
  • Python
  • 混合部署
  • 更新于
在 GitHub 查看 eliac7/cargr-api

使用说明

Car.gr API

基于非官方FastAPI的API和MCP服务器，用于从 car.gr希腊最大的汽车市场。

特性

  • 🔍 搜索API：使用原生car.gr过滤器进行搜索
  • 📋 汽车详细信息：获取详细的规格、定价和卖家信息
  • 🚗 综合数据：发动机规格、欧洲级、KTEO等
  • 🛡️ 隐形请求：撤退和隐形技术，以减少堵塞
  • ⚡ 快速API：具有自动生成Swagger文档的高性能API

安装

先决条件

  • python 3.13+
  • 紫外线 （推荐）或 点

设置

  1. 克隆仓库
git clone <repository-url>
cd cargr-api
  1. 安装依赖项

使用 紫外线 （推荐）：

uv pip install -e .

使用 点:

pip install -e .

码头工人

构建并运行容器化应用程序：

# Build image
docker build -t cargr-api .

# Run container
docker run -p 8000:8000 cargr-api

API将在以下网址提供：

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和辅助脚本

解析策略

  1. JSON-LD结构化数据（主数据，如果可用）
  2. 使用BeautifulSoup和目标选择器进行HTML解析
  3. 特定嵌入值的正则表达式回退
  4. 复杂布局的顺风网格/表格解析

利率限制和道德

该项目包括避免car.gr超载的防御措施：

  • 请求之间的随机延迟
  • 指数退避和重试逻辑
  • 速率限制检测和尊重暂停
  • 可选的缓存层，以减少重复请求

请负责任地使用，尊重汽车 robots.txt，并在抓取之前阅读他们的服务条款。未经许可，避免高频刮擦或商业使用。

依赖项

使用的关键Python包：

  • fastapi
  • uvicorn
  • beautifulsoup4
  • stealth-requests （或类似的隐形HTTP客户端）
  • pydantic
  • requests
  • 可选： 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存储库上打开问题。

相关 MCP