tencentmap-miniprogram-skill

Tencent Map WeChat Mini Program Development Skill

Help users implement map feature development in WeChat Mini Programs, including map components, location services, map control and backend service capabilities.

Directory Structure

API Documentation

All API documentation is located in the references/ directory:

Map Component Documentation

references/map_component_guide.md - Complete Mini Program map component documentation
- Map basic attributes: longitude, latitude, scale, rotate, skew, etc.
- Markers: display annotations on the map, supporting custom icons, bubbles, labels
- Routes (polyline): draw routes and rainbow lines, supporting arrows and text labels
- Polygon: draw closed areas, supporting dashed borders
- Circle: display circular overlays
- Point clustering: clustered display of large numbers of markers
- Custom bubbles: callout, customCallout
- Map events: tap, viewport changes, marker tap, etc.
- Collision detection: marker collision relationship configuration
- Map controls: compass, scale, 3D building blocks, etc.

MapContext API Documentation

references/mapContext_api/ The directory contains 32 API documents:

Map Control Category

MapContext.md - MapContext overview
wx.createMapContext.md - Create a MapContext instance
MapContext.getCenterLocation.md - Get the coordinates of the map center
MapContext.moveToLocation.md - Move to a specified location
MapContext.getRegion.md - Get the map viewport range
MapContext.getScale.md - Get the map zoom level
MapContext.getRotate.md - Get the map rotation angle
MapContext.getSkew.md - Get the map tilt angle
MapContext.setCenterOffset.md - Set the map center offset
MapContext.setBoundary.md - Limit the map display range
MapContext.includePoints.md - Zoom the viewport to include all coordinate points

Marker Management Category

MapContext.addMarkers.md - Add markers
MapContext.removeMarkers.md - Remove markers
MapContext.translateMarker.md - Translate markers (with animation)
MapContext.moveAlong.md - Move markers along a path (trajectory playback)
MapContext.setLocMarkerIcon.md - Set the location marker icon

Point Clustering Category

MapContext.initMarkerCluster.md - Initialize point clustering configuration
MapContext.addMarkers.md - Add clustered markers

Overlay Category

MapContext.addGroundOverlay.md - Add a custom image layer
MapContext.updateGroundOverlay.md - Update a custom image layer
MapContext.removeGroundOverlay.md - Remove a custom image layer
MapContext.addArc.md - Add an arc
MapContext.removeArc.md - Remove an arc

Visual Layer Class

MapContext.addVisualLayer.md - Add visual layer
MapContext.removeVisualLayer.md - Remove visual layer
MapContext.executeVisualLayerCommand.md - Execute visual layer command

Custom Layer Class

MapContext.addCustomLayer.md - Add personalized layer
MapContext.removeCustomLayer.md - Remove personalized layer

Coordinate Conversion Class

MapContext.toScreenLocation.md - Convert latitude and longitude to screen coordinates
MapContext.fromScreenLocation.md - Convert screen coordinates to latitude and longitude

Other Features

MapContext.openMapApp.md - Launch map app to select navigation
MapContext.eraseLines.md - Erase or gray out added line segments
MapContext.on.md - Listen to map events

Location Services API Documentation

references/wx_location_api/ The directory contains 12 API documents:

Basic Positioning

wx.getLocation.md - Get the current geographic location and speed
wx.getFuzzyLocation.md - Get fuzzy location (privacy protection)

Map Location Picker

wx.chooseLocation.md - Open the map to select a location
wx.choosePoi.md - Select a POI point

Location Display

wx.openLocation.md - View a location using the built-in map

Continuous Positioning

wx.startLocationUpdate.md - Enable receiving location messages when the mini program is in the foreground or background
wx.startLocationUpdateBackground.md - Enable receiving location messages when the mini program enters the foreground or background
wx.stopLocationUpdate.md - Stop receiving location messages
wx.onLocationChange.md - Listen to real-time geographic location change events
wx.onLocationChangeError.md - Listen to real-time geographic location error events
wx.offLocationChange.md - Cancel listening to real-time geographic location change events
wx.offLocationChangeError.md - Cancel listening to real-time geographic location error events

LBS Backend Service Documentation

references/lbs_service_guide/ The directory contains 9 API documents:

SDK Core

