roadbook-csv

Roadbook CSV - Travel Itinerary CSV Submission Tool

Submit travel itinerary location data via CSV text to automatically generate a roadbook sharing ID and link, allowing the complete itinerary to be viewed on Amap.

Usage Flow

Check environment variable CYEAM_API_KEY
- If not set: prompt the user to set the environment variable first (see "Apply for API Key" below)
- If already set: directly organize the CSV and call the API
Organize CSV data(5 columns, see format description below)
Call the API to generate the roadbook
Return the roadbook link and QR code

CSV Format

One location per line, comma-separated, 5 columns in total:

名称,地址,类型,日期,备注

Column	Description	Example
Name	Location name	China Ceramics and Glass Museum
Address	Detailed address	No. 320 Huaguang Road, Zhangdian District, Zibo City
Type	Attraction/Dining/Accommodation/Starting Point/Other	Attraction
Date	DayX or date	Day1 / 5.1
Remarks	Itinerary remarks	Afternoon / Morning market food stroll

Complete Example

淄博酒店,淄博市张店区某路,住宿,4.30,入住
八大局便民市场,淄博市张店区共青团东路,餐饮,5.1,早市逛吃
中国陶瓷琉璃馆,淄博市张店区华光路320号,景点,5.1,国家级免费
海岱楼钟书阁,淄博市张店区齐盛湖公园内,景点,5.1,夜景打卡
牧羊村烧烤,淄博市张店区林泽街,餐饮,5.1,晚餐

Date and Remarks Format

Day1,下午 → Day one, remark "Afternoon"
5.1,早市逛吃 → May 1, remark "Morning market food stroll"
Day2, → Day two, no remark (leave the remarks column empty)

Note: If the type of the last location on the previous day is "Accommodation", the system will automatically display it as the starting point of the next day on the map and in the itinerary list.

Call the API

Submit CSV to generate a roadbook

Endpoint: https://cyeam-open-main-d02895c.d2.zuplo.dev/api/roadbook/csv

Authentication: Authorization: Bearer $CYEAM_API_KEY

curl -X POST "https://cyeam-open-main-d02895c.d2.zuplo.dev/api/roadbook/csv" \
  -H "Authorization: Bearer $CYEAM_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "名称,地址,类型,日期,备注"

Why use these two domains? The write endpoint (zuplo.dev) is the API gateway of the Cyeam open platform, responsible for receiving CSV data and generating the sharing ID; the read endpoint (cyeam.com) is the frontend display page, through which users view the map roadbook via the link. Both are part of Cyeam's official services.

Returns:

{
  "id": "bf9186906ec8",
  "url": "https://www.cyeam.com/tool/roadbook?id=bf9186906ec8",
  "text": "https://www.cyeam.com/tool/roadbook?id=bf9186906ec8",
  "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Field	Description
`id`	Sharing ID
`url`	Roadbook page link
`text`	Text content to be encoded as a QR code (usually the same as url)
`qrcode`	Base64-encoded PNG QR code image

Get shared roadbook data

Endpoint: https://www.cyeam.com/api/roadbook/get?id={id}

No authentication required

curl -s "https://www.cyeam.com/api/roadbook/get?id=bf9186906ec8"

Returns:

{
  "data": "[{...地点数据JSON数组...}]"
}

Use Cases

Plan travel routes for users

When the user provides a travel plan, organize it into CSV format and call the API:

> 用户：帮我规划一个淄博两日游，第一天住淄博酒店，第二天去八大局吃早点，然后参观陶瓷琉璃馆，晚上吃烧烤。

> 助手：（检查 CYEAM_API_KEY 后，整理为 CSV 调用接口）
curl -X POST "https://cyeam-open-main-d02895c.d2.zuplo.dev/api/roadbook/csv" \
  -H "Authorization: Bearer $CYEAM_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "淄博酒店,淄博市张店区华光路,住宿,Day1,入住
八大局便民市场,淄博市张店区共青团东路,餐饮,Day2,早市逛吃
中国陶瓷琉璃馆,淄博市张店区华光路320号,景点,Day2,下午参观
牧羊村烧烤,淄博市张店区林泽街,餐饮,Day2,晚餐"

> 助手：路书已生成，点击链接查看完整行程地图：https://www.cyeam.com/tool/roadbook?id=xxx

Apply for API Key

If the environment variable CYEAM_API_KEY is not set, or the call returns 401, you need to apply first:

Visit Cyeam Open Platform
Click Sign In in the upper right corner to log in/register
Go to the Developer Portal to create an API Key
Set the environment variable:export CYEAM_API_KEY="YOUR_API_KEY"

Notes

The API accepts text/plain CSV text in the format (not multipart/form-data)
Data is stored in Redis, with a default validity period of 30 days
After the returned link is opened, the frontend will automatically perform geocoding and display it on Amap
Supports overwriting an existing share (add in the URL ?id=已有ID）
The create endpoint domain is cyeam-open-main-d02895c.d2.zuplo.dev, the read endpoint domain is www.cyeam.com, do not modify
If the API call returns a non-200 status code (such as 401/403/404/500), report the specific error message to the user and do not retry