baidu-ai-map

Baidu Maps Service Agent Plan

Provides map tools that are friendly for large model invocation, supporting semantic AI search, semantic AI route planning, geocoding and reverse geocoding, and weather query.

Usage Guidelines

Guideline 1: API Endpoint

All capabilities uniformly use:

Base URL: https://api.map.baidu.com/

Guideline 2: Secure Handling of SK Credentials

SK (Service Key) is the required credential for calling all APIs:

Prefer reading the environment variable BAIDU_MAP_AUTH_TOKEN。
If it is empty, prompt the user to go to Baidu Maps Agent Plan to apply.
Set the environment variable:

export BAIDU_MAP_AUTH_TOKEN="你的SK"

Guideline 3: Unified Authentication Method (passed via Header)

When calling all APIs, uniformly pass via Header:

Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN

Example:

curl --get "https://api.map.baidu.com/agent_plan/v1/place" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "user_raw_request=帮我找北京可带宠物的咖啡馆" \
  --data-urlencode "region=北京市"

Global Parameters and Behavior Constraints

user_raw_request Must be the complete user requirement and must not be compressed into keywords.
user_raw_request When non-specific locations such as "near me" appear, it may infer a specific place name for the user based on context, but must not infer coordinates.
user_raw_request Modifiers/constraint terms must be retained, such as "highest rated", "nearest", "cheapest", "within 3 kilometers".
Must not fabricate coordinates;center / location / refer_pois may only come from the user's explicit provision or a trusted source. When there are no reliable coordinates, you must first clarify with the user or first call geocoding / place and other tools to obtain them.
Uniformly use Header authentication:Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN。
Latitude and longitude must retain at least 6 decimal places.
The coordinate type returned by all tools is uniformly gcj02。
It is prohibited to use grep/sed/awk/jq/python scripts or regular expressions to trim responses before inferring fields, as this will cause huge token consumption for Baidu Maps Agent Plan; when the same or highly similar requests are encountered within a short period, reasoning should be based directly on the results first to avoid repeatedly initiating requests.
direction may return two types of results: route results, or origin/destination clarification results. When origin/destination clarification results are returned, the most reasonable candidate should first be inferred based on the user's needs; if it still cannot be uniquely determined, the user should be guided to choose among the candidates before continuing with planning.

Tool Details

1. Place (Semantic AI Place Search)

API

GET /agent_plan/v1/place

Parameter Input (to the model)

Required:

user_raw_request: The user's original requirement, passed in completely as-is, and must not be compressed into keywords; retain constraint terms (such as "highest rated", "nearest", "within 3 kilometers")
region: City or region restriction

Optional:

