Baidu Maps WebAPI Version Development Guide

This guide covers the development of Baidu Maps WebAPI version. It includes API descriptions and code examples for core modules such as map location search, route navigation, administrative divisions, etc. It can be used to directly call APIs to obtain results, and also helps developers quickly integrate Baidu Maps services.

When to Apply

Read this guide and call the corresponding API when encountering any of the following scenarios:

Route Planning and Travel Decision-Making

Plan driving, walking, cycling, motorcycle, and public transport routes
Query suggested departure time from A to B (e.g., "I want to arrive at 8 PM, what time should I depart?")
Predict route travel time for departure at a future time (e.g., "How long will it take if I depart at 3 PM?")
Query route travel time under historical traffic conditions
Plan the optimal route with multiple waypoints

Real-Time Dynamic Information

Query dynamic traffic events along the route (accidents, congestion, construction, etc.)
Query weather information for overseas cities

Location and POI Search

Find POI information such as restaurants, hotels, scenic spots in a city
Retrieve locations within a specified circular area
Retrieve locations by administrative division
Retrieve POIs with combined multiple conditions
Obtain detailed POI information
Input association/place completion prompts
Intelligently recommend safe pick-up points

Address and Coordinate Conversion

Parse address text into latitude and longitude coordinates (geocoding)
Parse latitude and longitude coordinates into address information (reverse geocoding)

Administrative Division and Region Query

Query administrative division locations
Obtain administrative division boundary coordinates

Development Guidelines

Please follow the following general guidelines in any scenario using this skill:

Guideline 1: API Endpoint Selection

Baidu Maps provides two service endpoints, and you must select the correct one based on the usage scenario:

Endpoint Type	Base URL	Applicable Scenarios
Standard Endpoint	`https://api.map.baidu.com/`	Formal development, production environment, code generated for users
Advanced Feature Experience Endpoint	`https://api.map.baidu.com/map_service/`	Officially provided by Baidu Maps, only for large models to directly call to quickly experience advanced permission features

Usage Rules:

For development code generated for users, must use the standard endpoint
```
https://api.map.baidu.com/
```
When large models directly call advanced permission features (such as suggested departure time, future route planning) for demonstration/experience, use the experience endpoint
The experience endpoint is only for feature experience and demonstration, and cannot be used for development or production environments
AK credentials are required for both endpoints
Before calling the experience endpoint, you must inform the user: ① An external API call will be made using the experience endpoint; ② This call will consume the user's AK quota; and obtain explicit confirmation from the user before execution

Guideline 2: AK Credential Security Handling

AK (Access Key) is a mandatory parameter before using this skill:

Prioritize reading the AK from the environment variable
```
BMAP_WEBAPI_AK
```
If
```
BMAP_WEBAPI_AK
```
is empty, prompt the user: Please first apply for a
server-side
AK on the Baidu Maps Open Platform
Then set it as an environment variable

export BMAP_WEBAPI_AK="Baidu Maps AK"

Use
```
$BMAP_WEBAPI_AK
```
for the ak parameter when using all capabilities in references/, example as follows:

curl "https://api.map.baidu.com/place/v3/region?query=food&region=Beijing&ak=$BMAP_WEBAPI_AK"

Guideline 3: Uniform Conversion of Address/Place Name via

address_to_poi

In any scenario where user-input place names or address text needs to be converted into coordinates/UIDs, prioritize referring to:

recipes/address_to_poi.md
— Address/Place Name to Coordinates and POI UID

This document describes the judgment methods and corresponding calling methods for two input types:

Structured address (including house number/building) →
```
references/geocoding
```
API
POI name/landmark/merchant name →
```
references/administrative_region_search
```
API

Guideline 4: UID Priority Over Pure Coordinates for Route Calculation

When passing parameters to route calculation interfaces (driving/walking/cycling/public transport):

Recommended: Pass both coordinates + uid (more precise for route binding, especially for large POIs). Must pass if origin_uid / destination_uid has a value

UID is obtained through the method described in

references/address_to_poi.md

Scenario Examples (Recommended to Read First)

When encountering the following scenarios, prioritize using the corresponding recipe, which contains complete call chains, parameter descriptions, and runnable code examples. For single API usage, please refer to the "Quick Reference" below.

Address/Place Name Preprocessing (Must Read Before Route Calculation)

