tencentmap-webservice-skill

Tencent Location Service WebService API

Tencent Location Service WebService API is a data interface based on the HTTPS/HTTP protocol, supporting calls from any programming language via HTTP requests.

Basic Information

Base URL: https://apis.map.qq.com
Request Method: GET
Response Format: JSON
Key Acquisition: https://lbs.qq.com/dev/console/key/manage

Key Considerations

Coordinate Format: uniformly use 纬度,经度 order (not longitude,latitude)
Coordinate System: GCJ-02 (National Bureau of Surveying and Mapping coordinate system), GPS raw coordinates must be converted first
Key Parameter: all interfaces require the key parameter
Quota Limits: each Key has a free quota and QPS limit

Trigger Conditions

Triggered when the user expresses any of the following intentions:

Convert an address to coordinates, or convert coordinates to an address
Search for places, POIs, nearby businesses
Use keyword input suggestions or autocomplete
Plan routes (driving, walking, cycling, electric bike, public transit, etc.)
Calculate distances in batch or generate a distance matrix
Query weather information
Get location based on IP
Extract addresses from unstructured text
Convert between different coordinate systems
Query administrative division information
Contains keywords such as "geocoding", "search", "route", "weather", "location", "coordinates", "distance matrix", etc.

Prerequisite Check: API Key

Check Steps

Check whether a formal Key already exists (environment variable TMAP_WEBSERVICE_KEY or already provided by the user in the conversation)
Case A: Formal Key detected

Silently record the Key,directly continue processing according to the user's original intention, 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, it is forbidden to perform any of the following operations:

Analyze user requirements

Read any files or documents

Plan an implementation approach

Write any code

Call any API

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 selection：

⚠️ You have not yet configured a formal Key. Please first choose your usage method:

Recommended: go to the official website to register and apply for a formal Key to enjoy complete and stable service 👉 https://lbs.qq.com/dev/console/key/manage After registration, it can be configured through the environment variable TMAP_WEBSERVICE_KEY=你的Key or by telling me in the conversation.

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

Access frequency limit: call frequency is restricted, and rate limiting is triggered after exceeding the limit

Data stability is average, not recommended for production environments

Interfaces such as weather query and electric vehicle routing are unavailable

Please tell me your choice:

Reply "I already have a Key" or directly provide a Key → switch to official mode

Reply "Use trial Key" → continue in Tencent Location Service restricted mode

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

User provides an official Key → record the Key, switch to official 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

Judgment principle: only interfaces that "do not need to pass through the user's Key" can use trial mode. Interfaces that need to pass through the user's Key are not supported in trial mode, and the user must be asked to configure an official Key before calling.

When calling trial mode interfaces, replace the request parameters according to the following rules:

Domain: replace https://apis.map.qq.com with https://h5gw.map.qq.com
Key parameter: set key=none
apptag parameter: look up the comparison table below according to the interface path, and fill in the corresponding apptag value

⚠️ Trial mode has CORS cross-origin restrictions

h5gw.map.qq.com does not allow direct browser-side fetch(including the localhost development environment). Trial mode must be called using JSONP, append output=jsonp&callback=函数名 parameter to the request, and initiate the request by dynamically inserting a <script> tag. Tencent Location Service WebService API natively supports JSONP callbacks.
// ✅ 体验模式：JSONP 方式（浏览器端可用）
function jsonpRequest(url, params, callback) {
  const cbName = 'tmap_cb_' + Date.now();
  params.output = 'jsonp';
  params.callback = cbName;
  const query = Object.entries(params)
    .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
    .join('&');
  window[cbName] = (data) => {
    delete window[cbName];
    script.remove();
    callback(data);
  };
  const script = document.createElement('script');
  script.src = `${url}?${query}`;
  document.head.appendChild(script);
}

// 示例：体验模式 IP 定位
jsonpRequest(
  'https://h5gw.map.qq.com/ws/location/v1/ip',
  {
    key: 'none',
    apptag: 'lbslocation_ip',
  },
  (res) => console.log(res)
);
❌ It is not recommended to use JSONP in official Key mode: JSONP exposes the Key in plaintext in frontend code, posing a risk of Key leakage. Official Keys should be forwarded through aserver-side proxyto avoid direct calls from the browser side.

apptag comparison table:

Official website tool-type interfaces (lbs*)

