openvan-travel

OpenVan.camp 公共 API

免费的免认证 vanlife 数据 API：燃油价格、路线燃油成本、收费公路、节假日和交通高峰日、旅行风险、电源插头、海关规定、汇率、食品成本指数、天气适宜度评分、签证和车辆进口规定、vanlife 活动、新闻，以及全球车牌信息——一站式提供，无需注册。

基础 URL： https://openvan.camp
身份验证： 无需
CORS： 已启用
许可证： 数据采用 CC BY 4.0 许可；本仓库中的代码（SDK、MCP 服务、示例）采用 MIT 许可
必须注明出处： 在展示数据的任何位置都要注明 Data: <a href="https://openvan.camp/">OpenVan.camp</a>，详见出处说明

JavaScript/TypeScript SDK： @openvancamp/sdk — npm install @openvancamp/sdk。零配置，带类型支持，适用于 Node.js／浏览器／边缘环境。SDK 文档 →

Python SDK： openvan — pip install openvan。无依赖，支持 Python 3.9 及以上版本，可与 pandas 配合使用。Python 文档 →

每日 CSV 快照： openvancamp/openvan-travel-data — 提供燃油价格、汇率、食品成本指数和天气评分的 CSV/JSON 数据，每天提交一次，并保留历史记录。

MCP 服务（适用于 AI Agent）： mcp-server/ — 提供 30 个只读工具，在 Claude 和 ChatGPT 中带交互式卡片（含 plan_road_trip，可生成完整行程路书）；托管于 https://mcp.openvan.camp/mcp，也可通过 npx -y @openvancamp/mcp-server 在本地运行，适用于 Claude Desktop／Cursor／Windsurf。安装文档 → · AI Agent 指南 →

Gemini CLI 扩展： 使用 gemini extensions install https://github.com/openvancamp/openvan-camp-public-api 安装本仓库。根目录中的 gemini-extension.json 可将 Gemini CLI 直接连接到托管的 OpenVan.camp MCP 服务；无需 API 密钥。 **面向编码 Agent 的插件（Claude Code、Codex）：**托管的 MCP 服务加上两个Agent 技能 — openvan-travel 使用合适的工具回答旅行问题， openvan-api 基于此 API 编写代码，并正确处理署名、各等级燃油单位和缓存。Claude Code：/plugin install openvan-camp --marketplace openvancamp/openvan-camp-public-api（或先运行 /plugin marketplace add openvancamp/openvan-camp-public-api，再运行 /plugin install openvan-camp@openvan-camp）。Codex：codex plugin marketplace add openvancamp/openvan-camp-public-api，然后从 Plugins Directory 安装 OpenVan.camp。适用于任何 Agent 的纯技能：npx skills add openvancamp/openvan-camp-public-api。

在 AI 助手中使用，无需编写代码：Claude 连接器 · ChatGPT 应用 · Telegram 机器人 @OpenVanCampBot — 在聊天中以交互卡片形式呈现相同数据。查看连接方法 →

---

哪些内容具有权威性

资源	用途
本 README	快速概览和代码示例
/docs	带有“试用”功能的交互式文档
/docs.openapi	完整的 OpenAPI 3.0 契约（始终保持最新）
/docs.postman	Postman 集合

/docs.openapi 中的 OpenAPI 规范由实时代码库生成，是权威契约。本 README 中的数字（国家/地区数量、故事总数）均为近似值，并会定期更新 — 请查看 /api/fuel/prices 元数据或 /api/stories 分页结果以获取当前总数。

---

端点

