Tencent Map Assistant

Specific Problems Addressed

When developing or using map-based applications, developers often face issues like fragmented APIs, inconsistent coordinate systems, and complex visualization generation. For instance, creating a travel guide requires integrating location search, route planning, and itinerary organization; directly using GPS raw coordinates in map services can cause tens of meters of offset; and displaying multiple POI results as a map involves base map compatibility and mini-program integration. The Tencent Map Assistant Skill tackles these pain points by encapsulating Tencent Location Services' WebService APIs, providing an end-to-end workflow from natural language input to structured output and visualization rendering.

Core Capabilities and Key Steps

The skill's core capabilities are aligned with Tencent Location Services' official APIs, mainly including:

• AI Travel Guide (travel_guide): Generates multi-day itineraries via natural language queries (e.g., "5-day Wuhan tour"), returning structured data and an output_markdown file containing mini-program QR codes.
• Personal Map Guide (generate_map_guide): Saves a list of locations (requiring prior poi_search calls to obtain real poi_id and coordinates) as a personal map in the Tencent Maps mini-program, generating QR codes for mobile viewing.
• Location Search and Resolution: Includes poi_search (city/area or nearby search), poi_detail (POI details), geocoder/regeocoder (address-coordinate conversion), and coord_translate (batch coordinate system conversion, e.g., GPS(WGS-84) to GCJ-02).
• Routing and Distance: direction plans routes for driving, walking, transit, or cycling, while distance_matrix calculates distance and time between two points.
• Other Tools: weather for weather queries, ip_location for IP-based positioning, and district_list for administrative district queries.

Key usage steps:
1. Key Configuration: The skill automatically retrieves keys from TmapClient or saved ones; if unavailable, it guides users to apply for a temporary key. Users can fix a key via save_key_to_dotenv.
2. Coordinate System Handling: If input coordinates are in GPS or other formats, call coord_translate(type=1) first to convert to GCJ-02 before passing to interfaces like regeocoder or poi_nearby to avoid offsets.
3. Generation and Visualization: Call travel_guide or generate_map_guide to get output_markdown, and output the Markdown content directly. For multi-POI or route displays, HTML web maps can be rendered using structured data with Tencent Map JSAPI GL as the base map.
4. Error Handling: When API calls fail, TmapClient automatically cycles through available keys, and users are directed to error-codes.md for correction methods.

Applicability and Considerations

• Coordinate System Strictness: All internal interfaces exclusively use GCJ-02 coordinates; external coordinate sources (e.g., phone GPS, GPX tracks) must be converted first to prevent offsets.
• Key Security: After generating HTML containing Tencent Map JSAPI GL, check for plaintext key leaks and follow specifications to use proxy solutions.
• Map Compliance: Maps displayed within China must use Tencent Map JSAPI, not unlicensed overseas services, to meet national surveying requirements.
• Data Privacy: travel_guide and generate_map_guide send user data to Tencent servers, adhering to Tencent Location Services' privacy policy.
• API Limits: coord_translate handles up to 100 points per call; travel_guide may take 30-50 seconds per invocation, requiring synchronous waits.