Baidu Maps API Setup Guide¶

⚠️ STATUS: IMPLEMENTED BUT DISABLED

Baidu Maps integration is fully implemented but disabled by default. The feature flag USE_BAIDU_MAPS=false prevents any Baidu API calls.

To enable: Complete the prerequisites below, then set USE_BAIDU_MAPS=true.

This guide explains how to set up Baidu Maps API for venue searches in China.

Why Baidu Maps for China?¶

Google Maps/Places is blocked in China and has limited/outdated data for Chinese locations. Baidu Maps provides: - Significantly better coverage for Chinese venues, restaurants, and landmarks - Accurate Chinese address formats and place names - Up-to-date business information (hours, ratings, reviews) - Better search results for Chinese language queries

Architecture¶

The system automatically routes venue searches based on destination: - China destinations → Baidu Maps API - Everywhere else → Google Places API

This is handled transparently by the PlacesRouter class.

Prerequisites Checklist¶

Before enabling Baidu Maps, complete the following:

1. Obtain Baidu Maps API key (AK)
Register at https://lbsyun.baidu.com/ (may require Chinese phone number)
Create a server-side application
Copy the AK (Access Key)

2. Configure environment variables

BAIDU_MAP_API_KEY=your_ak_here
USE_BAIDU_MAPS=true

3. Configure IP whitelist in Baidu console
Add Railway server IPs for production
Or use 0.0.0.0/0 for development
4. Test with real China destinations
Verify search results for major cities (Shanghai, Beijing, etc.)
Confirm coordinate accuracy (Baidu uses BD09, we request WGS84)
Test caching behavior
5. Production deployment
Add IP whitelist for production servers
Monitor API quota usage
Set up error alerting

Setting Up Baidu Maps API¶

Step 1: Create a Baidu Account¶

Go to the Baidu Maps Open Platform: https://lbsyun.baidu.com/
Click "注册" (Register) in the top right
You'll need a Chinese phone number for verification
Alternative: Use a business account or contact Baidu support for international access

Step 2: Create an Application¶

Log in to the console: https://lbsyun.baidu.com/apiconsole/key
Click "创建应用" (Create Application)
Fill in the application details:
应用名称 (App Name): archety-backend
应用类型 (App Type): Select "服务端" (Server)
启用服务 (Enable Services): Check:
- Place API / 地点检索
- Geocoding API / 地理编码
Click "提交" (Submit)

Step 3: Configure IP Whitelist¶

After creating the app, click on it to view details
Under "设置" (Settings), configure the IP whitelist:
For development: Add 0.0.0.0/0 (allows all IPs)
For production: Add your server IPs:
- Railway production IPs
- Any other deployment servers
Save the configuration

Step 4: Get Your API Key (AK)¶

In the application details, copy the "AK" (Access Key)
This is your BAIDU_MAP_API_KEY

Step 5: Add to Environment Variables¶

Add the API key to your environment:

# .env (local development)
BAIDU_MAP_API_KEY=your_baidu_ak_here

# Railway (production)
# Add via Railway dashboard → Variables
BAIDU_MAP_API_KEY=your_baidu_ak_here

API Endpoints Used¶

Place Search (`/place/v2/search`)¶

Searches for POIs by keyword within a city/region.

GET https://api.map.baidu.com/place/v2/search
  ?query=南翔馒头店
  &region=上海
  &output=json
  &ak=YOUR_AK
  &scope=2

Place Details (`/place/v2/detail`)¶

Gets detailed information about a specific place.

GET https://api.map.baidu.com/place/v2/detail
  ?uid=abc123...
  &output=json
  &ak=YOUR_AK
  &scope=2

Response Mapping¶

Baidu responses are normalized to match Google Places format:

Baidu Field	Unified Field	Notes
`uid`	`place_id`	Unique identifier
`name`	`name`	Place name
`location.lat/lng`	`coordinates`	WGS84 coordinates
`address`	`formatted_address`	Full address
`overall_rating`	`rating`	1-5 scale
`comment_num`	`user_ratings_total`	Review count
`telephone`	`phone_number`	Phone number
`shop_hours`	`opening_hours.weekday_text`	Business hours
`photos`	`photos`	Photo URLs (premium)

Coordinate Systems¶

Baidu uses multiple coordinate systems: - BD09 (Baidu Mercator) - Default Baidu format - GCJ02 (China encryption) - Required by Chinese law - WGS84 - Standard GPS coordinates

Our API requests use coord_type=1 (WGS84) for consistency with Google.

Rate Limits & Quotas¶

Default quotas for Baidu Maps API: - Daily quota: 30,000 requests (free tier) - QPS limit: 50 requests/second

To increase quotas: 1. Complete developer verification (实名认证) 2. Apply for quota increase in the console 3. Consider upgrading to a paid tier for high traffic

Caching¶

All Baidu API responses are cached in Redis: - Cache TTL: 24 hours (configurable via BAIDU_PLACES_CACHE_TTL) - Cache namespace: baidu_places

This minimizes API calls and costs.

Testing¶

Check China Detection¶

from app.services.location import is_china_destination

assert is_china_destination("Shanghai") == True
assert is_china_destination("Beijing, China") == True
assert is_china_destination("Tokyo") == False
assert is_china_destination("Hong Kong") == False  # Uses Google

Test Venue Search¶

from app.services.location import get_places_router

router = get_places_router()

# This routes to Baidu
results = await router.search_text(
    query="南翔馒头店",
    destination="Shanghai"
)

# This routes to Google
results = await router.search_text(
    query="Tsuta Ramen",
    destination="Tokyo"
)

Troubleshooting¶

Error: Status 2 (Parameter Invalid)¶

Check that region parameter is a valid Chinese city name
Ensure query is not empty

Error: Status 3 (Verify Failure)¶

Check API key is correct
Verify IP whitelist includes your server

Error: Status 4 (Quota Failure)¶

Daily quota exceeded
Apply for quota increase or wait until next day

Error: Status 5 (AK Failure)¶

API key not found or deleted
Re-generate key in console

No Results for Known Places¶

Try searching with Chinese characters: "南翔馒头店" instead of "Nanxiang Mantou"
Ensure region matches the actual city

app/services/location/baidu_client.py - Baidu API client
app/services/location/china_detector.py - China detection logic
app/services/location/places_router.py - API routing
app/config.py - Configuration settings