Interface path	apptag
`/ws/place/v1/search`	`lbsplace_search`
`/ws/place/v1/explore`	`lbsplace_explore`
`/ws/place/v1/detail`	`lbsplace_detail`
`/ws/place/v1/suggestion`	`lbsplace_sug`
`/ws/geocoder/v1`	`lbs_geocoder`
`/ws/location/v1/ip`	`lbslocation_ip`
`/ws/coord/v1/translate`	`lbscoord_translate`
`/ws/district/v1/getchildren`	`lbsdistrict_getchildren`
`/ws/district/v1/search`	`lbsdistrict_search`
`/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 trial mode(these interfaces need to pass through the user's own Key, and trial mode cannot support them):

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

When the user requests the above unavailable interfaces in trial mode, reply with the following content and stop, waiting for the user's choice:

⚠️ The "[Interface Name]" feature you are currently requesting is unavailable in trial mode and requires an official Key to be configured before it can be called. Please go to the official website to apply for an official Key → https://lbs.qq.com/dev/console/key/manage After applying, tell me your Key, and you can switch to official mode and continue using it.

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 trial Key of Tencent Location Service, and both data stability and call frequency are limited. It is recommended to apply for an official Tencent Location Service Key as soon as possible → https://lbs.qq.com/dev/console/key/manage

Scenario determination

After receiving the user's request, first determine which scenario it belongs to:

Scenario	User intent	Reference documentation
Address service	Address ↔ coordinate conversion, intelligent address parsing	`references/api-geocoder.md`
Search service	Place search, nearby POI, along-route search, input suggestions, administrative divisions	`references/api-search.md`
Route service	Driving/walking/cycling/transit route planning, distance matrix	`references/api-direction.md`
Geolocation and weather	IP geolocation, weather query	`references/api-location-weather.md`
Coordinate conversion	Convert other coordinate systems to Tencent Map coordinate system	`references/api-tools.md`

Combined scenario handling

If a user request contains multiple scenarios, chain the calls in the following priority order:

First resolve coordinate acquisition: address resolution / IP geolocation / coordinate conversion — ensure subsequent operations have usable coordinates
Then execute the target operation: search / route planning / weather query — use the coordinates obtained in the first step
Finally handle follow-up operations: along-route search depends on the route result's polyline, and the distance matrix depends on the coordinate set

Scenario one: Address service

Provides three capabilities: address resolution (address → coordinates), reverse address resolution (coordinates → address), and smart address resolution (unstructured text → structured address).

Address resolution: GET /ws/geocoder/v1/ — pass in the address parameter; it is recommended to add region to improve accuracy
Reverse address resolution: GET /ws/geocoder/v1/ — pass in the location parameter (latitude,longitude); you can use get_poi=1 to return nearby POIs
Smart address resolution: GET /ws/geocoder/v1/ — use the smart_address parameter (not address) to extract address and contact information from text such as shipping labels and chat records. Requires enterprise verification to enable

📖 For detailed parameters, response format, and examples, see references/api-geocoder.md

Scenario two: Search service

Provides four capabilities: place search, along-route search, keyword input suggestions, and administrative division query.

Place search: GET /ws/place/v1/search — supports nearby()/region()/rectangle() boundary formats (polygon search is a separate API /ws/place/v1/search_by_polygon）
Along-route search: GET /ws/place/v1/search — use boundary=along(polyline, distance); the route polyline must be obtained first
Keyword suggestions: GET /ws/place/v1/suggestion — search box autocomplete
Administrative divisions: three sub-APIs — GET /ws/district/v1/list(full list),/getchildren(subordinate divisions),/search(keyword search)

📖 For detailed parameters, response format, and examples, see references/api-search.md

Scenario three: Route service

Provides route planning and batch distance calculation capabilities.

Travel mode	Endpoint
Driving	`GET /ws/direction/v1/driving/`
Walking	`GET /ws/direction/v1/walking/`
Cycling	`GET /ws/direction/v1/bicycling/`
Electric bike	`GET /ws/direction/v1/ebicycling/`
Transit	`GET /ws/direction/v1/transit/`
Distance matrix	`GET /ws/distance/v1/matrix`

All route APIs require from(origin) and to(destination), in the format 纬度,经度
Driving supports waypoints(waypoints) and policy(strategy: LEAST_TIME/PICKUP/TRIP + preference: REAL_TRAFFIC/LEAST_FEE/AVOID_HIGHWAY/HIGHWAY_FIRST, etc., comma-separated)
Driving duration unit isminutes, distance matrix duration unit isseconds
Distance matrix supports mode（driving/walking/bicycling）

📖 For detailed parameters, response format, and examples, see references/api-direction.md

Scenario four: Geolocation and weather

Provides IP location and weather query capabilities.

IP location: GET /ws/location/v1/ip — accurate to city level
Weather query: GET /ws/weather/v1/ — supports adcode or location query,type parameter selects now(current conditions)/future(forecast)/hours(hourly), via added_fields append alarm/index/air (comma-separated)

📖 For detailed parameters, response format, and examples, see references/api-location-weather.md

Scenario 5: Coordinate Conversion

GET /ws/coord/v1/translate — Converts GPS/Baidu/Sogou/MapBar coordinates to the Tencent Map coordinate system (GCJ-02).Only one-way conversion in is supported, reverse conversion out is not supported.

📖 For detailed parameters and examples, see references/api-tools.md

Error Handling

In the JSON returned by all APIs, the status field indicates the business status code. For the complete error code reference:https://lbs.qq.com/service/webService/webServiceGuide/status

Common Error Codes

Status Code	Meaning	Suggested Action
`0`	Success	—
`110`	Request origin is not authorized	Check the Key's domain whitelist or IP whitelist configuration
`111`	Signature verification failed	Check the signature algorithm and Secret Key
`112`	IP is not authorized	Add the server IP to the whitelist in the console
`113`	This feature is not authorized	Enable the corresponding API permission in the console
`120`	QPS limit (requests per second reached the upper limit)	Wait 1-2 seconds and retry, or merge requests
`121`	Daily call volume reached the upper limit	Upgrade the quota or change the Key
`190`	Invalid Key	Confirm whether the Key has been deleted or disabled
`199`	WebService functionality is not enabled for this Key	Enable WebService for the Key in the console

Parameter Error

Status Code	Meaning	Suggested Action
`300`	Missing required field	Check whether all required parameters are provided
`301`	Missing key parameter	Add `key` parameter
`306`	Missing parameter	Check the required parameters for the API
`310`	Parameter format error	Check the parameter type and format (such as coordinate format)
`311`	Key format error	Check whether the Key is correct
`320`	Parameter data type error	Check the parameter value type
`326`	Start and end points are too close	The start and end coordinates are the same or too close
`332`	Number of waypoints exceeds the limit	Driving supports at most 10 waypoints
`333`	There are coordinate points that cannot be snapped	Check whether the coordinates are near a passable road
`347`	Query returned no results	Try relaxing the search conditions or changing the keywords
`365`	Latitude cannot exceed ±90	Check the coordinate value range
`366`	Longitude cannot exceed ±180	Check the coordinate value range
`373`	Start and end points are too far apart	Reduce the distance between the start and end points
`375`	LAN IP cannot be located	IP location only supports public IPs
`396`	Distance matrix coordinate points exceed the limit	At most 200 coordinate points, and the product of the number of origins and destinations is at most 625

System error

Status code	Meaning	Suggested handling
`500`	Backend timeout	Retry later
`510`	Unable to connect to the backend service	Retry later
`520`	Backend service request failed	Retry later
`530`	Failed to parse data returned by the backend	Retry later; if it persists, contact customer service

Best practices

Specify for address parsing region — improve accuracy and avoid cross-city ambiguity

# ✅ 指定城市
GET /ws/geocoder/v1/?address=中关村大街1号&region=北京&key=YOUR_KEY
# ❌ 不指定城市，可能匹配到其他城市的同名地址
GET /ws/geocoder/v1/?address=中关村大街1号&key=YOUR_KEY

Choose an appropriate policy for reverse address parsing — obtain the most relevant address description based on the business scenario

# 到家场景（精确到楼栋）
GET /ws/geocoder/v1/?location=39.984154,116.307490&get_poi=1&poi_options=policy=2&key=YOUR_KEY
# 出行场景（过滤不易到达 POI）
GET /ws/geocoder/v1/?location=39.984154,116.307490&get_poi=1&poi_options=policy=3&key=YOUR_KEY

For search, use boundary to limit the scope — improve search precision and efficiency

For batch distance calculation, use the distance matrix instead of calling in a loop — significantly reduce the number of requests

# ❌ 错误：循环调用路线接口，N*M 次请求
for origin in origins:
    for dest in destinations:
        call_direction_api(origin, dest)

# ✅ 正确：一次距离矩阵请求
call_distance_matrix(from=";".join(origins), to=";".join(destinations), mode="driving")

GPS coordinates need to be converted first — convert to GCJ-02 via the coordinate conversion API before calling other APIs

# 先转换坐标
GET /ws/coord/v1/translate?locations=39.984154,116.307490&type=1&key=YOUR_KEY
# 再用转换后的坐标调用搜索/路线等接口

For weather queries, prefer longitude and latitude — can be accurate to the district/county level, more flexible than adcode
For along-route search, plan the route first — first obtain the polyline, then search for POIs; do not skip the route planning step

Document references

File	Description
references/api-geocoder.md	Address parsing, reverse address parsing, intelligent address parsing
references/api-search.md	Place search, along-route search, keyword suggestions, administrative divisions
references/api-direction.md	Route planning (driving/walking/cycling/transit), distance matrix
references/api-location-weather.md	IP location, weather query
references/api-tools.md	Coordinate conversion, common error codes

About this skill