端点	描述	覆盖范围
GET /api/fuel/prices	零售燃油价格（汽油、柴油、LPG、E85）	160 多个国家
POST /api/route-cost	计算途经 2–10 个途经点的路线燃油费用，按国家提供价格	—
POST /api/roadbook/from-places	根据 2–10 个地点名称生成完整行程路书：逐日计划、预算、各国入境和车辆规定；返回可分享页面	—
GET /api/roadbook/{code}/status	路书生成状态（轮询直到状态为 ready）	—
GET /api/tolls/countries	各国收费公路：收费系统、按公里和车辆类别划分的费率、通行贴纸	84 个国家
GET /api/tolls/route	计算途经 2–10 个地点名称的路线通行费（轿车、面包车、重型车辆），以欧元范围表示	—
GET /api/holidays/countries/{code}?from=&to=	公共假日、学校假期（地区级）和交通高峰日	212 个国家
GET /api/hazards/countries/{code}	英国 FCDO 旅行建议等级和 GDACS 当前自然灾害	—
GET /api/hazards/fires?bbox=	NASA FIRMS 边界框内过去 48 小时的活跃火点（最多 10°×10°）	全球
GET /api/electricity/countries/{code}	插头类型、市电电压和频率、露营地电源接口（CEE17）	229 个国家
GET /api/customs/countries/{code}?from=	驾车入境海关规定：食品、现金、酒精、烟草、燃油桶	—
GET /api/currency/rates	相对于 EUR 的汇率	150 多种货币
GET /api/vanbasket/countries	相对于世界平均水平的食品价格指数（100 = 世界平均水平）	90 多个国家
GET /api/vanbasket/compare?from=DE&to=TR	比较两个国家的食品费用	—
GET /api/vanbasket/countries/{code}	单个国家及历史快照	—
GET /api/vansky/weather	房车生活天气适宜度评分（0–100）及 7 天预报	160 多个国家
GET /api/vansky/weather/{code}	单个国家，含海洋和太阳能数据	—
GET /api/vansky/weather/{code}/{city}	单个城市的页面数据：今天和本周天气、城市在该国的位置、每日评分明细、最差天气日、空气质量、建议（使用 include=hourly 获取每 3 小时的数据）	—
GET /api/vansky/weather/{code}/cities	按周评分（与网站相同）或今日评分对某国城市进行排名	—
GET /api/vansky/ranking	按地区列出周评分或今日评分排名靠前的国家	160 多个国家
GET /api/vansky/methodology	VanSky 评分计算方式：曲线、权重、调整项——可自行重新计算	—
GET /api/vansky/climate?lat=&lng=&date=	获取全球任意地点一年中任意一天的典型天气（ERA5 2021–2025）：温度、降水天数、天空、海洋、太阳能、VanSky 指数、月份、最佳月份	全球
GET /api/vansky/climate/{code}/{city}	获取 VanSky 城市的相同数据	—
GET /api/visa/check?passport=RU&destination=TR	入境规定：入境方式、停留时长、天数计算方式、车辆进口	199 个目的地
GET /api/visa/route?t=RU,GE,TR&p=RU	整条路线的签证规定，最多 10 本护照	—
GET /api/visa/passport/{code}	某本护照适用的所有目的地	—
GET /api/visa/vehicle/{place}	某国的车辆临时进口规定	—
GET /api/events	房车生活活动：展会、节庆、聚会、自驾游	1,100 多场活动
GET /api/event/{slug}	完整活动详情及地理坐标	—
GET /api/event/{slug}/articles	与活动关联的来源文章	—
GET /api/stories	汇总自 200 多家出版商的新闻报道	31,000 多篇报道
GET /api/story/{slug}	完整报道，含所有来源文章和直接链接	—
GET /api/news/search?q=...	对新闻报道进行语义搜索	—
GET /api/plates	全球车牌：格式、地区代码、示例车牌	199 个国家
GET /api/plates/{code}/types	某国的车牌类型（私人、出租车、摩托车、外交车辆……）；未细分的国家返回空值	—
GET /api/plates/{code}/plate.svg	可直接使用的车牌图像（也支持 .png）——可放入 <img src>	—

---

快速入门

# Fuel prices
curl https://openvan.camp/api/fuel/prices

# Currency rates (EUR-based)
curl https://openvan.camp/api/currency/rates

# Food price index
curl https://openvan.camp/api/vanbasket/countries

# Upcoming vanlife events in Germany
curl "https://openvan.camp/api/events?country=DE&status=upcoming&locale=en"

# Latest vanlife news stories in English
curl "https://openvan.camp/api/stories?locale=en"

---

燃油价格 — /api/fuel/prices

来自 45 多个官方政府来源的每周零售价格。
缓存 TTL： 6 小时。请勿以短于每 10 分钟一次的频率轮询。

curl https://openvan.camp/api/fuel/prices

