Baidu Maps WebAPI Version Development Guide

When to Apply

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

Guideline 1: API Endpoint Selection

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

https://api.map.baidu.com/map_service/

• 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

1. Prioritize reading the AK from the environment variable

   BMAP_WEBAPI_AK

2. If

   BMAP_WEBAPI_AK

   is empty, prompt the user: Please first apply for a

   server-side

   AK on the Baidu Maps Open Platform
3. Then set it as an environment variable

export BMAP_WEBAPI_AK="Baidu Maps AK"

1. 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

recipes/address_to_poi.md

— Address/Place Name to Coordinates and POI UID

• 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

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

references/address_to_poi.md

Scenario Examples (Recommended to Read First)

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

recipes/address_to_poi.md

Route Planning

recipes/route_to_named_place.md

recipes/smart_departure_time.md

recipes/traffic_aware_route.md

POI Search

recipes/nearby_poi_search.md

recipes/poi_search_to_detail.md

Address and Coordinate

recipes/address_to_full_location.md

recipes/coordinate_to_structured_address.md

Weather Query

recipes/weather_query.md

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

1. 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
2. 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

• Brief function description
• API parameter descriptions and notes

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