qqMapwx.md - QQMapWX SDK core class and usage guide

Search Service

methodSearch.md - Place search (surrounding POI search)
methodGetsuggestion.md - Keyword input suggestions

Geocoding

methodGeocoder.md - Address resolution (address to coordinates)
methodReverseGeocoder.md - Reverse address resolution (coordinates to address)

Route Planning

methodDirection.md - Route planning (driving, walking, cycling, transit)

Distance Calculation

methodCalculatedistance.md - Distance calculation (walking, driving)

Administrative Divisions

methodGetcitylist.md - Get the national city list
methodGetdistrictbycityid.md - Get administrative divisions under a city

Sample Code

assets/examples/ The directory contains 3 complete mini program sample projects:

minicode-location/ - Location feature sample

Complete sample project for obtaining user location

minicode-marker/ - Marker sample

Complete map marker sample project

minicode-markerCluster/ - Point clustering sample

Complete point clustering feature sample project

SDK Library

assets/libs/ Directory:

qqmap-wx-jssdk.js - Tencent Location Service WeChat Mini Program JS SDK
- Complete SDK source code
- Supports place search, route planning, geocoding, and other features

Pre-check: API Key

Check steps

Check whether a formal Key already exists (environment variable TMAP_MINIPROGRAM_KEY or already provided by the user in the conversation)
Case A: Formal Key detected Silently record the Key,continue processing directly according to the user's original intent, without any prompt or interruption。
Case B: No formal Key detected

⛔ Mandatory interception (highest priority) When no formal Key is detected,before the user explicitly completes the selection, no operation is allowed (analyzing requirements, reading files, planning solutions, writing code, calling APIs). The first and only step is: immediately output the selection prompt below, then stop and wait for the user's response.

Output the following content, thenstop and wait for the user's choice：

⚠️ You have not yet configured a formal Key. Please first choose how you want to use it:

Recommended: Go to the official website to register and apply for a formal Key, and enjoy complete, stable service 👉 https://lbs.qq.com/dev/console/key/manage After registering, you can configure it via the environment variable TMAP_MINIPROGRAM_KEY=你的Key or by telling me in the conversation.

Alternatively, you can choose to use the preset trial Key provided by the Tencent Location Service platform (no registration required, ready to use). Please note the limitations of the trial Key:

Call frequency is limited; exceeding it triggers rate limiting

Data stability is average; not recommended for production environments

Interfaces such as electric vehicle routes are unavailable

Please tell me your choice:

Reply "I already have a Key" or directly provide a Key → Switch to formal mode

Reply "Use trial Key" → Continue in restricted mode

After receiving the user's explicit reply, continue according to the user's choice:

User provides a formal Key → Record the Key, switch to formal mode, and continue processing the request
User chooses the trial Key → Switch to trial mode and continue processing the request (see "Trial mode call rules" below)

Trial mode call rules

Under trial mode, the backend services involved in this Skill (QQMapWX SDK, direct wx.request calls to the WebService API) are replaced according to the following rules:

Domain：https://apis.map.qq.com → https://h5gw.map.qq.com
Key parameter：key=none
apptag parameter: Look up the comparison table below based on the interface path

⚠️ The QQMapWX SDK cannot be used directly in trial mode

qqmap-wx-jssdk.js The constructor requires a valid key to be passed in, and internally BASE_URL is hardcoded as https://apis.map.qq.com/ws/. In trial mode, the SDK cannot be used directly; you need tobypass the SDK and use wx.request to directly call trial mode interfaces。

// ✅ 体验模式：使用 wx.request 直接调用（替代 QQMapWX SDK）
function experienceRequest(apiPath, params) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: `https://h5gw.map.qq.com/ws/${apiPath}`,
      data: {
        ...params,
        key: 'none',
        apptag: getApptag(apiPath), // 根据对照表获取
        output: 'json'
      },
      success: (res) => resolve(res.data),
      fail: (err) => reject(err)
    })
  })
}

// 示例：体验模式逆地址解析
experienceRequest('geocoder/v1/', {
  location: '39.984154,116.307490'
}).then(res => console.log(res))

In formal mode, the QQMapWX SDK is still used：

const QQMapWX = require('../../libs/qqmap-wx-jssdk.js')
const qqmapsdk = new QQMapWX({ key: 'YOUR_FORMAL_KEY' })