{
  "success": true,
  "data": {
    "DE": {
      "country_code": "DE",
      "country_name": "Germany",
      "region": "europe",
      "currency": "EUR",
      "local_currency": "EUR",
      "unit": "liter",
      "prices": {
        "gasoline": 1.79,
        "diesel": 1.69,
        "lpg": 0.89,
        "e85": null,
        "premium": null
      },
      "price_changes": { "gasoline": -0.02, "diesel": 0.01, "lpg": 0.0 },
      "fetched_at": "2026-04-05T10:00:00+00:00",
      "sources": ["EU Weekly Oil Bulletin", "Fuelo.net"],
      "sources_count": 2,
      "is_excluded": false
    }
  },
  "meta": {
    "total_countries": 121,
    "updated_at": "2026-04-05 10:00:00",
    "cache_ttl_hours": 6
  }
}

说明：

• 大多数国家的 unit 为 "liter"，美国和厄瓜多尔为 "gallon"
• is_excluded: true 表示该国燃油补贴力度较大（价格无法反映市场水平）
• price_changes = 与上周价格相比的变化量

---

汇率 — /api/currency/rates

以 EUR 为基准的汇率，来自多个开源提供方，并支持自动回退。
缓存 TTL： 25 小时。每日 07:00 UTC 刷新。

curl https://openvan.camp/api/currency/rates

{
  "success": true,
  "rates": {
    "EUR": 1,
    "USD": 1.08,
    "GBP": 0.85,
    "TRY": 38.5,
    "GEL": 2.95,
    "KZT": 510,
    "RUB": 98.5
  },
  "cached": true,
  "updated_at": "2026-04-08T07:00:00+00:00"
}

换算为任意货币：

const priceInUSD = (priceEUR / rates.EUR) * rates.USD;
const priceInTRY = (priceEUR / rates.EUR) * rates.TRY;

---