Recipe File	Applicable Scenario	Permission Requirement
`recipes/address_to_poi.md`	Address text or place name → Coordinates + POI UID (pre-step for route calculation)	Standard AK

Route Planning

Recipe File	Applicable Scenario	Permission Requirement
`recipes/route_to_named_place.md`	User mentions a place name → Plan driving route	Standard AK
`recipes/smart_departure_time.md`	"What time should I depart to arrive on time"	⚠️ Advanced Permission
`recipes/traffic_aware_route.md`	Predict road condition travel time for departure at a future time	⚠️ Advanced Permission

POI Search

Recipe File	Applicable Scenario	Permission Requirement
`recipes/nearby_poi_search.md`	Search for certain types of locations near the user	Standard AK
`recipes/poi_search_to_detail.md`	Keyword search → Obtain complete POI details	Standard AK

Address and Coordinate

Recipe File	Applicable Scenario	Permission Requirement
`recipes/address_to_full_location.md`	Address text → Coordinates + administrative division	Standard AK
`recipes/coordinate_to_structured_address.md`	Coordinates → Structured address + administrative division	Standard AK

Weather Query

Recipe File	Applicable Scenario	Permission Requirement
`recipes/weather_query.md`	Obtain detailed local weather information via city name/administrative division code/coordinates	Standard AK

Quick Reference

Basic Concepts

```
references/constants.md
```
- General Constants: Status codes

Location Search

```
references/global_reverse_geocoding.md
```
- Global Reverse Geocoding: Convert coordinates to location information
```
references/reverse_geocoding_agent.md
```
- Reverse Geocoding Agent: Intelligent reverse geocoding address parsing
```
references/administrative_region_search.md
```
- Administrative Region Search: Retrieve locations by administrative division
```
references/circular_region_search.md
```
- Circular Region Search: Retrieve locations within a circular area
```
references/multi_dimensional_search.md
```
- Multi-Dimensional Search: Intelligent POI retrieval with multiple conditions
```
references/place_detail_search.md
```
- Place Detail Search: Obtain detailed information of a specified location
```
references/place_input_suggestion.md
```
- Place Input Suggestion: Place input prompt matching
```
references/geocoding.md
```
- Geocoding: Parse address into coordinates

AOI Region

```
references/admin_division_query.md
```
- Administrative Division Query: Query administrative division information of China

Dynamic Data

```
references/domestic_weather_query.md
```
- Domestic Weather Query: Multi-functional interface for domestic weather query
```
references/overseas_weather_query.md
```
- Overseas Weather Query: Query weather for overseas cities

Route Navigation

```
references/cycling_route_planning.md
```
- Cycling Route Planning: Retrieve cycling route planning solutions
```
references/driving_route_planning.md
```
- Driving Route Planning: Driving route planning and traffic condition prediction
- ```
references/capabilities/driving_route_duration.md
```
  - Driving Route Historical Duration: Set historical travel time for driving routes
- ```
references/capabilities/future_driving_route.md
```
  - Future Driving Route Planning: Predict travel time for future driving routes
- ```
references/capabilities/suggested_departure_time.md
```
  - Suggested Departure Time: Advanced permission travel time suggestion
- ```
references/capabilities/waypoint_route_planning.md
```
  - Waypoint Intelligent Route Planning: Intelligently optimize waypoint order
```
references/motorcycle_route_planning.md
```
- Motorcycle Route Planning: Motorcycle route planning service
```
references/transit_route_planning.md
```
- Transit Route Planning: Multi-transport mode route planning
```
references/walking_route_planning.md
```
- Walking Route Planning: Walking route planning

How to Use

Recommended Decision Path:

If the user's requirement is a multi-step serial scenario (e.g., "Input place name to plan route", "Obtain nearby POIs") → Directly find the corresponding recipe in the
```
recipes/
```
directory
If the user's requirement is parameter details of a single API (e.g., "What values are available for the tactics parameter of this interface") → Refer to the
```
references/
```
directory

Each references document includes:

Brief function description
API parameter descriptions and notes

Each recipes scenario includes:

Trigger intent (what scenario it applies to)
Complete call chain and step-by-step instructions
Common errors and variants

baidu-map-webapi

NPX Install

Tags

SKILL.md Content (Chinese)