⚠️ Notes on trial mode parameter formats (important)

Trial mode bypasses the SDK and directly calls the WebService API,the parameter formats of some interfaces differ from those encapsulated by the SDK, and parameters must be passed in the original WebService API format:

1. Place search (/ws/place/v1/search）—— boundary parameters must be constructed manually

SDK's location、region、rectangle、distance Independent parameters such as these in the WebService APIdo not exist, and the SDK will automatically concatenate them into the boundary parameter internally. In experience mode, you must directly pass boundary：

Search type	boundary format	Example
Nearby search	`nearby(纬度,经度,半径米[,auto_extend])`	`nearby(39.984060,116.307520,1000,1)`
City search	`region(城市名[,auto_extend][,纬度,经度])`	`region(北京,0,39.984060,116.307520)`
Rectangle search	`rectangle(左下纬度,左下经度,右上纬度,右上经度)`	`rectangle(39.9,116.3,40.0,116.5)`

// ✅ 体验模式搜索示例：周边搜索附近 1km 内的酒店
experienceRequest('place/v1/search', {
  keyword: '酒店',
  boundary: 'nearby(39.984060,116.307520,1000)',
  orderby: '_distance',
  page_size: 10,
  page_index: 1
})

// ✅ 体验模式搜索示例：在北京搜索酒店
experienceRequest('place/v1/search', {
  keyword: '酒店',
  boundary: 'region(北京,0)'
})

❌ In experience mode, do not pass location、region、rectangle、distance these SDK wrapper parameters; they are not the original parameters of the WebService API.

2. Coordinate parameter format — uniformly use String

The SDK supports Object format { latitude: 39.98, longitude: 116.30 }, while the WebService API only accepts String format '纬度,经度'(latitude first):

Parameter	SDK format (formal mode)	WebService API format (experience mode)
`location`	`{ latitude: 39.98, longitude: 116.30 }` or `'39.98,116.30'`	`'39.98,116.30'`
`from` / `to`	Either Object or String is acceptable	`'39.98,116.30'`

3. Distance calculation — the interface path has changed

The /ws/distance/v1/ interface called internally by the SDK has been discontinued. The apptag comparison table in experience mode maps to the new interface /ws/distance/v1/matrix(distance matrix). Parameter differences:

from：'纬度,经度'(supports multiple origins, ; -separated)
to：'纬度,经度;纬度,经度'(multiple destinations, ; -separated)
mode：'driving' / 'walking' / 'bicycling'

// ✅ 体验模式距离计算示例
experienceRequest('distance/v1/matrix', {
  from: '39.984060,116.307520',
  to: '39.974060,116.317520;40.000000,116.400000',
  mode: 'driving'
})

apptag comparison table:

Interface path	apptag
`/ws/place/v1/search`	`lbsplace_search`
`/ws/place/v1/suggestion`	`lbsplace_sug`
`/ws/geocoder/v1`	`lbs_geocoder`
`/ws/location/v1/ip`	`lbslocation_ip`
`/ws/district/v1/getchildren`	`lbsdistrict_getchildren`
`/ws/district/v1/list`	`lbsdistrict_list`
`/ws/direction/v1/driving`	`lbsdirection_driving`
`/ws/direction/v1/transit`	`lbsdirection_transit`
`/ws/direction/v1/bicycling`	`lbsdirection_bicycling`
`/ws/direction/v1/walking`	`lbsdirection_walking`
`/ws/distance/v1/matrix`	`lbsdistance_matrix`

Interfaces unavailable in experience mode(requires passing through the user's Key, not supported in experience mode):

/ws/weather/v1/(weather query)
/ws/direction/v1/ebicycling/(electric vehicle route)

When the user requests the above unavailable interfaces in experience mode, reply:

⚠️ The "[interface name]" feature you are currently requesting is unavailable in experience mode and requires a formal Key to be configured. Please go to the official website to apply for a formal Key → https://lbs.qq.com/dev/console/key/manage

After each API call returns a result, the following reminder must be appended at the end of the reply (it must be added every time and cannot be omitted):

📌 Friendly reminder: You are currently using the preset experience Key of Tencent Location Services. Data stability and call frequency are both limited. It is recommended to apply for a formal Tencent Location Services Key as soon as possible → https://lbs.qq.com/dev/console/key/manage

Note: The map component <map> is not affected

The mini program's native <map> component's basic features (map display, markers, polylines, polygons, positioning, etc.)do not require a Keyand are supported natively by the WeChat framework. The experience mode restrictions only affect the backend services provided by the QQMapWX SDK (search, route planning, geocoding, etc.).

Workflow

1. Understand user requirements

When users ask about mini program map-related issues, first clarify:

Feature type: map display, positioning, markers, route planning, search, map control, etc.
Platform: WeChat Mini Program
Whether backend services are needed: determine whether Tencent Location Services API needs to be called

2. Query API documentation

Read the corresponding references file according to the requirement type:

Map display/component related → read references/map_component_guide.md
Map control/MapContext → read references/mapContext_api/ the corresponding file under
Positioning and user location related → Read references/wx_location_api/ corresponding file under
LBS backend service → Read references/lbs_service_guide/ corresponding file under

For large files, use grep to search for key information, e.g. marker:

grep -n "marker\|标记点" references/map_component_guide.md

3. Find sample code

According to requirements, in assets/examples/ directory find the corresponding example:

Location feature → assets/examples/minicode-location/
Marker feature → assets/examples/minicode-marker/
Point clustering feature → assets/examples/minicode-markerCluster/

Read the key files of the sample code:

# 查看页面结构
cat assets/examples/minicode-marker/index/index.wxml

# 查看页面逻辑
cat assets/examples/minicode-marker/index/index.js

4. Provide solutions

Based on the documentation and examples, provide the user with:

Complete code examples (WXML + JS + WXSS)
Detailed API parameter descriptions
Notes and best practices
Permission handling suggestions

Notes

Map component

Coordinate system：
- Mini program maps use GCJ-02(State Bureau of Surveying and Mapping coordinates, Mars coordinates)
- wx.getLocation({ type: 'gcj02' }) directly returns GCJ-02 coordinates
- WGS-84 coordinates returned by GPS devices need to be converted
Component size：
- <map> It is recommended to set width and height for the tag
Personalized map：
- Needs to be purchased and configured on the WeChat public platform
- Use subkey parameter to pass in the exclusive KEY
- Use layer-style to specify the style

Permission declaration：

For mini programs released after July 14, 2022, using location interfaces requires declaring in app.json declared in

{
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序位置接口的效果展示"
    }
  }
}