VanBasket 食品价格指数 — /api/vanbasket/*

食品篮子的相对成本，与全球平均水平相比（World = 100）。
基于 World Bank ICP 2021 数据，并使用 IMF CPI 进行调整。
数据来源： CC BY 4.0

# All countries
curl https://openvan.camp/api/vanbasket/countries

# Compare two countries
curl "https://openvan.camp/api/vanbasket/compare?from=DE&to=TR"

# Single country with historical snapshots
curl https://openvan.camp/api/vanbasket/countries/DE

{
  "success": true,
  "data": {
    "CH": { "country_code": "CH", "country_name": "Switzerland", "vanbasket_index": 162.3, "pct_vs_world": 62.3 },
    "DE": { "country_code": "DE", "country_name": "Germany",     "vanbasket_index": 118.7, "pct_vs_world": 18.7 },
    "TR": { "country_code": "TR", "country_name": "Turkey",      "vanbasket_index":  82.4, "pct_vs_world": -17.6 },
    "GE": { "country_code": "GE", "country_name": "Georgia",     "vanbasket_index":  64.1, "pct_vs_world": -35.9 }
  },
  "meta": {
    "total_countries": 92,
    "world_avg": 100,
    "base_year": 2021,
    "source": "World Bank ICP 2021",
    "license": "CC BY 4.0"
  }
}

比较响应：

{
  "success": true,
  "data": {
    "from": { "country_code": "DE", "country_name": "Germany", "vanbasket_index": 118.7 },
    "to":   { "country_code": "TR", "country_name": "Turkey",  "vanbasket_index":  82.4 },
    "diff_percent": -30.6,
    "budget_100": 69,
    "cheaper": true
  }
}

budget_100：如果你在 from 国家花 €100 购买食品，在 to 国家只需花 €69。

---

活动 — /api/events

Vanlife 活动：展览、节庆、聚会、自驾游。实时更新。

查询参数：

参数	值	默认值
locale	en ru de fr es pt tr	en
status	upcoming ongoing past all	upcoming
type	expo festival forum meetup roadtrip	—
country	ISO 3166-1 alpha-2	—
search	文本	—
page	整数	1
limit	整数（最大 100）	30

# Upcoming events in Germany
curl "https://openvan.camp/api/events?country=DE&status=upcoming&locale=en"

# Event details
curl "https://openvan.camp/api/event/fit-camper-2026?locale=en"

# Source articles linked to an event
curl "https://openvan.camp/api/event/fit-camper-2026/articles?locale=en"

{
  "events": [
    {
      "id": 493,
      "slug": "fit-camper-2026",
      "event_name": "Fit Your Camper",
      "event_type": "expo",
      "event_type_label": "Exhibition",
      "start_date": "2026-04-09",
      "end_date": "2026-04-12",
      "city": "Bologna",
      "country_code": "IT",
      "country": { "code": "it", "name": "Italy", "flag_emoji": "🇮🇹" },
      "venue_name": "BolognaFiere",
      "status": "upcoming",
      "articles_count": 7,
      "url": "https://openvan.camp/en/event/fit-camper-2026"
    }
  ],
  "pagination": { "total": 48, "page": 1, "limit": 30, "pages": 2 }
}

说明：

• 未知或缺失的 locale 会自动回退到 en
• /api/event/{slug}/articles 会按 locale 筛选来源文章；如果没有匹配项，则返回所有文章（可能使用原始发布者的语言）

---

故事 / 新闻 — /api/stories

从 200 多家发布者汇总的 Vanlife 新闻故事，并翻译成 7 种语言。每个故事会聚合报道同一主题的多篇来源文章。

查询参数：

参数	值	默认值
locale	en ru de fr es pt tr	en
category	类别 slug（例如 camping、travel、gear、incident）	—
country	ISO 3166-1 alpha-2	—
search	文本	—
page	整数	1
limit	整数（最大 50）	20

# Latest stories in English
curl "https://openvan.camp/api/stories?locale=en"

# German vanlife news in Germany
curl "https://openvan.camp/api/stories?locale=de&country=DE"

# Full story with all source links
curl "https://openvan.camp/api/story/free-overnight-parking-netherlands?locale=en"

{
  "slug": "free-overnight-parking-netherlands",
  "title": "Free Overnight Parking for Motorhomes in the Netherlands",
  "summary": "The Dutch motorhome community is pushing for more designated free overnight spots...",
  "image_url": "https://...",
  "category": { "slug": "travel", "name": "Travel" },
  "countries": [{ "code": "nl", "name": "Netherlands", "flag_emoji": "🇳🇱" }],
  "first_published_at": "2026-04-01T10:00:00+00:00",
  "last_updated_at": "2026-04-03T08:00:00+00:00",
  "articles_count": 5,
  "url": "https://openvan.camp/en/news/travel/free-overnight-parking-netherlands",
  "sources": [
    {
      "title": "Gratis overnachten in je camper: de beste plekken",
      "original_url": "https://www.campermagazine.nl/overnachten/gratis-plaatsen",
      "source_name": "CamperMagazine.nl",
      "published_at": "2026-04-01T10:00:00+00:00",
      "language": "nl",
      "image_url": "https://..."
    }
  ]
}

说明：

• title 和 summary 会翻译成请求的 locale
• 无论 locale 为何，sources[].language 始终表示原始发布者的语言
• sources[].original_url 是指向发布者文章的直接链接

---

车牌 — /api/plates/*

世界各地的车牌：车牌格式、按地区分组的所有地区代码（包含 ISO 3166-2 单位）、验证，以及车牌图片。图片由与 openvan.camp/en/license-plates 相同的引擎绘制——车牌字体以矢量轮廓的形式内置，因此无需安装字体。

最简单的集成方式是直接使用图片：

<img src="https://openvan.camp/api/plates/ru/plate.svg?number=A123BC&region=77" alt="A123BC 77">

• plate.png?width=800 — PNG，宽度为 200–2000 px，背景透明
• 外形相似的拉丁字母会自动规范化（A123BC → 俄罗斯车牌上的 А123ВС）
• 不符合国家格式的号码会返回 422；添加 custom=1 可绘制任意文本（例如姓名）
• 图片使用 Cache-Control: public, max-age=31536000, immutable 提供；API 返回的图片 URL 带有 v=<engine version>，因此引擎更新后会使用新的 URL

curl https://openvan.camp/api/plates                                        # countries
curl "https://openvan.camp/api/plates/ru?locale=en"                         # format, regions, codes, engine
curl "https://openvan.camp/api/plates/ru/validate?number=A123BC&region=799" # valid? which region?
curl https://openvan.camp/api/plates/ru/random                              # random plate + image URLs

车牌类型 — 特殊车牌有各自的颜色和号码格式。GET /api/plates/{code}/types 会列出这些类型（俄罗斯车牌包括：private、红色的 diplomatic、蓝色的 police、黑色的 military、黄色的 taxi_bus、 motorcycle、trailer、tractor、export_transit），每种类型都附有示例号码。向图片、/random 和 /validate 传入 type；响应会说明使用了哪种 type：

curl "https://openvan.camp/api/plates/ru/random?type=police"                # a valid blue police plate + image URLs
curl "https://openvan.camp/api/plates/ru/validate?number=У7962&region=790&type=police"

<img src="https://openvan.camp/api/plates/ru/plate.svg?number=190Т307&region=23&type=diplomatic" alt="190 Т 307 23">

若要在浏览器中自行绘制车牌（例如制作交互式生成器），请按顺序加载 /api/plates/{code} 的 data.engine.scripts 中列出的脚本，然后调用 Plates.render(code, number, region) → {svg}（SVG 元素）或 {error}。

对于车牌字体可再分发的国家（glyphs_license 为 free 或 sharealike），图片和引擎均可用；其他国家的数据端点仍可正常使用。 速率限制：图片和 /random 每分钟 60 次请求，其余端点每分钟 120 次。

---

路书 — /api/roadbook/from-places

一份完整的行程计划——与人们在向导中创建的路书相同：路线、驾驶日程与过夜安排、预算（燃油、通行费、通行证、渡轮），以及沿途每个国家针对指定护照和车牌的入境与车辆规定、节假日、安全情况和电源插座。相同的请求会返回相同的路书。

# 1. Create (all inputs are optional)
curl -X POST "https://openvan.camp/api/roadbook/from-places?source=your-app" \
  -H "Content-Type: application/json" \
  -d '{"places":["Munich","Venice"],"locale":"en","inputs":{"travelers":["DE"],"cons":10,"fuel":"diesel"}}'
# → {"code":"wqhk8","url":"/en/roadbook/wqhk8-munich-venice","status":"pending","points":[...]}

# 2. Poll until "ready" (long routes take up to a minute), then open https://openvan.camp + url
curl https://openvan.camp/api/roadbook/wqhk8/status

每个 IP 每分钟可请求 10 份路书。MCP 工具 plan_road_trip 可完成所有这些工作并返回计划本身。

---

节假日、危险信息、电源插头、海关

关于即将驾车前往国家的行程规划数据。每个列表端点都有一个 /countries 索引；传入 locale 可获取翻译后的名称。

# Public, school (with ISO 3166-2 regions) and peak traffic days; kind=public|school|traffic
curl "https://openvan.camp/api/holidays/countries/FR?from=2026-10-01&to=2026-11-15"

# FCDO travel advice level + current GDACS disasters (flood, earthquake, cyclone, wildfire…)
curl https://openvan.camp/api/hazards/countries/TR

# NASA FIRMS fire detections of the last 48 h; bbox = minLon,minLat,maxLon,maxLat, up to 10°×10°
curl "https://openvan.camp/api/hazards/fires?bbox=-1,38,1,40"

# Plug types, voltage, frequency, campsite hook-up connector
curl https://openvan.camp/api/electricity/countries/GB

# Customs rules on entry by car, optionally from a given country; each rule quotes the official source
curl "https://openvan.camp/api/customs/countries/NO?from=DE"

• 如果某个国家没有节假日或海关数据，系统会返回相应错误——这不表示“没有节假日”或“没有任何限制”
• 危险信息描述的是当前情况，而非预测；某个新区域的火灾数据在首次请求时可能会返回“正在加载，请一分钟后重试”

---

响应格式

所有 JSON 端点都遵循一致的封装格式：

{ "success": true, "data": { ... }, "meta": { ... }, "_attribution": { ... } }

每个响应都包含一个 _attribution 对象：

"_attribution": {
  "data_source": "openvan.camp",
  "license": "CC BY 4.0",
  "required": true,
  "attribution_url": "https://openvan.camp/",
  "attribution_html": "Data: <a href=\"https://openvan.camp/\">OpenVan.camp</a> (CC BY 4.0)",
  "instructions": "Attribution is required by the CC BY 4.0 license. ..."
}

错误：

{ "success": false, "error": "Description of the error." }

如果请求中未包含 Accept: application/json，某些错误响应可能会返回 HTML。请始终发送此请求头：

Accept: application/json

---

速率限制

每个 IP 每分钟 120 次请求。请合理使用：

• 燃油价格至少缓存 6 小时
• 汇率至少缓存 1 小时
• 故事/活动至少缓存 15 分钟

---

署名

CC BY 4.0 许可要求必须署名。无论数据展示在何处——网站、应用、机器人、仪表板或文章中——都请在旁边放置一个清晰可见的链接：

Data: <a href="https://openvan.camp/">OpenVan.camp</a> (CC BY 4.0)

每个响应都会通过 _attribution.attribution_html 返回相同的代码片段，并在 X-Attribution-Required 响应头中提供。

正在使用 AI 编码 Agent 构建项目？ 请告诉它在生成的 UI 中保留此链接，或者直接让它读取任意响应中的 _attribution.instructions。

识别你的集成

在任意请求中传入 ?source=yoursite.com，无需注册。该值会作为 _attribution.your_source 返回，供你确认其是否正常工作：

curl "https://openvan.camp/api/fuel/prices?source=myapp.com"

{
  "success": true,
  "data": { "..." },
  "meta": { "..." },
  "_attribution": {
    "data_source": "openvan.camp",
    "license": "CC BY 4.0",
    "required": true,
    "attribution_url": "https://openvan.camp/",
    "attribution_html": "Data: <a href=\"https://openvan.camp/\">OpenVan.camp</a> (CC BY 4.0)",
    "instructions": "Attribution is required by the CC BY 4.0 license. ...",
    "your_source": "myapp.com"
  }
}

这有助于我们了解数据的使用方式，并向活跃项目致谢。

---

使用 OpenVan 构建的项目

使用该 API 的公开项目：

项目	功能	使用的数据
cyfuel	燃油价格地图，可按“高效加油”排名：油箱加满的费用加上开车前往所消耗的燃油（cyfuel.cybush.uk）	燃油价格
DriveLog	驾驶和燃油记录 Web 应用	燃油价格
E-Logistic	按国家显示欧盟柴油价格的物流平台	燃油价格

使用这些数据构建了项目？欢迎提交拉取请求，将其添加到此表，或在 讨论区 告诉我们。

README 徽章：

[![Data: OpenVan.camp](https://img.shields.io/badge/data-OpenVan.camp-467187)](https://openvan.camp/)

---

JavaScript / TypeScript SDK

npm install @openvancamp/sdk
# or: pnpm add @openvancamp/sdk

import { OpenVan } from "@openvancamp/sdk";

const ov = new OpenVan();

// Cheapest diesel in Europe (top 5, EUR-normalized)
const top5 = await ov.fuel.cheapest("diesel", 5);
top5.forEach(c => console.log(c.country_name, c.prices.diesel, c.currency));

// Is Portugal cheaper than Germany for van living?
const comp = await ov.basket.compare("DE", "PT");
console.log(`Portugal is ${Math.abs(comp.diff_percent)}% cheaper`);

// Vanlife weather suitability — top 10 countries right now
const weather = await ov.weather.top({ limit: 10 });

原生支持 ESM，类型完整（包含 TypeScript），适用于 Node.js ≥ 18、浏览器、Cloudflare Workers、Deno 和 Bun。无需 API 密钥。

npm：‍@openvancamp/sdk · 完整 SDK 文档 →

---

资源

• 交互式文档： openvan.camp/docs
• OpenAPI 3.0 规范： https://openvan.camp/docs.openapi
• Postman 集合： https://openvan.camp/docs.postman
• JavaScript SDK： https://www.npmjs.com/package/@openvancamp/sdk
• Python SDK： python-sdk/ — pip install openvan
• 每日 CSV 快照及历史记录： openvancamp/openvan-travel-data
• Claude、ChatGPT 和 Telegram： openvan.camp/en/assistant
• 开发者页面： openvan.camp/en/developers
• 面向 AI Agent（MCP、llms.txt）： openvan.camp/ai

网站上的相同数据

各国燃油价格 · 护照和签证查询工具 · Roadbook 行程规划工具 · VanSky 天气 · 食品费用指数 · Vanlife 活动 · Vanlife 新闻