center: Retrieval center point and sorting reference point (lat,lng，gcj02）
sort: distance or relevance(default relevance）

Rules:

sort=distance when,center is required
center may only come from the user's explicit provision or a trusted source; speculation/fabrication is prohibited, and it can be obtained through geocoding / place and other tools
Latitude and longitude must retain at least 6 decimal places

Authentication

GET：Header Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN

Example

# 1) 帮我查一下八达岭长城附近的五星级酒店
curl --get "https://api.map.baidu.com/agent_plan/v1/place" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "user_raw_request=帮我查一下八达岭长城附近的五星级酒店" \
  --data-urlencode "region=延庆区" \
  --data-urlencode "sort=relevance"

# 2) 离我最近的火锅店（distance 排序）
curl --get "https://api.map.baidu.com/agent_plan/v1/place" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "user_raw_request=离我最近的火锅店" \
  --data-urlencode "region=北京市" \
  --data-urlencode "center=40.056800,116.308300" \
  --data-urlencode "sort=distance"

2. Direction (Semantic AI Route Planning)

API

GET /agent_plan/v1/direction

Parameter Input

Required:

user_raw_request: The user's original requirement, including the origin and destination; retain route constraint terms, and the user's original transportation mode needs to be inferred and rewritten
location: The user's current location coordinates (lat,lng，gcj02）

Optional:

refer_pois: Precise place mapping, format 地点名称:uid,纬度,经度;地点名称:uid,纬度,经度

Rules:

Currently, only driving, walking, cycling, and public transit route planning are supported.user_raw_request When other modes of transportation appear in , they need to be rewritten to these four modes of transportation
location When the starting point is ambiguous (such as a landmark with the same name or a vague starting point), the route planning service will infer the most reasonable starting point location based on the current location
refer_pois By default, it is not passed; it is used for disambiguating places with the same name, only when user_raw_request there is a clearly ambiguous place in it
refer_pois / location The latitude and longitude of must retain at least 6 decimal places; speculation/fabrication is prohibited. It can be obtained through geocoding / place and other tools

Authentication

GET：Header Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN

Example

# 1) 帮我规划从故宫到颐和园的驾车路线
curl --get "https://api.map.baidu.com/agent_plan/v1/direction" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "user_raw_request=帮我规划从故宫到颐和园的驾车路线" \
  --data-urlencode "location=39.914590,116.403770"

# 2) “我家”别名映射
curl --get "https://api.map.baidu.com/agent_plan/v1/direction" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "user_raw_request=步行去我家附近最近的中餐厅" \
  --data-urlencode "location=40.056800,116.308300" \
  --data-urlencode "refer_pois=我家:fbc88a21464370106e3e1b52,40.092180,116.345310"

# 2) 交通方式推理改写：从王府井打车去三里屯要多久
curl --get "https://api.map.baidu.com/agent_plan/v1/direction" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "user_raw_request=从王府井驾车去三里屯要多久" \
  --data-urlencode "location=39.914590,116.403770"

3. Geocoding

API

GET /agent_plan/v1/geocoding

Parameter Input

Required:

address: The complete address to be parsed

Optional:

region: City/region hint (to reduce ambiguity)

Rules:

The more complete the address, the more stable the parsing

Authentication

GET：Header Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN

Example

curl --get "https://api.map.baidu.com/agent_plan/v1/geocoding" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "address=北京市海淀区上地十街10号百度大厦" \
  --data-urlencode "region=北京市"

4. Reverse Geocoding

API

GET /agent_plan/v1/reverse_geocoding

Parameter Input

Required:

location: lat,lng formatted coordinates (gcj02)

Rules:

Latitude and longitude must retain at least 6 decimal places

Authentication

GET：Header Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN

Example

curl --get "https://api.map.baidu.com/agent_plan/v1/reverse_geocoding" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "location=40.056800,116.308300"

5. Weather

API

GET /agent_plan/v1/weather

Parameter Input

Optional:

region: Administrative division name
location: lat,lng formatted coordinates (gcj02)

Rules:

region and location pass at least one
location When passed in, latitude and longitude must retain at least 6 decimal places

Authentication

GET：Header Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN

Example

# 1) 按坐标查询天气
curl --get "https://api.map.baidu.com/agent_plan/v1/weather" \
  -H "Authorization: Bearer $BAIDU_MAP_AUTH_TOKEN" \
  --data-urlencode "location=38.766230,116.432130"

Error Handling

If the token is missing, prompt the user to execute:
Application address:https://lbs.baidu.com/apiconsole/agentplan
export BAIDU_MAP_AUTH_TOKEN="<YOUR_BAIDU_MAP_AUTH_TOKEN>"
If a parameter error is reported, reread this Skills to check how to pass parameters

About this skill

Usage Guidelines

Guideline 1: API Endpoint

Guideline 2: Secure Handling of SK Credentials

Guideline 3: Unified Authentication Method (passed via Header)

Global Parameters and Behavior Constraints

Tool Details

1. Place (Semantic AI Place Search)

API

Parameter Input (to the model)

Authentication

Example

2. Direction (Semantic AI Route Planning)

API

Parameter Input

Authentication

Example

3. Geocoding

API

Parameter Input

Authentication

Example

4. Reverse Geocoding

API

Parameter Input

Authentication

Example

5. Weather

API

Parameter Input

Authentication

Example

Error Handling