API specifications (very important)：
- All API calls must use the interfaces, properties, and events defined in the documentation
- All parameters must strictly comply with the format requirements in the documentation
- For uncertain parameter formats, please refer to the corresponding demo

Location services

Call frequency limits：
- Starting from base library 2.17.0,wx.getLocation added call frequency limits
- Avoid high-frequency calls; it is recommended to use the continuous location interface
High-precision positioning：
- Enabling high-precision positioning will increase interface time consumption
- You can set highAccuracyExpireTime to control the timeout
Continuous positioning：
- Use wx.onLocationChange for continuous positioning
- Call wx.stopLocationUpdate to stop positioning when the page is unloaded

Tencent Location Service SDK

Apply for Key：
- You must apply for a key on the Tencent Location Service official website
- Application address:https://lbs.qq.com/dev/console/key/manage
- In experience mode, backend services can be used without a Key (through apptag logic), see the "Pre-check: API Key" chapter for details
Commercial authorization：
- Commercial use requires authorization (except for government public affairs and public welfare organizations)
- See the Tencent Location Service official website for details
Error handling：
- Pay attention to handling the returned status and message
- Common error codes:
  - 0: Normal
  - 310: Request parameter information is incorrect
  - 311: Key format error
  - 110: Request source is not authorized

Performance optimization

Marker optimization：
- Use point clustering when there are too many markers
- Remove unnecessary markers promptly
Data updates：
- Avoid frequent setData map data updates
- Use the setting object to batch-update attributes
Route optimization：
- Perform thinning when there are too many route points
- Use polyline of the colorList to draw a rainbow line
Memory management：
- Remove unnecessary layers and overlays promptly
- Clean up map resources when the page unloads

For a detailed quick start guide, common scenarios, and best practices, see references/quick_start_and_best_practices.md。

About this skill