SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbaidu-map-webapi

baidu-map-webapi

Coding & development

View repository

Updated 10-15 20:05

About this skill

web API development guide

Baidu Map web API version development guide. It includes API descriptions and code examples for core modules such as map location search, route navigation, and administrative divisions. It can be used to directly call APIs to obtain results, and can also help developers quickly integrate Baidu Map services.

When it applies

In any of the following scenarios, this guide should be read and the corresponding API should be called:

Route planning and travel decisions

  • Plan driving, walking, cycling, motorcycle, and public transit routes
  • Query the recommended departure time from A to B(e.g., "I want to arrive at 8 PM, what time is suitable to depart?")
  • Predict route duration for departure at a future time(e.g., "How long does it take if I depart at 3 PM?")
  • Query route duration under historical traffic conditions
  • Plan the optimal route including multiple waypoints

Real-time dynamic information

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

Place and POI search

  • Find POI information such as restaurants, hotels, and attractions in a city
  • Search for places within a specified circular area
  • Search for places by administrative division
  • Search POIs with multiple combined conditions
  • Get detailed POI information
  • Input suggestions/place completion prompts
  • Intelligently recommend safe boarding 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 divisions and area queries

  • Query administrative division places
  • Get administrative division boundary coordinates

Development guidelines

In any scenario where this skill is used, please follow these general guidelines:

Guideline 1: API endpoint selection

Baidu Map provides two service endpoints, and the correct endpoint must be selected according to the usage scenario:

Endpoint type Base URL Applicable scenarios
Standard endpoint https://api.map.baidu.com/ Formal development, production environments, code generated for users
Advanced feature experience endpoint https://api.map.baidu.com/map_service/ Officially provided by Baidu Map, only for quickly experiencing advanced permission features when directly called by large models

Usage rules:

  • For development code generated for users,the standard endpoint must be used https://api.map.baidu.com/
  • When a large model directly calls advanced permission features (such as recommended departure time and future route planning) for demonstration/experience, use the experience endpoint
  • The experience endpoint is only for feature experience and demonstration, and must not be used in development or production environments
  • All require AK credentials
  • Before calling the experience endpoint, you must explain to the user: ① an external API call will be initiated using the experience endpoint; ② this call will consume the user's AK quota; and only proceed after obtaining the user's explicit confirmation

Guideline 2: Secure handling of AK credentials

AK (Access Key) is a required parameter before using the skills:

  1. Prefer to read from the environment variable BMAP_WEBAPI_AK the AK in
  2. BMAP_WEBAPI_AKWhen it is empty, prompt the user:Please first go toBaidu Maps Open Platformapply for服务端AK
  3. then set it as an environment variable
export BMAP_WEBAPI_AK="百度地图AK"
  1. When using all capabilities in references/, please use for the ak parameter $BMAP_WEBAPI_AK, as shown in the following example:
curl "https://api.map.baidu.com/place/v3/region?query=美食&region=北京&ak=$BMAP_WEBAPI_AK"

Guideline 3: Addresses/place names are uniformly converted through address_to_poi to

In any scenario that requires convertinguser-input place name or address textinto coordinates/UID,prefer to refer to：

recipes/address_to_poi.md — Convert address/place name to coordinates and POI UID

This file describes the methods for determining two input types and the corresponding invocation methods:

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

Guideline 4: In route calculation, UID takes priority over pure coordinates

When passing parameters to route calculation APIs (driving/walking/cycling/transit):

推荐：同时传坐标 + uid（绑路更精准，尤其对大型 POI） origin_uid / destination_uid 有值时必传

UID is obtained through the method described in references/address_to_poi.md .

Scenario examples (recommended to read first)

When encountering the following scenarios,prefer to use the corresponding recipe, which contains the complete invocation chain, parameter descriptions, and runnable code examples. For usage of a single API, please refer to the "Quick Reference" below.

Address/place name preprocessing (required before route calculation)

recipe file Applicable scenarios Permission requirements
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 scenarios Permission requirements
recipes/route_to_named_place.md User says a place name → plan a 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 the traffic duration for departing at a future time ⚠️ Advanced permission

POI search

recipe file Applicable scenarios Permission requirements
recipes/nearby_poi_search.md Search for a certain type of place near the user Standard AK
recipes/poi_search_to_detail.md Keyword search → get complete POI details Standard AK

Address and coordinates

recipe file Applicable scenarios Permission requirements
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 scenarios Permission requirements
recipes/weather_query.md Obtain local detailed weather information through city name/administrative division code/coordinates Standard AK

Quick reference

Basic concepts

  • references/constants.md - Common 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 division area search: administrative division place search
  • references/circular_region_search.md - Circular area search: circular area place search
  • references/multi_dimensional_search.md - Multi-dimensional search: multi-condition intelligent POI search
  • references/place_detail_search.md - Place detail search: get detailed information for a specified place
  • references/place_input_suggestion.md - Place input suggestion: place input suggestion matching
  • references/geocoding.md - Geocoding: parse address into coordinates

AOI area

  • references/admin_division_query.md - Administrative division query: query China administrative division information

Dynamic data

  • references/domestic_weather_query.md - Domestic weather query: multifunctional 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: cycling route planning scheme search
  • references/driving_route_planning.md - Driving route planning: driving route planning and traffic condition prediction
    • references/capabilities/driving_route_duration.md - Historical driving route duration: set historical duration for driving routes
    • references/capabilities/future_driving_route.md - Future driving route planning: predict future driving route duration
    • references/capabilities/suggested_departure_time.md - Suggested departure time: travel time suggestion with advanced permissions
    • references/capabilities/waypoint_route_planning.md - Intelligent waypoint 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-mode route planning
  • references/walking_route_planning.md - Walking route planning: walking route planning

How to use

Recommended decision path：

  1. The user need isa multi-step chained scenario(such as "input a place name to plan a route", "get nearby POIs") → directly find the corresponding recipe under the recipes/ directory
  2. The user need isthe parameter details of a single API(such as "what values does the tactics parameter of this interface have") → consult the references/ directory

Each references reference file contains:

  • Brief functional description
  • API parameter descriptions and notes

Each recipes scenario contains:

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